Merge branch 'main' into start-time-prom-otlp

Signed-off-by: Goutham Veeramachaneni <[email protected]>
open-telemetry · Jul 13, 2022 · 21cbec7 · 21cbec7
2 parents 00281c0 + 0b8aa6a
commit 21cbec7
Show file tree

Hide file tree

Showing 27 changed files with 61 additions and 43 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -13,12 +13,15 @@ release.
 
 - Clarify the return of `Export(batch)` in the Batch Span Processor and exporter
  concurrency ([#2452](https:/open-telemetry/opentelemetry-specification/pull/2452))
+- Clarify that Context should not be mutable when setting a span ([#2637](https:/open-telemetry/opentelemetry-specification/pull/2637))
 
 ### Metrics
 
 - Add experimental `OTEL_EXPORTER_OTLP_DEFAULT_HISTOGRAM_AGGREGATION` variable for
  configuring default histogram aggregation of OTLP metric exporter
  ([#2619](https:/open-telemetry/opentelemetry-specification/pull/2619)).
+- Clarify async instrument callback identity.
+ ([#2538](https:/open-telemetry/opentelemetry-specification/pull/2538)).
 
 ### Logs
 

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -268,7 +268,7 @@ Note: Support for environment variables is optional.
 |Feature |Go | Java |JS |Python|Ruby|Erlang|PHP|Rust|C++|.NET|Swift|
 |--------------------------------------------------|---|------|---|------|----|------|---|----|---|----|-----|
 |OTEL_RESOURCE_ATTRIBUTES | + | + | + | + | + | + | + | + | + | + | - |
-|OTEL_SERVICE_NAME | + | + |   | | + | + | + | | | + | |
+|OTEL_SERVICE_NAME | + | + | + | | + | + | + | | | + | |
 |OTEL_LOG_LEVEL | - | - | + | [-][py1059] | + | - | - | | - | - | - |
 |OTEL_PROPAGATORS | - | + | | + | + | + | - | - | - | - | - |
 |OTEL_BSP_* | + | + | | + | + | + | - | + | - | - | - |

diff --git a/specification/README.md b/specification/README.md
@@ -1,3 +1,14 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Specification
+no_list: true
+cascade:
+ body_class: otel-docs-spec
+ github_repo: &repo https:/open-telemetry/opentelemetry-specification
+ github_subdir: specification
+ path_base_for_github_subdir: content/en/docs/reference/specification/
+ github_project_repo: *repo
+--->
+
 # OpenTelemetry Specification
 
 ## Contents

diff --git a/specification/common/README.md b/specification/common/README.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 aliases: [/docs/reference/specification/common/common]
 --->
 # Common specification concepts

diff --git a/specification/context/README.md b/specification/context/README.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 aliases: [/docs/reference/specification/context/context]
 --->
 # Context

diff --git a/specification/logs/README.md b/specification/logs/README.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Logs
 aliases: [/docs/reference/specification/logs/overview]
 --->

diff --git a/specification/metrics/README.md b/specification/metrics/README.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Metrics
 --->
 

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: API
 --->
 
@@ -366,9 +366,9 @@ Where the API supports registration of `callback` functions after
 asynchronous instrumentation creation, the user MUST be able to undo
 registration of the specific callback after its registration by some means.
 
-Every currently registered Callback associated with an instrument MUST
+Every currently registered Callback associated with a set of instruments MUST
 be evaluated exactly once during collection prior to reading data for
-that instrument.
+that instrument set.
 
 Callback functions MUST be documented as follows for the end user:
 

diff --git a/specification/metrics/data-model.md b/specification/metrics/data-model.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Data Model
 --->
 
@@ -1341,8 +1341,8 @@ An [OpenTelemetry Gauge](#gauge) MUST be converted to a Prometheus Gauge.
  - The new data point's start time must match the time of the accumulated data point. If not, see [detecting alignment issues].(#sums-detecting-alignment-issues).
 - Otherwise, it MUST be dropped.
 
-Sum metric points MUST have `_total` added as a suffix to the metric name.
-Monotonic Sums metric points with `StartTimeUnixNano` should export the `{name}_created` metric as well.
+Monotonic Sum metric points MUST have `_total` added as a suffix to the metric name.
+Monotonic Sum metric points with `StartTimeUnixNano` should export the `{name}_created` metric as well.
 
 #### Histograms
 

diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: SDK
 --->
 
@@ -21,13 +21,13 @@ linkTitle: SDK
  + [Default Aggregation](#default-aggregation)
  + [Sum Aggregation](#sum-aggregation)
  + [Last Value Aggregation](#last-value-aggregation)
-  - [Histogram Aggregation common behavior](#histogram-aggregation-common-behavior)
- + [Explicit Bucket Histogram Aggregation](#explicit-bucket-histogram-aggregation)
- + [Exponential Bucket Histogram Aggregation](#exponential-bucket-histogram-aggregation)
- - [Exponential Bucket Histogram Aggregation: Handle all normal values](#exponential-bucket-histogram-aggregation-handle-all-normal-values)
- - [Exponential Bucket Histogram Aggregation: Support a minimum and maximum scale](#exponential-bucket-histogram-aggregation-support-a-minimum-and-maximum-scale)
- - [Exponential Bucket Histogram Aggregation: Use the maximum scale for single measurements](#exponential-bucket-histogram-aggregation-use-the-maximum-scale-for-single-measurements)
- - [Exponential Bucket Histogram Aggregation: Maintain the ideal scale](#exponential-bucket-histogram-aggregation-maintain-the-ideal-scale)
+ + [Histogram Aggregations](#histogram-aggregations)
+  - [Explicit Bucket Histogram Aggregation](#explicit-bucket-histogram-aggregation)
+  - [Exponential Bucket Histogram Aggregation](#exponential-bucket-histogram-aggregation)
+  * [Handle all normal values](#handle-all-normal-values)
+  * [Support a minimum and maximum scale](#support-a-minimum-and-maximum-scale)
+  * [Use the maximum scale for single measurements](#use-the-maximum-scale-for-single-measurements)
+  * [Maintain the ideal scale](#maintain-the-ideal-scale)
  * [Observations inside asynchronous callbacks](#observations-inside-asynchronous-callbacks)
  * [Resolving duplicate instrument registration conflicts](#resolving-duplicate-instrument-registration-conflicts)
 - [Attribute limits](#attribute-limits)
@@ -410,7 +410,7 @@ This Aggregation informs the SDK to collect:
 - The last `Measurement`.
 - The timestamp of the last `Measurement`.
 
-##### Histogram Aggregation common behavior
+#### Histogram Aggregations
 
 All histogram Aggregations inform the SDK to collect:
 
@@ -420,7 +420,7 @@ instruments that record negative measurements (e.g. `UpDownCounter` or `Observab
 - Min (optional) `Measurement` value in population.
 - Max (optional) `Measurement` value in population.
 
-#### Explicit Bucket Histogram Aggregation
+##### Explicit Bucket Histogram Aggregation
 
 The Explicit Bucket Histogram Aggregation informs the SDK to collect data for
 the [Histogram Metric Point](./data-model.md#histogram) using a set of
@@ -439,7 +439,7 @@ bound (except at positive infinity). A measurement is defined to fall
 into the greatest-numbered bucket with boundary that is greater than
 or equal to the measurement.
 
-#### Exponential Bucket Histogram Aggregation
+##### Exponential Bucket Histogram Aggregation
 
 The Exponential Histogram Aggregation informs the SDK to collect data
 for the [Exponential Histogram Metric
@@ -491,7 +491,7 @@ either:
 1. The maximum supported scale, generally used for single-value histogram Aggregations where scale is not otherwise constrained
 2. The largest value of scale such that no more than the maximum number of buckets are needed to represent the full range of input data in either of the positive or negative ranges.
 
-##### Exponential Bucket Histogram Aggregation: Handle all normal values
+###### Handle all normal values
 
 Implementations are REQUIRED to accept the entire normal range of IEEE
 floating point values (i.e., all values except for +Inf, -Inf and NaN
@@ -504,18 +504,18 @@ values do not map into a valid bucket.
 Implementations MAY round subnormal values away from zero to the
 nearest normal value.
 
-##### Exponential Bucket Histogram Aggregation: Support a minimum and maximum scale
+###### Support a minimum and maximum scale
 
 The implementation MUST maintain reasonable minimum and maximum scale
 parameters that the automatic scale parameter will not exceed.
 
-##### Exponential Bucket Histogram Aggregation: Use the maximum scale for single measurements
+###### Use the maximum scale for single measurements
 
 When the histogram contains not more than one value in either of the
 positive or negative ranges, the implementation SHOULD use the maximum
 scale.
 
-##### Exponential Bucket Histogram Aggregation: Maintain the ideal scale
+###### Maintain the ideal scale
 
 Implementations SHOULD adjust the histogram scale as necessary to
 maintain the best resolution possible, within the constraint of

diff --git a/specification/metrics/sdk_exporters/README.md b/specification/metrics/sdk_exporters/README.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Exporters
 --->
 

diff --git a/specification/metrics/sdk_exporters/in-memory.md b/specification/metrics/sdk_exporters/in-memory.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: In-memory
 --->
 

diff --git a/specification/metrics/sdk_exporters/otlp.md b/specification/metrics/sdk_exporters/otlp.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: OTLP
 --->
 

diff --git a/specification/metrics/sdk_exporters/prometheus.md b/specification/metrics/sdk_exporters/prometheus.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Prometheus
 --->
 

diff --git a/specification/metrics/sdk_exporters/stdout.md b/specification/metrics/sdk_exporters/stdout.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Stdout
 --->
 

diff --git a/specification/metrics/semantic_conventions/README.md b/specification/metrics/semantic_conventions/README.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Semantic Conventions
 --->
 

diff --git a/specification/metrics/semantic_conventions/database-metrics.md b/specification/metrics/semantic_conventions/database-metrics.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Database
 --->
 

diff --git a/specification/metrics/semantic_conventions/faas-metrics.md b/specification/metrics/semantic_conventions/faas-metrics.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: FaaS
 --->
 

diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: HTTP
 --->
 

diff --git a/specification/metrics/semantic_conventions/instrumentation/kafka.md b/specification/metrics/semantic_conventions/instrumentation/kafka.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Kafka
 --->
 

diff --git a/specification/metrics/semantic_conventions/openmetrics-guidelines.md b/specification/metrics/semantic_conventions/openmetrics-guidelines.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: OpenMetrics
 --->
 

diff --git a/specification/metrics/semantic_conventions/process-metrics.md b/specification/metrics/semantic_conventions/process-metrics.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Process
 --->
 

diff --git a/specification/metrics/semantic_conventions/rpc.md b/specification/metrics/semantic_conventions/rpc.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: RPC
 --->
 

diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: Runtime Environment
 --->
 

diff --git a/specification/metrics/semantic_conventions/system-metrics.md b/specification/metrics/semantic_conventions/system-metrics.md
@@ -1,4 +1,4 @@
-<!---
+<!--- Hugo front matter used to generate the website version of this page:
 linkTitle: System
 --->
 

diff --git a/specification/overview.md b/specification/overview.md
@@ -1,3 +1,7 @@
+<!--- Hugo front matter used to generate the website version of this page:
+weight: 1
+--->
+
 # Overview
 
 <details>

diff --git a/specification/trace/api.md b/specification/trace/api.md
@@ -163,7 +163,7 @@ The API MUST provide the following functionality to interact with a `Context`
 instance:
 
 - Extract the `Span` from a `Context` instance
-- Insert the `Span` to a `Context` instance
+- Combine the `Span` with a `Context` instance, creating a new `Context` instance
 
 The functionality listed above is necessary because API users SHOULD NOT have
 access to the [Context Key](../context/README.md#create-a-key) used by the Tracing API implementation.
@@ -173,7 +173,7 @@ If the language has support for implicitly propagated `Context` (see
 the following functionality:
 
 - Get the currently active span from the implicit context. This is equivalent to getting the implicit context, then extracting the `Span` from the context.
-- Set the currently active span to the implicit context. This is equivalent to getting the implicit context, then inserting the `Span` to the context.
+- Set the currently active span into a new context, and make that the implicit context. This is equivalent to combining the current implicit context's values with the `Span` to create a new context, which is then made the current implicit context.
 
 All the above functionalities operate solely on the context API, and they MAY be
 exposed as either static methods on the trace module, or as static methods on a class