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.

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

Jump to bottom

Clarify AggregationTemporality override rules #2032

Merged
merged 9 commits into from
Oct 26, 2021
Merged

Clarify AggregationTemporality override rules #2032

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
9ac4f2d
Clarify AggregationTemporality override rules
reyang Oct 19, 2021
c1f61a5
update changelog
reyang Oct 19, 2021
601c037
remove per view setting, adjust wording
reyang Oct 19, 2021
fa56d22
simply the wording
reyang Oct 19, 2021
6459fce
remove the invalid example
reyang Oct 19, 2021
4ba1aa3
address review feedback
reyang Oct 19, 2021
5052cef
Merge branch 'open-telemetry:main' into reyang/metrics-sdk-temporalit…
reyang Oct 19, 2021
d62076f
Merge branch 'main' into reyang/metrics-sdk-temporality-rules
reyang Oct 20, 2021
b185988
Merge branch 'main' into reyang/metrics-sdk-temporality-rules
reyang Oct 25, 2021
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 @@ -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
46 changes: 36 additions & 10 deletions specification/metrics/sdk.md
View file
Open in desktop
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 @@ -332,12 +336,6 @@ This Aggregation does not have any configuration parameters.
The Sum Aggregation informs the SDK to collect data for the
[Sum Metric Point](./datamodel.md#sums).

This Aggregation honors the following configuration parameters:

| Key | Value | Default Value | Description |
| --- | --- | --- | --- |
| Temporality | Delta, Cumulative | Cumulative | |

The monotonicity of the aggregation is determined by the instrument type:

| Instrument Kind | `SumType` |
Expand All @@ -349,6 +347,8 @@ The monotonicity of the aggregation is determined by the instrument type:
| [Asynchronous Counter](./api.md#asynchronous-counter) | Monotonic |
| [Asynchrounous UpDownCounter](./api.md#asynchronous-updowncounter) | Non-Monotonic |

This Aggregation does not have any configuration parameters.

This Aggregation informs the SDK to collect:

- The arithmetic sum of `Measurement` values.
Expand Down Expand Up @@ -383,7 +383,6 @@ This Aggregation honors the following configuration parameters:

| Key | Value | Default Value | Description |
| --- | --- | --- | --- |
| Temporality | Delta, Cumulative | Cumulative | See [Temporality](./datamodel.md#temporality). |
| Boundaries | double\[\] | [ 0, 5, 10, 25, 50, 75, 100, 250, 500, 1000 ] | Array of increasing values representing explicit bucket boundary values.<br><br>The Default Value represents the following buckets:<br>(-&infin;, 0], (0, 5.0], (5.0, 10.0], (10.0, 25.0], (25.0, 50.0], (50.0, 75.0], (75.0, 100.0], (100.0, 250.0], (250.0, 500.0], (500.0, 1000.0], (1000.0, +&infin;) |

Note: This aggregator should not fill out `sum` when used with instruments
Expand Down Expand Up @@ -575,6 +574,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 +669,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 +820,29 @@ 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 [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 [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, 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
2 changes: 1 addition & 1 deletion specification/metrics/sdk_exporters/otlp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,4 +26,4 @@ Exporter](../../protocol/exporter.md) specification once it reaches

| Description | Default | Env variable |
| ----------- | ------- | ------------ |
| The output [Aggregation Temporality](../datamodel.md#temporality), either `CUMULATIVE` or `DELTA` (case insensitive) | `CUMULATIVE` | `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY`
| The preferred output [Aggregation Temporality](../datamodel.md#temporality), either `CUMULATIVE` or `DELTA` (case insensitive) | `CUMULATIVE` | `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY`
reyang marked this conversation as resolved.
Show resolved Hide resolved