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.

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

Add details for Aggregator in Metrics Spec. #1842

Merged
merged 17 commits into from
Aug 19, 2021
141 changes: 141 additions & 0 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -207,6 +207,147 @@ meter_provider
.set_exporter(ConsoleExporter())
```

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

An `Aggregator` computes incoming Instrument [Measurements](./api.md#measurement)
into [Aggregated Metrics](./datamodel.md#opentelemetry-protocol-data-model).

The [View](./sdk.md#view) informs the SDK on creation and configuration of
Aggregators. An [Aggregator Name](./sdk.md#aggregator-name) may be used to
refer to an Aggregator and configuration.

Implementors may choose the best idiomatic practice for their language to
victlu marked this conversation as resolved.
Show resolved Hide resolved
represent the semantic of an Aggregator and configuration parameters.

e.g. The View specifies an Aggregator by string name (i.e. "Histogram").

```python
# Use Histogram with custom boundaries
meter_provider
victlu marked this conversation as resolved.
Show resolved Hide resolved
.add_view(
"X",
aggregator="Histogram",
aggregator_params={"Boundaries": [0, 10, 100]}
)
```

e.g. The View specifies an Aggregator by class/type instance.

```c#
// Use Histogram with custom boundaries
meterProviderBuilder
.AddView(
instrumentName: "X",
aggregator: new HistogramAggregator(
boundaries: new double[] { 0.0, 10.0, 100.0 }
)
);
```

The [View](./sdk.md#view) informs the SDK to provide correct
Instrument [Measurements](./api.md#measurement) to the correct Aggregators.

An `Aggregator` is created with optional configuration parameters
(i.e. Temporality=Delta, Boundaries=[0, 10, 100]).
Default configuration parameters will be used unless overridden by
optional configuration parameters.

An `Aggregator` has a means to "update" its internal state with incoming
Instrument [Measurement](./api.md#measurement) data.

An `Aggregator` has a means to "collect"
[Aggregated Metric](./datamodel.md#timeseries-model) data.
victlu marked this conversation as resolved.
Show resolved Hide resolved
The "collect" action should be treated as stateful and may update its
internal state.

**TBD**:
The [View](./sdk.md#view) may inform an `Aggregator` to collect
[Examplars](./datamodel.md#exemplars).
victlu marked this conversation as resolved.
Show resolved Hide resolved

### Aggregator Name

The [View](./sdk.md#view) can refer to the following Aggregator by name.

| Name | Aggregator | Description |
| --- | --- | -- |
| None | - | The reserved name "None" specify no Aggregator or a "virtual" Aggregator which ignores all measurements. |
| Default | [Default](./sdk.md#default-aggregator) | The reserved name "Default" select an Aggregator by Instrument Kind. See [Default Aggregator](./sdk.md#default-aggregator). |
| Sum | [Sum Aggregator](./sdk.md#sum-aggregator) | The reserved name "Sum" select a Sum Aggregator and SumType configuration parameter by Instrument Kind. See [Default Aggregator](./sdk.md#default-aggregator). |
| Gauge | [Last Value Aggregator](./sdk.md#last-value-aggregator) | The reserved name "Gauge" select the [Last Value Aggregator](./sdk.md#last-value-aggregator). |
| Histogram | "Best" Histogram | The reserved name "Histogram" select the "best" available Histogram Aggregator. i.e. [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator). |
| Explicit_Bucket_Histogram | [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator) | Select the [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator). |

### Default Aggregator

The SDK MUST provide default Aggregators to support the
[Metric Points](./datamodel.md#metric-points) in the
[Metrics Data Model](./datamodel.md).

The "Default" Aggregator uses the Instrument Kind (e.g. at View registration)
to select an Aggregator and configuration parameters.

| Instrument Kind | Default Aggregator | Configuration Parameters |
| --- | --- | --- |
| [Counter](./api.md#counter) | [Sum Aggregator](./sdk.md#sum-aggregator) | SumType = Monotonic |
| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregator](./sdk.md#sum-aggregator) | SumType = Monotonic |
| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregator](./sdk.md#sum-aggregator) | SumType = Non-Monotonic |
| [Asynchrounous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregator](./sdk.md#sum-aggregator) | SumType = Non-Monotonic |
| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregator](./sdk.md#last-value-aggregator) | - |
| [Histogram](./api.md#histogram) | "Best" Histogram<sup>1</sup> | - |

\[1\]: The SDK will select the "best" available Histogram Aggregator. i.e. [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator).

### Last Value Aggregator

The Last Value Aggregator collects data for the
[Gauge Metric Point](./datamodel.md#gauge).

This Aggregator does not have any configuration parameters.

This Aggregator collects:

- The last `Measurement`.
victlu marked this conversation as resolved.
Show resolved Hide resolved

### Sum Aggregator

The Sum Aggregator collects data for the [Sum Metric Point](./datamodel.md#sums).

This Aggregator honors the following configuration parameters:

| Key | Value | Default Value | Description |
| --- | --- | --- | --- |
| SumType<sup>2</sup> | Monotonic, Non-Monotonic, Other<sup>2</sup> | Depends<sup>1</sup> | See SumType<sup>2</sup> |
| Temporality | Delta, Cummulative | Cummulative | See [Temporality](./datamodel.md#temporality). |
victlu marked this conversation as resolved.
Show resolved Hide resolved

\[1\]: Depends on the Instrument Kind. See [Default Aggregator](./sdk.md#default-aggregator).

\[2\]: **TBD**: See [PR#320](open-telemetry/opentelemetry-proto#320) for SumType definition.
victlu marked this conversation as resolved.
Show resolved Hide resolved

This Aggregator collects:

- The arithmetic sum of `Measurement` values.
victlu marked this conversation as resolved.
Show resolved Hide resolved

### Explicit Bucket Histogram Aggregator

The Explicit Bucket Histogram Aggregator collects data for the
[Histogram Metric Point](./datamodel.md#histogram). It supports a set of
explicit boundary values for histogram bucketing.

This Aggregator honors the following configuration parameters:

| Key | Value | Default Value | Description |
| --- | --- | --- | --- |
| Monotonic | boolean | true | if true, non-positive values are treated as errors<sup>1</sup>. |
victlu marked this conversation as resolved.
Show resolved Hide resolved
| Temporality | Delta, Cummulative | Cummulative | See [Temporality](./datamodel.md#temporality). |
victlu marked this conversation as resolved.
Show resolved Hide resolved
| Boundaries | double\[\] | [ 0, 5, 10, 25, 50, 75, 100, 250, 500, 1000 ] | Array of increasing values representing explicit bucket boundary values.<br><br>The Default Value represents the following buckets:<br>(-&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;) |

\[1\]: Language implementations may choose the best strategy for handling errors. (i.e. Log, Discard, etc...)

This Aggregator collects:

- Count of `Measurement` values falling within explicit bucket boundaries.
- Arithmetic sum of `Measurement` values in population.

## MeasurementProcessor

`MeasurementProcessor` is an interface which allows hooks when a
Expand Down