diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7af4f22c6d3..a3e9dbf3d7a 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -248,6 +248,151 @@ active span](../trace/api.md#context-interaction)). +------------------+ ``` +### Aggregation MeasurementProcessor + +An `Aggregation` `MeasurementProcessor` is responsible for providing incoming +Instrument `Measurements` to the correct [`Aggregator`](#Aggregator) instances. + +The `Aggregation` `MeasurementProcessor` MUST have access to `In-Memory State`. + +The `Aggregation` `MeasurementProcessor` MUST create and configure +[`Aggregators`](#Aggregator) based on [View](#View) configuration. + +e.g. Create a Sum Aggregator with monotonic values and delta temporality. + +The `Aggregation` `MeasurementProcessor` MUST provide `Measurements` to the +correct and properly configured `Aggregators` based on [View](#View) +configuration. + +e.g. A View re-configures a temperature Gauge Instrument to use a Histogram +aggregator with custom bucket boundaries and cumulative temporality. + +e.g. A View re-configures a temperature Gauge Instrument to count by Attribute +"Location" (e.g. "Location=Portland" or "Location=Seattle"). The Aggregation +MeasurementProcessor provides measurements to the Aggregator instance that +handles the specific Attribute Key/Value combination. +(i.e. "Location=Portland" => Aggregator #1, "Location=Seattle" => Aggregator #2) + +e.g. A View re-configures a temperature Gauge Instrument to not provide +measurements to any Aggregator. + +```text + +----------------------------+ + | Aggregation | + | MeasurementProcessor | + | | +-----------------+ + | ... | | | + [Measurements]-----> ... <---------------------->| In-Memory State | + | ... | | | + | | | +-----------------+ + | | +---------------+ | + | | | Aggregator #1 | | + | | | | | + | +---->"Update" | | + | | | ... | | + | | | "Collect"-----------[Pre-Aggregated Metrics]--> + | | +---------------+ | + | | | + | | +---------------+ | + | | | Aggregator #2 | | + | | | | | + | +---->"Update" | | + | | ... | | + | | "Collect"-----------[Pre-Aggregated Metrics]--> + | +---------------+ | + | | + +----------------------------+ +``` + +### Aggregator + +An `Aggregator` computes incoming [Measurements](./api.md#measurement) into +[Pre-Aggregated Metrics](./datamodel.md#opentelemetry-protocol-data-model). + +An `Aggregator` MUST provide a means to "update" with given +[Measurement](./api.md#measurement) data. + +An `Aggregator` MUST provide a means to "collect" +[Pre-Aggregated Metric](./datamodel.md#timeseries-model) data. +The collect call should be treated as a stateful action and may reset its +internal state. + +e.g. When an Exporter (support only Cumulative temporality) collects from +a SumAggregator with delta temporality, the Exporter may drop the metrics OR +support DELTA to CUMULATIVE conversion. + +e.g. When an Exporter (support only Delta temporality) collects from +a SumAggregator with cumulative temporality, the Exporter may drop the metrics +OR support CUMULATIVE to DELTA conversion. + +The SDK MUST provide the following Aggregators to support the +[Metric Points](./datamodel.md#metric-points) in the +[Metrics Data Model](./datamodel.md). + +- [Sum Aggregator](#SumAggregator) +- [Last Value Aggregator](#LastValueAggregator) (For Gauge Metric Point) +- [Explicit Bucket Histogram Aggregator](#ExplicitBucketHistogramAggregator) + +#### SumAggregator + +The Sum Aggregator collect data for the +[Sum Metric Point](./datamodel.md#sums) +and reports the arithmetic sum of seen `Measurements`. +This Aggregator may be configured for monotonicity and temporality. + +A [Default Aggregator](#DefaultAggregators) MUST be provided. + +#### LastValueAggregator + +The Last Value Aggregator collect data for the +[Gauge Metric Point](./datamodel.md#gauge) +and reports the last seen `Measurement`. + +A [Default Aggregator](#DefaultAggregators) MUST be provided. + +#### ExplicitBucketHistogramAggregator + +The Explicit Bucket Histogram Aggregator collect data for the +[Histogram Metric Point](./datamodel.md#histogram) +and reports a histogram with explicit bucket boundaries of seen `Measurements`. +This Aggregator may be configured for custom bucket boundaries, monotonicity, and +temporality. + +A [Default Aggregator](#DefaultAggregators) MUST be provided. + +This Aggregator MUST also report on the arithmetic sum of seen `Measurements`. +The [Histogram Metric Point](./datamodel.md#histogram) requires Sum. + +#### Example of In-Memory State + +The following are examples of `In-Memory State`: + +| Aggregator | In-Memory State | +| --- | --- | +| Sum | Start Time1
Sum (arithmetic sum of measurements) | +| Last Value | Last Timestamp2
Last Value2 | +| Explicit Bucket Histogram | Start Time1
Count (count of points in population)
Sum (arithmetic sum of point values in population)
Bucket Counts (count of values falling within configured Boundary Values) | + +\[1\]: Start Time is exclusive (e.g. not inclusive) of the provided time. + +\[2\]: From last measurement given, avoiding any time comparison. + +### DefaultAggregators + +An `Aggregation` `MeasurementProcessor` MUST provide the following **DEFAULT** +`Aggregators` based on the reporting Instrument. + +| Instrument Kind | Default Aggregator | Monotonic | Temporality | Notes | +| --- | --- | --- | --- | --- | +| [Counter](./api.md#counter) | [Sum Aggregator](#SumAggregator) | Monotonic | Delta | | +| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregator](#SumAggregator) | Monotonic | Cumulative | | +| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregator](#SumAggregator) | Non-Monotonic | Delta | | +| [Asynchrounous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregator](#SumAggregator) | Non-Monotonic | Cumulative | | +| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregator](#LastValueAggregator) | Non-Monotonic | Cumulative | | +| [Histogram](./api.md#histogram) | [Explicit Bucket Histogram Aggregator](#ExplicitBucketHistogramAggregator) | Monotonic | Delta | Default Bucket Boundaries1 | + +\[1\]: Default Bucket Boundaries: (-∞, 0], (0, 5.0], (5.0, 10.0], (10.0, 25.0], (25.0, 50.0], (50.0, 75.0], (75.0, 100.0], (100.0, 250.0], (250.0, 500.0], (500.0, 1000.0], (1000.0, +∞) + ## MetricProcessor `MetricProcessor` is an interface which allows hooks for [pre-aggregated metrics