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

Clarify reader / exporter relationship for temporality preference and default aggregation #4142

Merged
merged 7 commits into from
Jul 24, 2024
Merged

Clarify reader / exporter relationship for temporality preference and default aggregation #4142

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
b214d4b
Clarify that reader / exporter relationship for temporality and aggre…
jack-berg Jul 11, 2024
f425ae8
Remove prometheus host and port options
jack-berg Jul 15, 2024
f721dd1
PR feedback
jack-berg Jul 15, 2024
0f0ec8f
Merge branch 'main' into clarify-metric-exporter-configuration
jack-berg Jul 15, 2024
29819be
Add changelog entry
jack-berg Jul 15, 2024
2760e88
Merge branch 'clarify-metric-exporter-configuration' of https://githu…
jack-berg Jul 15, 2024
ef9544a
Merge branch 'main' of https://github.com/open-telemetry/opentelemetr…
jack-berg Jul 23, 2024
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
5 changes: 5 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,11 @@ release.

- Clarify prometheus exporter should have `host` and `port` configuration options.
([#4147](https://github.com/open-telemetry/opentelemetry-specification/pull/4147))
- Clarify metric reader / metric exporter relationship for temporality
preference and default aggregation. Explicitly define configuration options
for temporality preference and default aggregation of built-in exporters, and
make default values explicit.
([#4142](https://github.com/open-telemetry/opentelemetry-specification/pull/4142))

### Logs

Expand Down
122 changes: 62 additions & 60 deletions spec-compliance-matrix.md
View file
Open in desktop

Large diffs are not rendered by default.

8 changes: 4 additions & 4 deletions specification/metrics/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1221,12 +1221,12 @@ determines the following capabilities:
* Handling the [ForceFlush](#forceflush) and [Shutdown](#shutdown) signals from
the SDK.

To construct a `MetricReader` when setting up an SDK, the caller
SHOULD provide at least the following:
To construct a `MetricReader` when setting up an SDK, at least the following
SHOULD be provided:

* The `exporter` to use, which is a `MetricExporter` instance.
* The default output `aggregation` (optional), a function of instrument kind. If not configured, the [default aggregation](#default-aggregation) SHOULD be used.
* The default output `temporality` (optional), a function of instrument kind. If not configured, the Cumulative temporality SHOULD be used.
* The default output `aggregation` (optional), a function of instrument kind. This function SHOULD be obtained from the `exporter`. If not configured, the [default aggregation](#default-aggregation) SHOULD be used.
* The output `temporality` (optional), a function of instrument kind. This function SHOULD be obtained from the `exporter`. If not configured, the Cumulative temporality SHOULD be used.
* **Status**: [Development](../document-status.md) - The default aggregation cardinality limit to use, a function of instrument kind. If not configured, a default value of 2000 SHOULD be used.
* **Status**: [Development](../document-status.md) - The [MetricFilter](#metricfilter) to apply to metrics and attributes during `MetricReader#Collect`.
* Zero of more [MetricProducer](#metricproducer)s (optional) to collect metrics from in addition to metrics from the SDK.
Expand Down
11 changes: 9 additions & 2 deletions specification/metrics/sdk_exporters/in-memory.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,8 +10,15 @@ In-memory Metrics Exporter is a [Push Metric
Exporter](../sdk.md#push-metric-exporter) which accumulates metrics data in the
local memory and allows to inspect it (useful for e.g. unit tests).

In-memory Metrics Exporter MUST support both Cumulative and Delta
[Temporality](../data-model.md#temporality).
In-memory Metrics Exporter MUST provide configuration to set
the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
instrument kind. This option MAY be named `temporality`, and MUST set
temporality to Cumulative for all instrument kinds by default.

In-memory Metrics Exporter MAY provide configuration to set
the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
of instrument kind. This option MAY be named `default_aggregation`, and MUST use
the [default aggregation](../sdk.md#default-aggregation) by default.

If a language provides a mechanism to automatically configure a
[MetricReader](../sdk.md#metricreader) to pair with the associated
Expand Down
21 changes: 14 additions & 7 deletions specification/metrics/sdk_exporters/otlp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,15 @@ OTLP Metrics Exporter is a [Push Metric
Exporter](../sdk.md#push-metric-exporter) which sends metrics via the
[OpenTelemetry Protocol](../../protocol/README.md).

OTLP Metrics Exporter MUST support both Cumulative and Delta
[Aggregation Temporality](../data-model.md#temporality).
OTLP Metrics Exporter MUST provide configuration to influence
the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
jack-berg marked this conversation as resolved.
Show resolved Hide resolved
instrument kind. This option MAY be named `temporality`, and MUST set
temporality preference to Cumulative for all instrument kinds by default.

OTLP Metrics Exporter MUST provide configuration to influence
the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
of instrument kind. This option MAY be named `default_aggregation`, and MUST set
the [default aggregation](../sdk.md#default-aggregation) for all instrument kinds by default.

The exporter MUST provide configuration according to the [OpenTelemetry Protocol
Exporter](../../protocol/exporter.md) specification.
Expand All @@ -33,12 +40,12 @@ then by default:
* The exporter MUST configure the default aggregation on the basis of instrument kind using
the `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` variable as described below if it is implemented.

## Additional Configuration
## Additional Environment Variable Configuration

| Name | Description | Default |
|------------------------------------------------------------|---------------------------------------------------------------------|-----------------------------|
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | The aggregation temporality to use on the basis of instrument kind. | `cumulative` |
| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | The default aggregation to use for histogram instruments. | `explicit_bucket_histogram` |
| Name | Description | Default |
|------------------------------------------------------------|--------------------------------------------------------------------------------------------------------|-----------------------------|
| `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` | Configure the exporter's aggregation `temporality` option (see above) on the basis of instrument kind. | `cumulative` |
| `OTEL_EXPORTER_OTLP_METRICS_DEFAULT_HISTOGRAM_AGGREGATION` | Configure the exporter's `default_aggregation` option (see above) for Histogram instrument kind. | `explicit_bucket_histogram` |

The recognized (case-insensitive) values for `OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE` are:

Expand Down
9 changes: 9 additions & 0 deletions specification/metrics/sdk_exporters/prometheus.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,6 +38,10 @@ A Prometheus Exporter for an OpenTelemetry metrics SDK MUST NOT add
There MUST be at most one `target` info metric exposed by an SDK
Prometheus exporter.

A Prometheus Exporter MUST set
the [MetricReader](../sdk.md#metricreader) `temporality` as a function of
instrument kind to be `cumulative` for all instrument kinds.

## Configuration

A Prometheus Exporter SHOULD support a configuration option to set the host
Expand All @@ -48,6 +52,11 @@ A Prometheus Exporter SHOULD support a configuration option to set the port
that metrics are served on. The option MAY be named `port`, and MUST be `9464` by
default.
jack-berg marked this conversation as resolved.
Show resolved Hide resolved

A Prometheus Exporter SHOULD support a configuration option to set
the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
of instrument kind. This option MAY be named `default_aggregation`, and MUST use
the [default aggregation](../sdk.md#default-aggregation) by default.

A Prometheus Exporter MAY offer configuration to add resource attributes as metric attributes.
By default, it MUST NOT add any resource attributes as metric attributes.
The configuration SHOULD allow the user to select which resource attributes to copy (e.g.
Expand Down
11 changes: 9 additions & 2 deletions specification/metrics/sdk_exporters/stdout.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,8 +14,15 @@ stdout/console.
name for their language. For example, ConsoleExporter, StdoutExporter,
StreamExporter, etc.

"Standard output" Metrics Exporter MUST support both Cumulative and Delta
[Temporality](../data-model.md#temporality).
"Standard output" Metrics Exporter MUST provide configuration to set
the [MetricReader](../sdk.md#metricreader) output `temporality` as a function of
instrument kind. This option MAY be named `temporality`, and MUST set
temporality to Cumulative for all instrument kinds by default.

"Standard output" Metrics Exporter MAY provide configuration to set
the [MetricReader](../sdk.md#metricreader) default `aggregation` as a function
of instrument kind. This option MAY be named `default_aggregation`, and MUST use
the [default aggregation](../sdk.md#default-aggregation) by default.

If a language provides a mechanism to automatically configure a
[MetricReader](../sdk.md#metricreader) to pair with the associated
Expand Down
Loading