Skip to content

Commit

Permalink
Fixes #3812 - ExemplarFilter does not need to be exposed as an interf…
Browse files Browse the repository at this point in the history
…ace.
  • Loading branch information
jsuereth committed Jan 17, 2024
1 parent 2580724 commit 792aa84
Showing 1 changed file with 16 additions and 28 deletions.
44 changes: 16 additions & 28 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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)
Expand Down

0 comments on commit 792aa84

Please sign in to comment.