Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add details for Aggregator in Metric spec #1804

Closed
wants to merge 11 commits into from
Closed

Add details for Aggregator in Metric spec #1804

Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
ba5e8c3
Add details for Aggregator in Metric spec
victlu Jul 7, 2021
2c86ea5
Fix mispelling
victlu Jul 7, 2021
885c6f3
Updates based on PR feedback.
victlu Jul 8, 2021
fb6a357
Updates per PR feedback.
victlu Jul 19, 2021
c3e3912
Updates per PR feedback.
victlu Jul 19, 2021
37906d0
Updates based on PR feedback
victlu Jul 26, 2021
1219f3b
Add examples of in-memory state.
victlu Jul 26, 2021
78a7faf
Mix misspelling
victlu Jul 26, 2021
8b05ed6
Fix misspellings
victlu Jul 27, 2021
bea5f83
Merge branch 'main' into aggregator-spec
victlu Jul 27, 2021
d0b8730
Update Links and add footnote for bucket boundaries
victlu Jul 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
145 changes: 145 additions & 0 deletions specification/metrics/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -248,6 +248,151 @@ active span](../trace/api.md#context-interaction)).
+------------------+
```

### Aggregation MeasurementProcessor
victlu marked this conversation as resolved.
Show resolved Hide resolved

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
victlu marked this conversation as resolved.
Show resolved Hide resolved

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 Time<sup>1</sup><br>Sum (arithmetic sum of measurements) |
| Last Value | Last Timestamp<sup>2</sup><br>Last Value<sup>2</sup> |
| Explicit Bucket Histogram | Start Time<sup>1</sup><br>Count (count of points in population)<br>Sum (arithmetic sum of point values in population)<br>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 Boundaries<sup>1</sup> |

\[1\]: Default Bucket Boundaries: (-&infin;, 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, +&infin;)
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to specify a default unit of measure for this?


victlu marked this conversation as resolved.
Show resolved Hide resolved
## MetricProcessor

`MetricProcessor` is an interface which allows hooks for [pre-aggregated metrics
Expand Down