diff --git a/CHANGELOG.md b/CHANGELOG.md index 0bc0648f16a..93072979516 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ release. ### Metrics +- Add the OptIn advisory parameter. + ([#4809](https://github.com/open-telemetry/opentelemetry-specification/pull/4809)) + ### Logs ### Baggage diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 116a3b786cc..23cc47f9d94 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -130,6 +130,7 @@ formats is required. Implementing more than one format is optional. | Instrument descriptions conform to the specified syntax. | | - | + | | - | + | + | | | - | + | | | Instrument supports the advisory ExplicitBucketBoundaries parameter. | | + | + | | | | + | | | | | | | Instrument supports the advisory Attributes parameter. | | - | + | | | | + | | | | | | +| Instrument supports the advisory OptIn parameter. | | - | - | - | - | - | - | - | - | - | - | - | | All methods of `MeterProvider` are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | | All methods of `Meter` are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | | All methods of any instrument are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | diff --git a/spec-compliance-matrix/cpp.yaml b/spec-compliance-matrix/cpp.yaml index 65ae3abfe76..cba61a615ac 100644 --- a/spec-compliance-matrix/cpp.yaml +++ b/spec-compliance-matrix/cpp.yaml @@ -223,6 +223,8 @@ sections: status: '?' - name: Instrument supports the advisory Attributes parameter. status: '?' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '+' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/dotnet.yaml b/spec-compliance-matrix/dotnet.yaml index f5d51a066d3..da8a933b50b 100644 --- a/spec-compliance-matrix/dotnet.yaml +++ b/spec-compliance-matrix/dotnet.yaml @@ -223,6 +223,8 @@ sections: status: '?' - name: Instrument supports the advisory Attributes parameter. status: '?' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '+' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/erlang.yaml b/spec-compliance-matrix/erlang.yaml index 7d5d680d6a5..e42d3231bef 100644 --- a/spec-compliance-matrix/erlang.yaml +++ b/spec-compliance-matrix/erlang.yaml @@ -223,6 +223,8 @@ sections: status: '+' - name: Instrument supports the advisory Attributes parameter. status: '+' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '+' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/go.yaml b/spec-compliance-matrix/go.yaml index 7b3fb26a4b6..c79d6474093 100644 --- a/spec-compliance-matrix/go.yaml +++ b/spec-compliance-matrix/go.yaml @@ -223,6 +223,8 @@ sections: status: '+' - name: Instrument supports the advisory Attributes parameter. status: '-' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '+' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/java.yaml b/spec-compliance-matrix/java.yaml index e3fe29f9ad3..33fec46a511 100644 --- a/spec-compliance-matrix/java.yaml +++ b/spec-compliance-matrix/java.yaml @@ -223,6 +223,8 @@ sections: status: '+' - name: Instrument supports the advisory Attributes parameter. status: '+' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '+' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/js.yaml b/spec-compliance-matrix/js.yaml index a7154980e30..3739111b8b0 100644 --- a/spec-compliance-matrix/js.yaml +++ b/spec-compliance-matrix/js.yaml @@ -223,6 +223,8 @@ sections: status: '?' - name: Instrument supports the advisory Attributes parameter. status: '?' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '+' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/php.yaml b/spec-compliance-matrix/php.yaml index 1d506cafd6f..8e7587015ce 100644 --- a/spec-compliance-matrix/php.yaml +++ b/spec-compliance-matrix/php.yaml @@ -223,6 +223,8 @@ sections: status: '?' - name: Instrument supports the advisory Attributes parameter. status: '?' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '?' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/python.yaml b/spec-compliance-matrix/python.yaml index 9c686be08a1..592a02cf991 100644 --- a/spec-compliance-matrix/python.yaml +++ b/spec-compliance-matrix/python.yaml @@ -223,6 +223,8 @@ sections: status: '?' - name: Instrument supports the advisory Attributes parameter. status: '?' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '-' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/ruby.yaml b/spec-compliance-matrix/ruby.yaml index 0c690c00109..7acb5e6a3d3 100644 --- a/spec-compliance-matrix/ruby.yaml +++ b/spec-compliance-matrix/ruby.yaml @@ -223,6 +223,8 @@ sections: status: '?' - name: Instrument supports the advisory Attributes parameter. status: '?' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '?' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/rust.yaml b/spec-compliance-matrix/rust.yaml index 1f3cb6913f3..c85d7f1eebb 100644 --- a/spec-compliance-matrix/rust.yaml +++ b/spec-compliance-matrix/rust.yaml @@ -223,6 +223,8 @@ sections: status: '?' - name: Instrument supports the advisory Attributes parameter. status: '?' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '?' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/swift.yaml b/spec-compliance-matrix/swift.yaml index 5ff118465d6..5dde92f7475 100644 --- a/spec-compliance-matrix/swift.yaml +++ b/spec-compliance-matrix/swift.yaml @@ -223,6 +223,8 @@ sections: status: '?' - name: Instrument supports the advisory Attributes parameter. status: '?' + - name: Instrument supports the advisory OptIn parameter. + status: '-' - name: All methods of `MeterProvider` are safe to be called concurrently. status: '?' - name: All methods of `Meter` are safe to be called concurrently. diff --git a/spec-compliance-matrix/template.yaml b/spec-compliance-matrix/template.yaml index 3013f98e178..ac6fba7c328 100644 --- a/spec-compliance-matrix/template.yaml +++ b/spec-compliance-matrix/template.yaml @@ -155,6 +155,7 @@ sections: - name: Instrument descriptions conform to the specified syntax. - name: Instrument supports the advisory ExplicitBucketBoundaries parameter. - name: Instrument supports the advisory Attributes parameter. + - name: Instrument supports the advisory OptIn parameter. - name: All methods of `MeterProvider` are safe to be called concurrently. - name: All methods of `Meter` are safe to be called concurrently. - name: All methods of any instrument are safe to be called concurrently. diff --git a/specification/metrics/api.md b/specification/metrics/api.md index c37fccc944d..7439b6ab9d4 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -26,6 +26,7 @@ weight: 1 + [Instrument advisory parameters](#instrument-advisory-parameters) - [Instrument advisory parameter: `ExplicitBucketBoundaries`](#instrument-advisory-parameter-explicitbucketboundaries) - [Instrument advisory parameter: `Attributes`](#instrument-advisory-parameter-attributes) + - [Instrument advisory parameter: `OptIn`](#instrument-advisory-parameter-optin) + [Synchronous and Asynchronous instruments](#synchronous-and-asynchronous-instruments) - [Synchronous Instrument API](#synchronous-instrument-api) - [Asynchronous Instrument API](#asynchronous-instrument-api) @@ -276,6 +277,16 @@ Applies to all instrument types. `Attributes` (a list of [attribute keys](../common/README.md#attribute)) is the recommended set of attribute keys to be used for the resulting metrics. +##### Instrument advisory parameter: `OptIn` + +**Status**: [Development](../document-status.md) + +Applies to all instrument types. + +`OptIn` (bool) if true, indicates that the instrument MUST NOT +produce metric data and that functions on the instrument SHOULD be no-ops +unless the user has explicitly enabled the metric. + #### Synchronous and Asynchronous instruments Instruments are categorized on whether they are synchronous or diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 0c3da4b83fc..96f5edccbf8 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -52,6 +52,7 @@ weight: 3 * [Instrument advisory parameters](#instrument-advisory-parameters) + [Instrument advisory parameter: `ExplicitBucketBoundaries`](#instrument-advisory-parameter-explicitbucketboundaries) + [Instrument advisory parameter: `Attributes`](#instrument-advisory-parameter-attributes) + + [Instrument advisory parameter: `OptIn`](#instrument-advisory-parameter-optin) * [Instrument enabled](#instrument-enabled) - [Attribute limits](#attribute-limits) - [Exemplar](#exemplar) @@ -413,6 +414,13 @@ The SDK MUST accept the following stream configuration parameters: `aggregation_cardinality_limit` value, the `MeterProvider` MUST apply the [default aggregation cardinality limit](#metricreader) the `MetricReader` is configured with. +* **Status**: [Development](../document-status.md) - `enabled` (optional): A + boolean denoting whether the instrument should be enabled. When `enabled` is + `false`, the View uses the `DropAggregation`, regardless of the `aggregation` + provided. When `enabled` is `true` for an instrument with `OptIn` set to + `true`, the SDK treats the instrument as-if `OptIn` was set to false. The + SDK must allow `enabled` to be unset (neither true nor false). If unset, + `enabled` has no effect. #### Measurement processing @@ -420,33 +428,36 @@ The SDK SHOULD use the following logic to determine how to process Measurements made with an Instrument: * Determine the `MeterProvider` which "owns" the Instrument. -* If the `MeterProvider` has no `View` registered, take the Instrument - and apply the default Aggregation on the basis of instrument kind according - to the [MetricReader](#metricreader) instance's `aggregation` property. +* If the `MeterProvider` has no `View` registered, or if the Instrument does + not match any View's instrument selection criteria: + * **Status**: [Development](../document-status.md) - If the instrument's + [OptIn advisory parameter](#instrument-advisory-parameter-optin) + is set to true, use the [Drop Aggregation](#drop-aggregation). + * If OptIn is false, take the Instrument and apply the default + Aggregation on the basis of instrument kind according to the + [MetricReader](#metricreader) instance's `aggregation` property. [Instrument advisory parameters](#instrument-advisory-parameters), if any, MUST be honored. -* If the `MeterProvider` has one or more `View`(s) registered: - * If the Instrument could match the instrument selection criteria, for each - View: - * Try to apply the View's stream configuration independently of any other - Views registered for the same matching Instrument (i.e. Views are not - merged). This may result in [conflicting metric identities](./data-model.md#opentelemetry-protocol-data-model-producer-recommendations) - even if stream configurations specify non-overlapping properties (e.g. - one View setting `aggregation` and another View setting `attribute_keys`, - both leaving the stream `name` as the default configured by the - Instrument). If applying the View results in conflicting metric identities - the implementation SHOULD apply the View and emit a warning. If it is not - possible to apply the View without producing semantic errors (e.g. the - View sets an asynchronous instrument to use the [Explicit bucket - histogram aggregation](#explicit-bucket-histogram-aggregation)) the - implementation SHOULD emit a warning and proceed as if the View did not - If both a View and [Instrument advisory parameters](#instrument-advisory-parameters) - specify the same aspect of the [Stream configuration](#stream-configuration), - the setting defined by the View MUST take precedence over the advisory parameters. - * If the Instrument could not match with any of the registered `View`(s), the - SDK SHOULD enable the instrument using the default aggregation and temporality. - Users can configure match-all Views using [Drop aggregation](#drop-aggregation) - to disable instruments by default. +* If the `MeterProvider` has one or more matching `View`(s) registered, for + each `View` that matches the instrument selection criteria: + * Try to apply the View's stream configuration independently of any other + Views registered for the same matching Instrument (i.e. Views are not + merged). This may result in [conflicting metric identities](./data-model.md#opentelemetry-protocol-data-model-producer-recommendations) + even if stream configurations specify non-overlapping properties (e.g. + one View setting `aggregation` and another View setting `attribute_keys`, + both leaving the stream `name` as the default configured by the + Instrument). If applying the View results in conflicting metric identities + the implementation SHOULD apply the View and emit a warning. If it is not + possible to apply the View without producing semantic errors (e.g. the + View sets an asynchronous instrument to use the [Explicit bucket + histogram aggregation](#explicit-bucket-histogram-aggregation)) the + implementation SHOULD emit a warning and proceed as if the View did not + If both a View and [Instrument advisory parameters](#instrument-advisory-parameters) + specify the same aspect of the [Stream configuration](#stream-configuration), + the setting defined by the View MUST take precedence over the advisory parameters. + +Users can configure match-all Views with `enabled=false` or with the +[Drop aggregation](#drop-aggregation), to disable instruments by default. #### View examples @@ -999,6 +1010,20 @@ If no View is configured, or if a matching view does not specify attribute keys, the advisory parameter should be used. If neither is provided, all attributes must be retained. +#### Instrument advisory parameter: `OptIn` + +**Status**: [Development](../document-status.md) + +This advisory parameter applies to all aggregations. + +When an instrument has `OptIn=true`, the SDK MUST use the +[Drop Aggregation](#drop-aggregation). If the user sets `enabled=true` on a +View's [Stream configuration](#stream-configuration), this "enables" the +instrument with the same behavior as-if the instrument was `OptIn=false` -- +including respecting other advisory parameters. Setting fields other than +`enabled` on the View, including setting the `aggregation`, does not enable +the instrument. + ### Instrument enabled The synchronous instrument [`Enabled`](./api.md#enabled) MUST return `false`