diff --git a/CHANGELOG.md b/CHANGELOG.md index 75951048578..96131073223 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -16,6 +16,9 @@ release. ### Metrics +- Rename built-in ExemplarFilters to AlwaysOn, AlwaysOff and TraceBased. + ([#2919](https://github.com/open-telemetry/opentelemetry-specification/pull/2919)) + ### Logs ### Resource @@ -28,6 +31,10 @@ release. ### SDK Configuration +- Rename knowns values for "OTEL_METRICS_EXEMPLAR_FILTER" to "always_on", + "always_off" and "trace_based". + ([#2919](https://github.com/open-telemetry/opentelemetry-specification/pull/2919)) + ### Telemetry Schemas ### Common diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index c722604dcfd..d19467a571c 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -33,6 +33,10 @@ linkTitle: SDK - [Attribute limits](#attribute-limits) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) + * [Built-in ExemplarFilters](#built-in-exemplarfilters) + + [AlwaysOn](#alwayson) + + [AlwaysOff](#alwaysoff) + + [TraceBased](#tracebased) * [ExemplarReservoir](#exemplarreservoir) * [Exemplar defaults](#exemplar-defaults) - [MetricReader](#metricreader) @@ -651,7 +655,9 @@ A Metric SDK SHOULD provide extensible hooks for Exemplar sampling, specifically ### ExemplarFilter The `ExemplarFilter` interface MUST provide a method to determine if a -measurement should be sampled. +measurement should be sampled. Sampled here simply makes the measurement +eligible for being included as an exemplar. `ExemplarReservoir` makes the final +decision if a measurement becomes an exemplar. This interface SHOULD have access to: @@ -662,8 +668,24 @@ This interface SHOULD have access to: [Span](../trace/api.md#span). - A `timestamp` that best represents when the measurement was taken. -See [Defaults and Configuration](#defaults-and-configuration) for built-in -filters. +### Built-in ExemplarFilters + +OpenTelemetry supports a number of built-in exemplar filters to choose from. +The default is `TraceBased`. + +#### AlwaysOn + +An ExemplarFilter which makes all measurements eligible for being an Exemplar. + +#### AlwaysOff + +An ExemplarFilter which makes no measurements eligible for being an Exemplar. +Using this ExemplarFilter is as good as disabling Exemplar feature. + +#### TraceBased + +An ExemplarFilter which makes those measurements eligible for being an +Exemplar, which are recorded in the context of a sampled parent span. ### ExemplarReservoir diff --git a/specification/sdk-environment-variables.md b/specification/sdk-environment-variables.md index a3d04652164..ded3dcaa57c 100644 --- a/specification/sdk-environment-variables.md +++ b/specification/sdk-environment-variables.md @@ -294,9 +294,9 @@ Known values for `OTEL_LOGS_EXPORTER` are: Known values for `OTEL_METRICS_EXEMPLAR_FILTER` are: -- `"none"`: No measurements are eligible for exemplar sampling. -- `"all"`: All measurements are eligible for exemplar sampling. -- `"with_sampled_trace"`: Only allow measurements with a sampled parent span in context. +- `"always_on"`: [AlwaysOn](./metrics/sdk.md#alwayson) +- `"always_off"`: [AlwaysOff](./metrics/sdk.md#alwaysoff) +- `"trace_based"`: [TraceBased](./metrics/sdk.md#tracebased) ### Periodic exporting MetricReader