Skip to content

Add OptIn metric advisory parameter #4809

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
dashpole wants to merge 12 commits into
base: main
Choose a base branch
from
Draft

Add OptIn metric advisory parameter #4809

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
12 commits
Select commit Hold shift + click to select a range
ea7d7ec
add DefaultDisabled advisory parameter
dashpole Dec 16, 2025
03cbc80
make bool explicit
dashpole Dec 16, 2025
2e3fbd2
rename to OptIn
dashpole Jan 5, 2026
37821ea
clarify that advisory parameters apply when views are registered, but…
dashpole Jan 5, 2026
fb933a8
fix lint
dashpole Jan 5, 2026
d647106
Update specification/metrics/api.md
dashpole Jan 6, 2026
23bcef0
clarify that the defualt aggregation enables OptIn instruments
dashpole Jan 6, 2026
5929f55
Update specification/metrics/sdk.md
dashpole Jan 8, 2026
e79e34f
add explicit enabled field to view configuration
dashpole Jan 8, 2026
7899e97
address wording feedback
dashpole Jan 8, 2026
9a96262
lint
dashpole Jan 8, 2026
6805ae2
view stream.Enabled can be unset
dashpole Jan 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -13,6 +13,9 @@ release.

### Metrics

- Add the OptIn advisory parameter.
([#4809](https://github.com/open-telemetry/opentelemetry-specification/pull/4809))

### Logs

### Baggage
Expand Down
1 change: 1 addition & 0 deletions spec-compliance-matrix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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. | | + | + | + | - | | + | | | + | + | |
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/cpp.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/dotnet.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/erlang.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/go.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/java.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/js.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/php.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/python.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/ruby.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/rust.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 2 additions & 0 deletions spec-compliance-matrix/swift.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
1 change: 1 addition & 0 deletions spec-compliance-matrix/template.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
11 changes: 11 additions & 0 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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`
Comment thread
trask marked this conversation as resolved.

**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
Expand Down
75 changes: 50 additions & 25 deletions specification/metrics/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -413,40 +414,50 @@ 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

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

Expand Down Expand Up @@ -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
Comment thread
dashpole marked this conversation as resolved.

The synchronous instrument [`Enabled`](./api.md#enabled) MUST return `false`
Expand Down
Loading