From 2dfedfe623bda8ae0a90959cdbb00edaa9b4d97b Mon Sep 17 00:00:00 2001 From: Josh Suereth Date: Wed, 31 Jan 2024 13:20:55 -0500 Subject: [PATCH] Expose `ExemplarReservoir` as configuration option of View. (#3820) Fixes #2922 Fixes #3812 Related to #3756 ## Changes - Cleans up language around exposing `ExemplarReservoir`. (Remove TODO, e.g.) - Remove `ExemplarFilter` interface but keep configuration options. (see #3812) - Clarify / simplify Spec Compliance matrix for existing state of the Exemplar Specification. Prototype in java: https://github.com/open-telemetry/opentelemetry-java/pull/5960 --- CHANGELOG.md | 5 + spec-compliance-matrix.md | 238 +++++++++++++++++------------------ specification/metrics/sdk.md | 63 +++++----- 3 files changed, 154 insertions(+), 152 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c78bff6ac42..c6495d32ac7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,11 @@ release. ### Metrics +- Expose `ExemplarReservoir` as configuration parameter for views. + Remove `ExemplarFilter` as an interface, now it is only configuration + parameter. + ([#3820](https://github.com/open-telemetry/opentelemetry-specification/pull/3820)) + ### Logs - Fix `Resource` field type in Logs Data Model. diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index f19a36477f9..10570f92fc6 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -96,125 +96,125 @@ formats is required. Implementing more than one format is optional. ## Metrics -| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | -|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----|------|----|--------|------|--------|-----|------|-----|------|-------| -| The API provides a way to set and get a global default `MeterProvider`. | X | + | + | + | + | | + | + | + | + | - | | -| It is possible to create any number of `MeterProvider`s. | X | + | + | + | + | | + | + | + | + | + | | -| `MeterProvider` provides a way to get a `Meter`. | | + | + | + | + | | + | + | + | + | - | | -| `get_meter` accepts name, `version` and `schema_url`. | | + | + | + | + | | + | + | + | + | - | | -| `get_meter` accepts `attributes`. | | | | | | | | + | + | + | | | -| When an invalid `name` is specified a working `Meter` implementation is returned as a fallback. | | + | + | + | + | | + | | + | + | - | | -| The fallback `Meter` `name` property keeps its original invalid value. | X | - | - | + | + | | + | | + | - | - | | -| Associate `Meter` with `InstrumentationScope`. | | | + | + | + | | + | | + | + | | | -| The meter provides functions to create a new `Counter`. | | + | + | + | + | | + | + | + | + | + | | -| The meter provides functions to create a new `AsynchronousCounter`. | | + | + | + | + | | + | + | + | + | + | | -| The meter provides functions to create a new `Histogram`. | | + | + | + | + | | + | + | + | + | + | | -| The meter provides functions to create a new `AsynchronousGauge`. | | + | + | + | + | | + | + | + | + | + | | -| The meter provides functions to create a new `UpDownCounter`. | | + | + | + | + | | + | + | + | + | + | | -| The meter provides functions to create a new `AsynchronousUpDownCounter`. | | + | + | + | + | | + | + | + | + | + | | -| Instruments have `name` | | + | + | + | + | | + | + | + | + | + | | -| Instruments have kind. | | + | + | + | + | | + | + | + | + | + | | -| Instruments have an optional unit of measure. | | + | + | + | + | | + | + | + | + | + | | -| Instruments have an optional description. | | + | + | + | + | | + | + | + | + | + | | -| A valid instrument MUST be created and warning SHOULD be emitted when multiple instruments are registered under the same `Meter` using the same `name`. | | | + | + | + | | + | | | | | | -| Duplicate instrument registration name conflicts are resolved by using the first-seen for the stream name. | | | + | | | | + | | | | | | -| It is possible to register two instruments with same `name` under different `Meter`s. | | + | + | + | + | | + | | + | + | + | | -| Instrument names conform to the specified syntax. | | + | + | + | + | | + | | | + | | | -| Instrument units conform to the specified syntax. | | - | + | | + | | - | | + | + | + | | -| Instrument descriptions conform to the specified syntax. | | - | + | | - | | - | | | - | + | | -| Instrument supports the advisory ExplicitBucketBoundaries parameter. | | | + | | | | + | | | | | | -| Instrument supports the advisory Attributes parameter. | | | + | | | | - | | | | | | -| `create_counter` returns a `Counter`. | | + | + | + | + | | + | + | + | + | + | | -| The API for `Counter` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | -| `Counter` has an `add` method. | | + | + | + | + | | + | + | + | + | + | | -| The `add` method returns no (or dummy) value. | X | + | + | + | + | | + | + | + | + | + | | -| The `add` method accepts optional attributes. | | + | + | + | + | | + | + | + | + | + | | -| The `add` method accepts the increment amount. | | + | + | + | + | | + | + | + | + | + | | -| The `add` method of `Counter` accepts only positive amounts. | | + | + | + | + | | | | + | + | - | | -| `create_asynchronous_counter` creates an `AsynchronousCounter`. | | + | + | + | + | | + | + | + | + | + | | -| The API for `AsynchronousCounter` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | -| The API for `AsynchronousCounter` accepts a callback. | | + | + | + | + | | + | + | + | + | + | | -| `create_up_down_counter` returns an `UpDownCounter`. | | + | + | + | + | | + | + | + | + | + | | -| The API for `UpDownCounter` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | -| `UpDownCounter` has an `add` method. | | + | + | + | + | | + | + | + | + | + | | -| The `add` method returns no (or dummy) value. | X | + | + | + | + | | + | + | + | + | + | | -| The `add` method accepts optional attributes. | | + | + | + | + | | + | + | + | + | + | | -| The `add` method accepts the increment amount. | | + | + | + | + | | + | + | + | + | + | | -| `create_asynchronous_up_down_counter` creates an `AsynchronousUpDownCounter`. | | + | + | + | + | | + | + | + | + | + | | -| The API for `AsynchronousUpDownCounter` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | -| The API for `AsynchronousUpDownCounter` accepts a callback. | | + | + | + | + | | + | + | + | + | + | | -| `create_histogram` returns a `Histogram`. | | + | + | + | + | | + | + | + | + | + | | -| The API for `Histogram` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | -| `Histogram` has a `record` method. | | + | + | + | + | | + | + | + | + | + | | -| The `record` method return no (or dummy) value. | X | + | + | + | + | | + | + | + | + | + | | -| The `record` method accepts optional attributes. | | + | + | + | + | | + | + | + | + | + | | -| The `record` method accepts a value. | | + | + | + | + | | + | + | + | + | + | | -| The `record` method of `Histogram` accepts only positive amounts. | | - | + | + | + | | + | | + | + | + | | -| `create_asynchronous_gauge` creates an `Asynchronous Gauge`. | | + | + | + | + | | + | + | + | + | + | | -| The API for `AsynchronousGauge` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | -| The API for `AsynchronousGauge` accepts a callback. | | + | + | + | + | | + | + | + | + | + | | -| The callback function of an `Asynchronous` instrument does not block indefinitely. | X | - | - | + | - | | + | | | + | ? | | -| The callback function reports `Measurement`s. | | + | + | + | + | | + | | + | + | + | | -| There is a way to pass state to the callback. | X | + | + | | + | | + | | | + | + | | -| All methods of `MeterProvider` are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | -| All methods of `Meter` are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | -| All methods of any instrument are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | -| `MeterProvider` allows a `Resource` to be specified. | | + | + | + | + | | | + | + | + | + | | -| A specified `Resource` can be associated with all the produced metrics from any `Meter` from the `MeterProvider`. | | + | + | + | + | | | + | + | + | + | | -| The supplied `name`, `version` and `schema_url` arguments passed to the `MeterProvider` are used to create an `InstrumentationLibrary` instance stored in the `Meter`. | | + | - | | + | | | | + | + | - | | -| The supplied `name`, `version` and `schema_url` arguments passed to the `MeterProvider` are used to create an `InstrumentationScope` instance stored in the `Meter`. | | | + | + | | | + | + | + | + | | | -| Configuration is managed solely by the `MeterProvider`. | | + | + | + | + | | + | + | + | + | + | | -| The `MeterProvider` provides methods to update the configuration | X | - | - | - | + | | - | | | - | + | | -| The updated configuration applies to all already returned `Meter`s. | if above | - | - | - | - | | - | | | - | + | | -| There is a way to register `View`s with a `MeterProvider`. | | - | + | + | + | | + | + | + | + | + | | -| The `View` instrument selection criteria is as specified. | | | + | + | + | | + | + | + | + | + | | -| The `View` instrument selection criteria supports wildcards. | X | | + | + | + | | - | | + | + | + | | -| The `View` instrument selection criteria supports the match-all wildcard. | | | + | + | + | | + | | + | + | + | | -| The `View` instrument selection criteria supports a unit. | | + | | | + | | + | | + | | | | -| The name of the `View` can be specified. | | | + | + | + | | + | + | | + | + | | -| The `View` allows configuring the name description, attributes keys and aggregation of the resulting metric stream. | | | + | + | + | | + | + | + | + | - | | -| The `View` allows configuring the exemplar reservoir of resulting metric stream. | X | | - | | - | | - | | | | - | | -| The SDK allows more than one `View` to be specified per instrument. | X | | + | + | + | | + | | + | + | + | | -| The `Drop` aggregation is available. | | + | + | + | + | | + | | + | + | + | | -| The `Drop` aggregation drops all measurements and does not produce a metric stream. | | + | + | + | + | | + | | + | - | + | | -| The `Default` aggregation is available. | | + | + | + | + | | + | | + | + | + | | -| The `Default` aggregation uses the specified aggregation by instrument. | | + | + | + | + | | + | | + | + | + | | -| The `Sum` aggregation is available. | | + | + | + | + | | + | + | + | + | + | | -| The `Sum` aggregation performs as specified. | | + | + | + | + | | + | + | + | + | + | | -| The `LastValue` aggregation is available. | | + | + | + | + | | + | + | + | + | + | | -| The `LastValue` aggregation performs as specified. | | + | + | + | + | | + | + | + | + | + | | -| The `ExplicitBucketHistogram` aggregation is available. | | - | + | + | + | | + | + | + | + | + | | -| The `ExplicitBucketHistogram` aggregation performs as specified. | | - | + | + | + | | + | + | + | + | + | | -| The `ExponentialBucketHistogram` aggregation is available. | | | | | | | - | | | | + | | -| The `ExponentialBucketHistogram` aggregation performs as specified. | | | | | | | - | | | | + | | -| The metrics Reader implementation supports registering metric Exporters | | | + | + | + | | + | + | + | + | + | | -| The metrics Reader implementation supports configuring the default aggregation on the basis of instrument kind. | | | + | | + | | + | | | - | - | | -| The metrics Reader implementation supports configuring the default temporality on the basis of instrument kind. | | | + | + | + | | + | | + | + | | | -| The metrics Exporter has access to the aggregated metrics data (aggregated points, not raw measurements). | | + | + | + | + | | + | | + | + | + | | -| The metrics Exporter `export` function can not be called concurrently from the same Exporter instance. | | + | + | + | - | | + | | | + | + | | -| The metrics Exporter `export` function does not block indefinitely. | | + | + | + | - | | + | | | + | + | | -| The metrics Exporter `export` function receives a batch of metrics. | | + | + | + | + | | + | + | + | + | + | | -| The metrics Exporter `export` function returns `Success` or `Failure`. | | + | + | + | + | | + | + | + | + | + | | -| The metrics Exporter provides a `ForceFlush` function. | | - | + | + | - | | + | + | + | + | + | | -| The metrics Exporter `ForceFlush` can inform the caller whether it succeeded, failed or timed out. | | | + | + | - | | + | + | | + | + | | -| The metrics Exporter provides a `shutdown` function. | | + | + | + | - | | + | + | + | + | + | | -| The metrics Exporter `shutdown` function do not block indefinitely. | | + | + | + | - | | + | | | + | + | | -| The metrics SDK samples `Exemplar`s from measurements. | | | + | | - | | - | | | | - | | -| Exemplar sampling can be disabled. | | | - | | - | | - | | | | - | | -| The metrics SDK samples measurements in the context of a sampled trace by default. | | | + | | - | | - | | | | - | | -| Exemplars retain any attributes available in the measurement that are not preserved by aggregation or view configuration. | | | + | | - | | - | | | | - | | -| Exemplars contain the associated trace id and span id of the active span in the Context when the measurement was taken. | | | + | | - | | - | | | | - | | -| Exemplars contain the timestamp when the measurement was taken. | | | + | | - | | - | | | | - | | -| The metrics SDK provides an `ExemplarReservoir` interface or extension point. | X | | - | | - | | - | + | | | - | | -| An `ExemplarReservoir` has an `offer` method with access to the measurement value, attributes, `Context` and timestamp. | X | | - | | - | | - | + | | | - | | -| The metrics SDK provides a `SimpleFixedSizeExemplarReservoir` that is used by default for all aggregations except `ExplicitBucketHistogram`. | | | + | | - | | - | + | | | - | | -| The default size of the `SimpleFixedSizeExemplarReservoir` is `1`. | | | | | | | - | | | | | | -| The metrics SDK provides an `AlignedHistogramBucketExemplarReservoir` that is used by default for `ExplicitBucketHistogram` aggregation. | | | + | | - | | - | | | | - | | -| The metrics SDK provides an `ExemplarFilter` interface or extension point. | X | | - | | - | | - | + | | | - | | -| An `ExemplarFilter` has access to the measurement value, attributes, `Context` and timestamp. | X | | - | | - | | - | + | | | - | | -| A metric Producer accepts an optional metric Filter | | | | | | | - | | | | | | -| The metric Reader implementation supports registering metric Filter and passing them its registered metric Producers | | | | | | | - | | | | | | -| The metric SDK's metric Producer implementations uses the metric Filter | | | | | | | - | | | | | | +| Feature | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|----|------|-----|--------|------|--------|-----|------|-----|------|-------| +| The API provides a way to set and get a global default `MeterProvider`. | X | + | + | + | + | | + | + | + | + | - | | +| It is possible to create any number of `MeterProvider`s. | X | + | + | + | + | | + | + | + | + | + | | +| `MeterProvider` provides a way to get a `Meter`. | | + | + | + | + | | + | + | + | + | - | | +| `get_meter` accepts name, `version` and `schema_url`. | | + | + | + | + | | + | + | + | + | - | | +| `get_meter` accepts `attributes`. | | | | | | | | + | + | + | | | +| When an invalid `name` is specified a working `Meter` implementation is returned as a fallback. | | + | + | + | + | | + | | + | + | - | | +| The fallback `Meter` `name` property keeps its original invalid value. | X | - | - | + | + | | + | | + | - | - | | +| Associate `Meter` with `InstrumentationScope`. | | | + | + | + | | + | | + | + | | | +| The meter provides functions to create a new `Counter`. | | + | + | + | + | | + | + | + | + | + | | +| The meter provides functions to create a new `AsynchronousCounter`. | | + | + | + | + | | + | + | + | + | + | | +| The meter provides functions to create a new `Histogram`. | | + | + | + | + | | + | + | + | + | + | | +| The meter provides functions to create a new `AsynchronousGauge`. | | + | + | + | + | | + | + | + | + | + | | +| The meter provides functions to create a new `UpDownCounter`. | | + | + | + | + | | + | + | + | + | + | | +| The meter provides functions to create a new `AsynchronousUpDownCounter`. | | + | + | + | + | | + | + | + | + | + | | +| Instruments have `name` | | + | + | + | + | | + | + | + | + | + | | +| Instruments have kind. | | + | + | + | + | | + | + | + | + | + | | +| Instruments have an optional unit of measure. | | + | + | + | + | | + | + | + | + | + | | +| Instruments have an optional description. | | + | + | + | + | | + | + | + | + | + | | +| A valid instrument MUST be created and warning SHOULD be emitted when multiple instruments are registered under the same `Meter` using the same `name`. | | | + | + | + | | + | | | | | | +| Duplicate instrument registration name conflicts are resolved by using the first-seen for the stream name. | | | + | | | | + | | | | | | +| It is possible to register two instruments with same `name` under different `Meter`s. | | + | + | + | + | | + | | + | + | + | | +| Instrument names conform to the specified syntax. | | + | + | + | + | | + | | | + | | | +| Instrument units conform to the specified syntax. | | - | + | | + | | - | | + | + | + | | +| Instrument descriptions conform to the specified syntax. | | - | + | | - | | - | | | - | + | | +| Instrument supports the advisory ExplicitBucketBoundaries parameter. | | | + | | | | + | | | | | | +| Instrument supports the advisory Attributes parameter. | | | + | | | | - | | | | | | +| `create_counter` returns a `Counter`. | | + | + | + | + | | + | + | + | + | + | | +| The API for `Counter` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | +| `Counter` has an `add` method. | | + | + | + | + | | + | + | + | + | + | | +| The `add` method returns no (or dummy) value. | X | + | + | + | + | | + | + | + | + | + | | +| The `add` method accepts optional attributes. | | + | + | + | + | | + | + | + | + | + | | +| The `add` method accepts the increment amount. | | + | + | + | + | | + | + | + | + | + | | +| The `add` method of `Counter` accepts only positive amounts. | | + | + | + | + | | | | + | + | - | | +| `create_asynchronous_counter` creates an `AsynchronousCounter`. | | + | + | + | + | | + | + | + | + | + | | +| The API for `AsynchronousCounter` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | +| The API for `AsynchronousCounter` accepts a callback. | | + | + | + | + | | + | + | + | + | + | | +| `create_up_down_counter` returns an `UpDownCounter`. | | + | + | + | + | | + | + | + | + | + | | +| The API for `UpDownCounter` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | +| `UpDownCounter` has an `add` method. | | + | + | + | + | | + | + | + | + | + | | +| The `add` method returns no (or dummy) value. | X | + | + | + | + | | + | + | + | + | + | | +| The `add` method accepts optional attributes. | | + | + | + | + | | + | + | + | + | + | | +| The `add` method accepts the increment amount. | | + | + | + | + | | + | + | + | + | + | | +| `create_asynchronous_up_down_counter` creates an `AsynchronousUpDownCounter`. | | + | + | + | + | | + | + | + | + | + | | +| The API for `AsynchronousUpDownCounter` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | +| The API for `AsynchronousUpDownCounter` accepts a callback. | | + | + | + | + | | + | + | + | + | + | | +| `create_histogram` returns a `Histogram`. | | + | + | + | + | | + | + | + | + | + | | +| The API for `Histogram` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | +| `Histogram` has a `record` method. | | + | + | + | + | | + | + | + | + | + | | +| The `record` method return no (or dummy) value. | X | + | + | + | + | | + | + | + | + | + | | +| The `record` method accepts optional attributes. | | + | + | + | + | | + | + | + | + | + | | +| The `record` method accepts a value. | | + | + | + | + | | + | + | + | + | + | | +| The `record` method of `Histogram` accepts only positive amounts. | | - | + | + | + | | + | | + | + | + | | +| `create_asynchronous_gauge` creates an `Asynchronous Gauge`. | | + | + | + | + | | + | + | + | + | + | | +| The API for `AsynchronousGauge` accepts the name, unit and description of the instrument. | | + | + | + | + | | + | + | + | + | + | | +| The API for `AsynchronousGauge` accepts a callback. | | + | + | + | + | | + | + | + | + | + | | +| The callback function of an `Asynchronous` instrument does not block indefinitely. | X | - | - | + | - | | + | | | + | ? | | +| The callback function reports `Measurement`s. | | + | + | + | + | | + | | + | + | + | | +| There is a way to pass state to the callback. | X | + | + | | + | | + | | | + | + | | +| All methods of `MeterProvider` are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | +| All methods of `Meter` are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | +| All methods of any instrument are safe to be called concurrently. | | + | + | + | - | | + | | | + | + | | +| `MeterProvider` allows a `Resource` to be specified. | | + | + | + | + | | | + | + | + | + | | +| A specified `Resource` can be associated with all the produced metrics from any `Meter` from the `MeterProvider`. | | + | + | + | + | | | + | + | + | + | | +| The supplied `name`, `version` and `schema_url` arguments passed to the `MeterProvider` are used to create an `InstrumentationLibrary` instance stored in the `Meter`. | | + | - | | + | | | | + | + | - | | +| The supplied `name`, `version` and `schema_url` arguments passed to the `MeterProvider` are used to create an `InstrumentationScope` instance stored in the `Meter`. | | | + | + | | | + | + | + | + | | | +| Configuration is managed solely by the `MeterProvider`. | | + | + | + | + | | + | + | + | + | + | | +| The `MeterProvider` provides methods to update the configuration | X | - | - | - | + | | - | | | - | + | | +| The updated configuration applies to all already returned `Meter`s. | if above | - | - | - | - | | - | | | - | + | | +| There is a way to register `View`s with a `MeterProvider`. | | - | + | + | + | | + | + | + | + | + | | +| The `View` instrument selection criteria is as specified. | | | + | + | + | | + | + | + | + | + | | +| The `View` instrument selection criteria supports wildcards. | X | | + | + | + | | - | | + | + | + | | +| The `View` instrument selection criteria supports the match-all wildcard. | | | + | + | + | | + | | + | + | + | | +| The `View` instrument selection criteria supports a unit. | | + | | | + | | + | | + | | | | +| The name of the `View` can be specified. | | | + | + | + | | + | + | | + | + | | +| The `View` allows configuring the name description, attributes keys and aggregation of the resulting metric stream. | | | + | + | + | | + | + | + | + | - | | +| The `View` allows configuring the exemplar reservoir of resulting metric stream. | X | | - | | - | | - | | | | - | | +| The SDK allows more than one `View` to be specified per instrument. | X | | + | + | + | | + | | + | + | + | | +| The `Drop` aggregation is available. | | + | + | + | + | | + | | + | + | + | | +| The `Drop` aggregation drops all measurements and does not produce a metric stream. | | + | + | + | + | | + | | + | - | + | | +| The `Default` aggregation is available. | | + | + | + | + | | + | | + | + | + | | +| The `Default` aggregation uses the specified aggregation by instrument. | | + | + | + | + | | + | | + | + | + | | +| The `Sum` aggregation is available. | | + | + | + | + | | + | + | + | + | + | | +| The `Sum` aggregation performs as specified. | | + | + | + | + | | + | + | + | + | + | | +| The `LastValue` aggregation is available. | | + | + | + | + | | + | + | + | + | + | | +| The `LastValue` aggregation performs as specified. | | + | + | + | + | | + | + | + | + | + | | +| The `ExplicitBucketHistogram` aggregation is available. | | - | + | + | + | | + | + | + | + | + | | +| The `ExplicitBucketHistogram` aggregation performs as specified. | | - | + | + | + | | + | + | + | + | + | | +| The `ExponentialBucketHistogram` aggregation is available. | | | | | | | | | | | + | | +| The `ExponentialBucketHistogram` aggregation performs as specified. | | | | | | | | | | | + | | +| The metrics Reader implementation supports registering metric Exporters | | | + | + | + | | + | + | + | + | + | | +| The metrics Reader implementation supports configuring the default aggregation on the basis of instrument kind. | | | + | | + | | + | | | - | - | | +| The metrics Reader implementation supports configuring the default temporality on the basis of instrument kind. | | | + | + | + | | + | | + | + | | | +| The metrics Exporter has access to the aggregated metrics data (aggregated points, not raw measurements). | | + | + | + | + | | + | | + | + | + | | +| The metrics Exporter `export` function can not be called concurrently from the same Exporter instance. | | + | + | + | - | | + | | | + | + | | +| The metrics Exporter `export` function does not block indefinitely. | | + | + | + | - | | + | | | + | + | | +| The metrics Exporter `export` function receives a batch of metrics. | | + | + | + | + | | + | + | + | + | + | | +| The metrics Exporter `export` function returns `Success` or `Failure`. | | + | + | + | + | | + | + | + | + | + | | +| The metrics Exporter provides a `ForceFlush` function. | | - | + | + | - | | + | + | + | + | + | | +| The metrics Exporter `ForceFlush` can inform the caller whether it succeeded, failed or timed out. | | | + | + | - | | + | + | | + | + | | +| The metrics Exporter provides a `shutdown` function. | | + | + | + | - | | + | + | + | + | + | | +| The metrics Exporter `shutdown` function do not block indefinitely. | | + | + | + | - | | + | | | + | + | | +| The metrics SDK samples `Exemplar`s from measurements. | | | + | | - | | - | | | | - | | +| Exemplar sampling can be disabled. | | | - | | - | | - | | | | - | | +| The metrics SDK supports SDK-wide exemplar filter configuration | | | + | | - | | - | | | | - | | +| The metrics SDK supports `TraceBased` exemplar filter | | | + | | - | | - | | | | - | | +| The metrics SDK supports `AlwaysOn` exemplar filter | | | + | | - | | - | | | | - | | +| The metrics SDK supports `AlwaysOff` exemplar filter | | | + | | - | | - | | | | - | | +| Exemplars retain any attributes available in the measurement that are not preserved by aggregation or view configuration. | | | + | | - | | - | | | | - | | +| Exemplars contain the associated trace id and span id of the active span in the Context when the measurement was taken. | | | + | | - | | - | | | | - | | +| Exemplars contain the timestamp when the measurement was taken. | | | + | | - | | - | | | | - | | +| The metrics SDK provides an `ExemplarReservoir` interface or extension point. | X | | - | | - | | - | + | | | - | | +| An `ExemplarReservoir` has an `offer` method with access to the measurement value, attributes, `Context` and timestamp. | X | | - | | - | | - | + | | | - | | +| The metrics SDK provides a `SimpleFixedSizeExemplarReservoir` that is used by default for all aggregations except `ExplicitBucketHistogram`. | | | + | | - | | - | + | | | - | | +| The metrics SDK provides an `AlignedHistogramBucketExemplarReservoir` that is used by default for `ExplicitBucketHistogram` aggregation. | | | + | | - | | - | | | | - | | +| A metric Producer accepts an optional metric Filter | | | | | | | - | | | | | | +| The metric Reader implementation supports registering metric Filter and passing them its registered metric Producers | | | | | | | - | | | | | | +| The metric SDK's metric Producer implementations uses the metric Filter | | | | | | | - | | | | | | ## Logs diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index d0c005a4ec0..32971ceaca6 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -50,15 +50,14 @@ linkTitle: SDK - [Attribute limits](#attribute-limits) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) - * [Built-in ExemplarFilters](#built-in-exemplarfilters) + [AlwaysOn](#alwayson) + [AlwaysOff](#alwaysoff) + [TraceBased](#tracebased) - + [Configuration](#configuration-2) * [ExemplarReservoir](#exemplarreservoir) * [Exemplar defaults](#exemplar-defaults) + [SimpleFixedSizeExemplarReservoir](#simplefixedsizeexemplarreservoir) + [AlignedHistogramBucketExemplarReservoir](#alignedhistogrambucketexemplarreservoir) + * [Custom ExemplarReservoir](#custom-exemplarreservoir) - [MetricReader](#metricreader) * [MetricReader operations](#metricreader-operations) + [Collect](#collect) @@ -344,7 +343,7 @@ The SDK MUST accept the following stream configuration parameters: user does not provide an `aggregation` value, the `MeterProvider` MUST apply a [default aggregation](#default-aggregation) configurable on the basis of instrument type according to the [MetricReader](#metricreader) instance. -* **Status**: [Feature-freeze](../document-status.md) - `exemplar_reservoir`: A +* **Status**: [Experimental, Feature-freeze](../document-status.md) - `exemplar_reservoir`: A functional type that generates an exemplar reservoir a `MeterProvider` will use when storing exemplars. This functional type needs to be a factory or callback similar to aggregation selection functionality which allows @@ -515,10 +514,6 @@ meterProviderBuilder ); ``` -TODO: after we release the initial Stable version of Metrics SDK specification, -we will explore how to allow configuring custom -[ExemplarReservoir](#exemplarreservoir)s with the [View](#view) API. - The SDK MUST provide the following `Aggregation` to support the [Metric Points](./data-model.md#metric-points) in the [Metrics Data Model](./data-model.md). @@ -897,7 +892,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 @@ -952,31 +947,27 @@ 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. - -This interface SHOULD have access to: +The `ExemplarFilter` configuration MUST allow users to select between one of the +built-in ExemplarFilters. While `ExemplarFilter` determines which measurements +are _eligible_ for becoming an `Exemplar`, the `ExemplarReservoir` makes the +final decision if a measurement becomes an exemplar and is stored. -- 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 @@ -992,12 +983,6 @@ Using this ExemplarFilter is as good as disabling Exemplar feature. 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 @@ -1048,7 +1033,7 @@ The `ExemplarReservoir` SHOULD avoid allocations when sampling exemplars. ### Exemplar defaults -The SDK SHOULD include two types of built-in exemplar reservoirs: +The SDK MUST include two types of built-in exemplar reservoirs: 1. `SimpleFixedSizeExemplarReservoir` 2. `AlignedHistogramBucketExemplarReservoir` @@ -1112,6 +1097,20 @@ measurements using the equivalent of the following naive algorithm: return boundaries.length ``` +This Exemplar reservoir MAY take a configuration parameter for the bucket +boundaries used by the reservoir. The size of the reservoir is always the +number of bucket boundaries plus one. This configuration parameter SHOULD have +the same format as specifying bucket boundaries to +[Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation). + +### Custom ExemplarReservoir + +The SDK MUST provide a mechanism for SDK users to provide their own +ExemplarReservoir implementation. This extension MUST be configurable on +a metric [View](#view), although individual reservoirs MUST still be +instantiated per metric-timeseries (see +[Exemplar Reservoir - Paragraph 2](#exemplarreservoir)). + ## MetricReader **Status**: [Stable](../document-status.md) @@ -1699,8 +1698,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)