Add OptIn metric advisory parameter

[dashpole]

Fixes #4391

Changes

Add a new advisory parameter, OptIn, which causes the SDK to use the DropAggregation by default. The instrument's Enabled method returns false by default.

Users can enable metrics by using Views. They can set a new enabled parameter to true in the stream configuration to do this. They can enable all metrics by setting enabled=true with a wildcard (*) view.

Example in Declarative Config

If accepted, this would likely be an enabled: field within stream configuraiton.

A user could enable a single instrument with a view:

meter_provider:
  views:
    - selector:
        instrument_name: my.optin.instrument
      stream:
        enabled: true

A user could disable a single instrument with a view:

meter_provider:
  views:
    - selector:
        instrument_name: my.unwanted.instrument
      stream:
        enabled: false

A user could enable all OptIn instruments:

meter_provider:
  views:
    - selector:
        instrument_name: *
      stream:
        enabled: true

Motivation

I would like to be able to metric semantic conventions with the opt-in requirement level. In particular, I am interested in this to be able to define some for Go runtime semantic conventions. See open-telemetry/opentelemetry-go-contrib#6321 (comment).

Prototypes

• Go: PoC: Metric instruments support an WithOptIn option. opentelemetry-go#7721

Alternative Considered: DefaultAggregation enables metrics

Instead of a new enabled parameter in View, we could just tell users to use aggregation=DefaultAggregation to enable OptIn metrics.

The issue is that DefaultAggregation is often used in Views to make a small change (enable exponential histograms, change default histogram boundaries, etc), but otherwise leave the aggregation unmodified. If we use DefaultAggregation as a signal to enable OptIn metrics, it prevents DefaultAggregation from being used as a signal to "keep the normal aggregation behavior".

Alternative Considered: Metric Levels

TL;DR: Metric Levels should be built on-top-of views, and can co-exist with this OptIn parameter.

In a similar vein to #3205, we could define levels for metrics. As an instrumentation author, instead of defining a metric as "default disabled", I would define a metric as "debug level". Users would be able to enable all debug metrics as a group, similar to how debug logging is turned on today.

A complete metric levels feature should control more than just which instruments are enabled or disabled. The overall goal should be managing cardinality and data size, which has many other dimensions. I've opened #4828 with details about how levels could be layered on-top-of views, as an alternative to adding them to the API.

• CHANGELOG.md file updated for non-trivial changes
• Spec compliance matrix updated if necessary

[cijothomas]

Should this (###Instrument Enabled) section be updated to return false based on DefaultDisabled?

[dashpole]

I initially included that, but I think it is covered by the "resolved view" clause:

opentelemetry-specification/specification/metrics/sdk.md

Lines 1009 to 1010 in d783245

	- All [resolved views](#measurement-processing) for the instrument are
	configured with the [Drop Aggregation](#drop-aggregation).

The #measurement-processing section linked there is what I modify here: https://github.com/open-telemetry/opentelemetry-specification/pull/4809/files#diff-32d5f289beed96900fa1e6e69a3ee9cc0b6503ce8883672011c44bc772c0fa2aR424.

So my reading of it is that updating the #measurement-processing section is enough to make Instrument Enabled return false based on DefaultDisabled.

[cijothomas]

Agree with the change, except the name. I prefer OptIn.
Requesting changes only for the name part.

[carlosalberto]

@cijothomas Name was changed to OptIn. I think your only request was satisfied?

[dashpole]

Feedback from 2/6 spec sig meeting:

• It would be nice for consistency of opt-in behavior to be similar for all signal types
• To be explored, and added to alternatives considered:
  • View-style configuration for spans and logs
  • Level-based configuration (similar to log levels) for metrics and spans. Investigate how the collector handles this.

[dashpole]

I've given metric levels more thought, and have looked through how the collector has implemented them. I updated the alternatives considered section in the description. TL;DR: Metric Levels should be layered on-top-of views, and should not be part of the API.

[codeboten]

These are all tuned today using views. Instead of building metric levels into the API, we should build metric levels as a layer on top of views. That is actually what the collector does today.

It's not immediately clear to me how levels could be layered on top of views, as instrumentation authors need to be able to define the level of a metric in their definition of the instrument, and views are configured when instantiating the provider.

The collector can do this as it is an end user of the SDK, and chooses what telemetry to emit at various levels via views, but as an instrumentation author i'm not sure how that would work w/ the api we have available today.

Would a "level" metric advisory parameter work here?

[dashpole]

It's not immediately clear to me how levels could be layered on top of views
Would a "level" metric advisory parameter work here?

I'm hoping to avoid a level advisory parameter. See #4828 for a rough sketch of what I had in mind.

[trask]

@MrAlias @reyang (since you have already approved) please see recent change based on this discussion: #4809 (comment)

[dashpole]

This was discussed at the 1/13 Spec SIG meeting today:

• Metric requirement levels are more detailed than just Opt-In: https://opentelemetry.io/docs/specs/semconv/general/metric-requirement-level/
• Should we add required or recommended?
  • Start with just OptIn. Recommended isn’t used consistently.
• Where should the SDK config be located? MeterProvider? Scope? View?
  • View-level would be what java-agent users want, but scope level might work. MeterProvider would not.

[trask]

• View-level would be what java-agent users want.

scope level might work for them. I don't think a global setting would though.

[jack-berg]

I'm partial to an approach where these instruments are enabled via the MeterConfig / MeterConfigurator mechanism. As discussed in the spec SIG a couple of times, this issue of config knob granularity (i.e. should the knob be at the meter provider, metric reader, meter, or instrument level) is recurring, and I think the answer ends up being subjective rather than right or wrong. Reason I prefer config at the meter level:

• The view API has surprising behavior when conflicts occur. The idea of a using a wildcard view to opt into all opt-in metrics only works if you currently don't have any other views. As soon as you do, that wildcard view will yield duplicate metric streams for all "enabled by default metrics". Because of this, I generally try to stay away from views. When I do use / recommend them, I recommend selecting / configuring individual instruments, which avoids the no-merging / duplicate stream problems.
• Adding a new "enabled" field to views seems like the most correct thing to do here given the discussion, and yet does jive well with the existing view properties. Had we had this "enabled" concept from v1, we wouldn't need the "drop" aggregation. But we do have "drop" and with "enabled" there are now two ways to do the same thing.
• The meter level seems sufficiently granular. Views are of course more granular, but I would guess that meter level configuration seems to be good enough for most usage.
• If the meter config option manifested as something like a "minimum requirement level", then it would have symmetry to the minimum_severity property of LoggerConfig. Its reasonable to see how that idea could be extended to traces such that we could have a threshold / level property in LoggerConfig / MeterConfig / TracerConfig.

That's my preference, but I understand the desire / argument for configuration at the view level and so won't block.

[dashpole]

@cijothomas @reyang @MrAlias please re-review -- especially the new view Stream.Enabled field. Also let me know if you would prefer that I explore a meter-level configuration for enabling opt-in metrics instead.

[dashpole]

I updated the PoC to use the new Enabled field on the View's stream.

[dashpole]

One thing I found when implementing the prototype is that it is important for stream.Enabled to be allowed to be unset. I've addressed this in 4704d7e.

[dashpole]

I've also added hypothetical declarative configuration examples in the description.