opentelemetry-specification
opentelemetry-specification copied to clipboard
Clarify "semantic conflicts" in the metrics spec
What are you trying to achieve?
There are several combinations of metric instrument and aggregator that OpenTelemetry has not given a formal specification for. Use of these combinations potentially allows unspecified behavior to become available to users.
OTel's metrics SDK spec should be updated to explain which combinations MUST/SHOULD be prevented.
These result from incompleteness in the data model.
- We do not have a GaugeHistogram data point type, so we cannot meaningfully define the use of Histogram with asynchronous instruments.
- We have not specified how to handle synchronous Gauge instruments, even though we have the appropriate data type.
Until the behavior of these aggregations/instruments is specified (histogram w/ async instrument, gauge w/ sync instrument) they should not be allowed.
There is a second, connected question that has come up in the SIGs implementing OTel metrics. When configuring an instrument with a non-standard aggregation, who is then responsible for range checks? Does the new pairing observe the range limits associated with the aggregator, or with the instrument? Consensus in the SIGs suggests that range limits should remain with the instrument. This implies that range checks SHOULD be performed based on the instrument kind, without considering its aggregation.
The possibility to use non-standard aggregations SHOULD NOT encourage violating the data model, particularly as it concerns Counter and Histogram instruments. Observe that if an UpDownCounter were allowed to be paired with a Monotonic Sum aggregator, it would potentially break the data model, so this combination needs to be avoided. OTOH there is nothing wrong with configuring a Counter with a NonMonotonic Sum aggregation: it changes interpretation but does not break the data model.
Additional context.
Here is an implementation of a semantic conflict checker for Lightstep's metrics SDK: https://github.com/lightstep/otel-launcher-go/blob/main/lightstep/sdk/metric/internal/viewstate/viewstate.go#L617