From 792aa849e89283514756336726b7efca8ebc94dd Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 17 Jan 2024 10:18:51 -0500 Subject: [PATCH] Fixes #3812 - ExemplarFilter does not need to be exposed as an interface. --- specification/metrics/sdk.md | 44 +++++++++++++----------------------- 1 file changed, 16 insertions(+), 28 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index fe54797425d..37921be7f20 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -879,7 +879,7 @@ series and the topic requires further analysis. ## Exemplar -**Status**: [Feature-freeze](../document-status.md) +**Status**: [Experimental, Feature-freeze](../document-status.md) Exemplars are example data points for aggregated data. They provide specific context to otherwise general aggregations. Exemplars allow correlation between @@ -934,52 +934,42 @@ A Metric SDK MUST allow exemplar sampling to leverage the configuration of metric aggregation. For example, Exemplar sampling of histograms should be able to leverage bucket boundaries. -A Metric SDK SHOULD provide extensible hooks for Exemplar sampling, specifically: +A Metric SDK SHOULD provide configuration for Exemplar sampling, specifically: - `ExemplarFilter`: filter which measurements can become exemplars. - `ExemplarReservoir`: storage and sampling of exemplars. ### ExemplarFilter -The `ExemplarFilter` interface MUST provide a method to determine if a -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. +The `ExemplarFilter` configuration MUST allow users to select between one of the +built-in ExemplarFilters. While `ExemplarFilter` detrmines which measurements +are *eligible* for becoming an `Exemplar`, the `ExemplarReservoir` makes the +final decision if a measurement becomes an exemplar and is stored. -This interface SHOULD have access to: - -- The `value` of the measurement. -- The complete set of `Attributes` of the measurement. -- The [Context](../context/README.md) of the measurement, which covers the - [Baggage](../baggage/api.md) and the current active - [Span](../trace/api.md#span). -- A `timestamp` that best represents when the measurement was taken. +The ExemplarFilter SHOULD be a configuration parameter of a `MeterProvider` for +an SDK. The default value SHOULD be `TraceBased`. The filter configuration +SHOULD follow the [environment variable specification](../configuration/sdk-environment-variables.md#exemplar). -### Built-in ExemplarFilters +An OpenTelemetry SDK MUST support the following filters: -OpenTelemetry supports a number of built-in exemplar filters to choose from. -The default is `TraceBased`. +- [AlwaysOn](#alwayson) +- [AlwaysOff](#alwaysoff) +- [TraceBased](#tracebased) -#### AlwaysOn +### AlwaysOn An ExemplarFilter which makes all measurements eligible for being an Exemplar. -#### AlwaysOff +### AlwaysOff An ExemplarFilter which makes no measurements eligible for being an Exemplar. Using this ExemplarFilter is as good as disabling Exemplar feature. -#### TraceBased +### TraceBased An ExemplarFilter which makes those measurements eligible for being an Exemplar, which are recorded in the context of a sampled parent span. -#### Configuration - -The ExemplarFilter SHOULD be a configuration parameter of a `MeterProvider` for -an SDK. The default value SHOULD be `TraceBased`. The filter configuration -SHOULD follow the [environment variable specification](../configuration/sdk-environment-variables.md#exemplar). - ### ExemplarReservoir The `ExemplarReservoir` interface MUST provide a method to offer measurements @@ -1695,8 +1685,6 @@ specific guarantees and safeties. **MeterProvider** - Meter creation, `ForceFlush` and `Shutdown` are safe to be called concurrently. -**ExemplarFilter** - all methods are safe to be called concurrently. - **ExemplarReservoir** - all methods are safe to be called concurrently. **MetricReader** - `Collect`, `ForceFlush` (for periodic exporting MetricReader)