Skip to content
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.

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

Clarify AggregationTemporality override rules #2032

Merged
3 changes: 3 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,9 @@ release.
([#1935](https:/open-telemetry/opentelemetry-specification/pull/1935))
- Add clarifications on how to handle numerical limits.
([#2007](https:/open-telemetry/opentelemetry-specification/pull/2007))
- Add clarifications on how to determine aggregation temporality.
([#2013](https:/open-telemetry/opentelemetry-specification/pull/2013),
[#2032](https:/open-telemetry/opentelemetry-specification/pull/2032))

### Logs

Expand Down
44 changes: 41 additions & 3 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@ Table of Contents
* [Push Metric Exporter](#push-metric-exporter)
* [Pull Metric Exporter](#pull-metric-exporter)
* [Defaults and configuration](#defaults-and-configuration)
* [Temporality override rules](#temporality-override-rules)
* [Numerical limits handling](#numerical-limits-handling)
* [Compatibility requirements](#compatibility-requirements)
* [Concurrency requirements](#concurrency-requirements)
Expand Down Expand Up @@ -162,9 +163,12 @@ are the inputs:
* The `extra dimensions` which come from Baggage/Context (optional). If not
provided, no extra dimension will be used. Please note that this only
applies to [synchronous Instruments](./api.md#synchronous-instrument).
* The `aggregation` (optional) to be used. If not provided, a default
aggregation will be applied by the SDK. The default aggregation is a TODO.
* The `exemplar_reservoir` (optional) to use for storing exemplars.
* The `aggregation` (optional) to be used. If not provided, the SDK SHOULD
apply a [default aggregation](#default-aggregation). If the aggregation has
temporality, the SDK SHOULD use the [temporality override
rules](#temporality-override-rules) to determine the aggregation
temporality.
* The `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.

Expand Down Expand Up @@ -575,6 +579,8 @@ authors MAY choose the best idiomatic design for their language:
instance is set to use Cumulative, and it has an associated [Push Metric
Exporter](#push-metric-exporter) instance which has the temporality set to
Delta), would the SDK want to fail fast or use some fallback logic?
* Refer to the [temporality override rules](#temporality-override-rules) for how
to determine the temporality.
* Refer to the [supplementary
guidelines](./supplementary-guidelines.md#aggregation-temporality), which have
more context and suggestions.
Expand Down Expand Up @@ -668,6 +674,8 @@ language:
Exporter](./sdk_exporters/prometheus.md) instance is being used, and the
temporality is set to Delta), would the SDK want to fail fast or use some
fallback logic?
* Refer to the [temporality override rules](#temporality-override-rules) for how
to determine the temporality.
* Refer to the [supplementary
guidelines](./supplementary-guidelines.md#aggregation-temporality), which have
more context and suggestions.
Expand Down Expand Up @@ -817,6 +825,36 @@ modeled to interact with other components in the SDK:
The SDK MUST provide configuration according to the [SDK environment
variables](../sdk-environment-variables.md) specification.

## Temporality override rules

There are several places where [Aggregation
Temporality](./datamodel.md#temporality) can be configured in the OpenTelemetry
SDK. The SDK MUST use the following order to determine which temporality to be
used:

* If the temporality is explicitly specified on a [View](#view), use the
specified temporality and goto END.
reyang marked this conversation as resolved.
Show resolved Hide resolved
* If the [MetricExporter](#metricexporter) or [MetricReader](#metricreader) only
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
supports one temporality (either Cumulative or Delta), use the supported
temporality and goto END.
* If the [MetricExporter](#metricexporter) or [MetricReader](#metricreader)
supports both Cumulative and Delta:
* If the temporality is explicitly specified on the
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
[MetricExporter](#metricexporter) or [MetricReader](#metricreader), use the
specified temporality and goto END.
* If the [MetricExporter](#metricexporter) or [MetricReader](#metricreader)
has a preferred temporality, use the preferred temporality and goto END.
* If the [MetricExporter](#metricexporter) or [MetricReader](#metricreader)
does not have a preferred temporality, use Cumulative and goto END.
* END.

If the above process caused conflicts (e.g. a View has an explicitly specified
temporality Delta, but the `MetricExporter` only supports Cumulative), the SDK
SHOULD treat the conflicts as error. It is unspecified _how_ the SDK should
handle these error (e.g. it could fail fast during the SDK configuration time).
Please refer to [Error handling in OpenTelemetry](../error-handling.md) for the
general guidance.

## Numerical limits handling

The SDK MUST handle numerical limits in a graceful way according to [Error
Expand Down