Merge branch 'main' into ecs-proto

CHANGELOG.md

@@ -15,6 +15,14 @@ release.
 
 - Add experimental histogram advice API.
   ([#3216](https://github.com/open-telemetry/opentelemetry-specification/pull/3216))
+- Recommended cardinality limits to protect metrics pipelines against
+  excessive data production from a single instrument.
+  ([#2960](https://github.com/open-telemetry/opentelemetry-specification/pull/2960))
+- Specify second unit (`s`) and advice bucket boundaries of `[]`
+  for `process.runtime.jvm.gc.duration`.
+  ([#3458](https://github.com/open-telemetry/opentelemetry-specification/pull/3458))
+- Add links to the JMX APIs that are the JVM runtime metric sources.
+  ([#3463](https://github.com/open-telemetry/opentelemetry-specification/pull/3463))
 
 ### Logs
 
@@ -47,6 +55,9 @@ release.
   ([#3390](https://github.com/open-telemetry/opentelemetry-specification/pull/3390))
 - BREAKING: Remove `messaging.consumer.id`, make `messaging.client_id` generic
   ([#3336](https://github.com/open-telemetry/opentelemetry-specification/pull/3336))
+- Add transition plan for upcoming breaking changes to the unstable HTTP semantic
+  conventions.
+  ([#3443](https://github.com/open-telemetry/opentelemetry-specification/pull/3443))
 - BREAKING: Adopt ECS attributes in HTTP semantic conventions.
   Renames: `http.method` to `http.request.method`,
   `http.status_code` to `http.response.status_code`,

semantic_conventions/metrics/process-runtime-jvm-metrics.yaml

@@ -70,7 +70,7 @@ groups:
     metric_name: process.runtime.jvm.gc.duration
     brief: "Duration of JVM garbage collection actions."
     instrument: histogram
-    unit: "ms"
+    unit: "s"
     attributes:
       - id: gc
         type: string

specification/README.md

@@ -1,5 +1,5 @@
 <!--- Hugo front matter used to generate the website version of this page:
-linkTitle: Specification
+linkTitle: OTel spec
 no_list: true
 cascade:
   body_class: otel-docs-spec

specification/metrics/sdk.md

@@ -30,6 +30,9 @@ linkTitle: SDK
         * [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)
+  * [Cardinality limits](#cardinality-limits)
+    + [Synchronous instrument cardinality limits](#synchronous-instrument-cardinality-limits)
+    + [Asynchronous instrument cardinality limits](#asynchronous-instrument-cardinality-limits)
 - [Meter](#meter)
   * [Duplicate instrument registration](#duplicate-instrument-registration)
   * [Instrument name](#instrument-name)
@@ -235,6 +238,12 @@ are the inputs:
     `exemplar_reservoir` (optional) to use for storing exemplars. This should be
     a factory or callback similar to aggregation which allows different
     reservoirs to be chosen by the aggregation.
+  * **Status**: [Experimental](../document-status.md) - the
+    `aggregation_cardinality_limit` (optional) associated with the view.  This
+    should be a positive integer to be taken as a hard limit on the
+    number of data points that will be emitted during a single
+    collection by a single instrument.  See [cardinality limits](#cardinality-limits),
+    below.
 
 In order to avoid conflicts, views which specify a name SHOULD have an
 instrument selector that selects at most one instrument. For the registration
@@ -582,6 +591,62 @@ execution.
 The implementation MUST complete the execution of all callbacks for a
 given instrument before starting a subsequent round of collection.
 
+### Cardinality limits
+
+**Status**: [Experimental](../document-status.md)
+
+Views SHOULD support being configured with a cardinality limit to be
+applied to all aggregators not configured by a specific view, specified
+via `MetricReader` configuration.
+
+View configuration SHOULD support applying per-aggregation cardinality limits.
+
+The cardinality limit is taken as an exact, hard limit on the number
+of data points that can be written per collection, per aggregation.
+Each aggregation configured view MUST NOT output more than the
+configured `aggregation_cardinality_limit` number of data points per
+period.
+
+The RECOMMENDED default aggregation cardinality limit is 2000.
+
+An overflow attribute set is defined, containing a single attribute
+`otel.metric.overflow` having (boolean) value `true`, which is used to
+report a synthetic aggregation of the metric events that could not be
+independently aggregated because of the limit.
+
+The SDK MUST create an Aggregator with the overflow attribute set
+prior to reaching the cardinality limit and use it to aggregate events
+for which the correct Aggregator could not be created.  The maximum
+number of distinct, non-overflow attributes is one less than the
+limit, as a result.
+
+#### Synchronous instrument cardinality limits
+
+Views of synchronous instruments with cumulative aggregation
+temporality MUST continue to export the all attribute sets that were
+observed prior to the beginning of overflow.  Metric events
+corresponding with attribute sets that were not observed prior to the
+overflow will be reflected in a single data point described by (only)
+the overflow attribute.
+
+Views of synchronous instruments with delta aggregation temporality
+MAY choose an arbitrary subset of attribute sets to output to maintain
+the stated cardinality limit.
+
+Regardless of aggregation temporality, the SDK MUST ensure that every
+metric event is reflected in exactly one Aggregator, which is either
+an Aggregator associated with the correct attribute set or an
+aggregator associated with the overflow attribute set.
+
+Events MUST NOT be double-counted or dropped during an
+overflow.
+
+#### Asynchronous instrument cardinality limits
+
+Views of asynchronous instruments SHOULD prefer the first-observed
+attributes in the callback when limiting cardinality, regardless of
+aggregation temporality.
+
 ## Meter
 
 Distinct meters MUST be treated as separate namespaces for the purposes of detecting
@@ -862,6 +927,7 @@ SHOULD provide at least the following:
 * The `exporter` to use, which is a `MetricExporter` instance.
 * The default output `aggregation` (optional), a function of instrument kind.  If not configured, the [default aggregation](#default-aggregation) SHOULD be used.
 * The default output `temporality` (optional), a function of instrument kind.  If not configured, the Cumulative temporality SHOULD be used.
+* The default aggregation cardinality limit to use, a function of instrument kind.  If not configured, a default value of 2000 SHOULD be used.
 
 The [MetricReader.Collect](#collect) method allows general-purpose
 `MetricExporter` instances to explicitly initiate collection, commonly

specification/metrics/semantic_conventions/README.md

@@ -41,6 +41,8 @@ Conventions](../../resource/semantic_conventions/README.md).
 
 ## General Guidelines
 
+**Status**: [Experimental](../../document-status.md)
+
 Metric names and attributes exist within a single universe and a single
 hierarchy. Metric names and attributes MUST be considered within the universe of
 all existing metric names. When defining new metric names and attributes,
@@ -125,12 +127,16 @@ to the processes then to represent the count of the processes we can have a metr
 
 ## General Metric Semantic Conventions
 
+**Status**: [Mixed](../../document-status.md)
+
 The following semantic conventions aim to keep naming consistent. They
 provide guidelines for most of the cases in this specification and should be
 followed for other instruments not explicitly defined in this document.
 
 ### Instrument Naming
 
+**Status**: [Experimental](../../document-status.md)
+
 - **limit** - an instrument that measures the constant, known total amount of
 something should be called `entity.limit`. For example, `system.memory.limit`
 for the total amount of memory on a system.
@@ -209,6 +215,8 @@ implementation detail. Both choices are compliant with this specification.
 
 ### Consistent UpDownCounter timeseries
 
+**Status**: [Experimental](../../document-status.md)
+
 When recording `UpDownCounter` metrics, the same attribute values used to record an increment SHOULD be used to record
 any associated decrement, otherwise those increments and decrements will end up as different timeseries.
 

specification/metrics/semantic_conventions/http-metrics.md

@@ -26,6 +26,30 @@ operations. By adding HTTP attributes to metric events it allows for finely tune
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing HTTP instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/http-metrics.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the HTTP or networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in HTTP instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which supports the following values:
+>   * `none` - continue emitting whatever version of the old experimental
+>     HTTP and networking attributes the instrumentation was emitting previously.
+>     This is the default value.
+>   * `http` - emit the new, stable HTTP and networking attributes,
+>     and stop emitting the old experimental HTTP and networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable HTTP and networking attributes,
+>     allowing for a seamless transition.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## HTTP Server
 
 ### Metric: `http.server.duration`

specification/metrics/semantic_conventions/rpc-metrics.md

@@ -28,6 +28,30 @@ metrics can be filtered for finer grain analysis.
 
 <!-- tocstop -->
 
+> **Warning**
+> Existing RPC instrumentations that are using
+> [v1.20.0 of this document](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.20.0/specification/metrics/semantic_conventions/rpc-metrics.md)
+> (or prior):
+>
+> * SHOULD NOT change the version of the networking attributes that they emit
+>   until the HTTP semantic conventions are marked stable (HTTP stabilization will
+>   include stabilization of a core set of networking attributes which are also used
+>   in RPC instrumentations).
+> * SHOULD introduce an environment variable `OTEL_SEMCONV_STABILITY_OPT_IN`
+>   in the existing major version which supports the following values:
+>   * `none` - continue emitting whatever version of the old experimental
+>     networking attributes the instrumentation was emitting previously.
+>     This is the default value.
+>   * `http` - emit the new, stable networking attributes,
+>     and stop emitting the old experimental networking attributes
+>     that the instrumentation emitted previously.
+>   * `http/dup` - emit both the old and the stable networking attributes,
+>     allowing for a seamless transition.
+> * SHOULD maintain (security patching at a minimum) the existing major version
+>   for at least six months after it starts emitting both sets of attributes.
+> * SHOULD drop the environment variable in the next major version (stable
+>   next major version SHOULD NOT be released prior to October 1, 2023).
+
 ## Metric instruments
 
 The following metric instruments MUST be used to describe RPC operations. They