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 Metrics Spec. #1842

Merged
merged 17 commits into from
Aug 19, 2021
Merged

Add details for Aggregator in Metrics Spec. #1842

Changes from 1 commit
Commits
Show all changes
17 commits
Select commit Hold shift + click to select a range
cc3eb35
Aggregator Spec
victlu Jul 30, 2021
bcb60af
Cleanup
victlu Jul 30, 2021
d691f64
Tweaks
victlu Jul 30, 2021
15ca246
tweaks
victlu Jul 30, 2021
01a3749
tweak
victlu Jul 30, 2021
23cdb3f
Fix up nits from PR feedback
victlu Aug 10, 2021
d5851a5
Fix up nits from PR feedback
victlu Aug 10, 2021
df6faaa
Refactor based on SIG meeting feedback
victlu Aug 11, 2021
b7c8fc2
Allow idiomatic approach for Aggregator+Params
victlu Aug 12, 2021
487f360
Add Timestamp for Last Value Aggregator
victlu Aug 12, 2021
9cd2dda
Fix misspelling
victlu Aug 13, 2021
2a49855
Merge branch 'otel-main' into aggregator-spec-2
victlu Aug 13, 2021
a9bfba9
Refactor to use Aggregation (as a config)
victlu Aug 17, 2021
a07fe19
Refactor to use Aggregation (as a config)
victlu Aug 17, 2021
05cdd67
Fix based on PR feedback
victlu Aug 17, 2021
0ee8738
fix misspelling
victlu Aug 17, 2021
74fd5b7
Merge branch 'main' into aggregator-spec-2
jmacd Aug 18, 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
Prev Previous commit
Next Next commit
Fix up nits from PR feedback
  • Loading branch information
@victlu
victlu committed Aug 10, 2021
commit 23cdb3f6f4eb1939e078d4daced3426d8c3f005d
72 changes: 33 additions & 39 deletions specification/metrics/sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -210,10 +210,10 @@ meter_provider
## Aggregator
victlu marked this conversation as resolved.
Show resolved Hide resolved

An `Aggregator` computes incoming Instrument [Measurements](./api.md#measurement)
into [Pre-Aggregated Metrics](./datamodel.md#opentelemetry-protocol-data-model).
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 use to
Aggregators. An [Aggregator Name](./sdk.md#aggregator-name) may be used to
refer to an Aggregator and configuration.

e.g. The View specifies the string name of an Aggregator (i.e. "Histogram")
Expand All @@ -226,14 +226,13 @@ meter_provider
instrument_name = "X",
aggregator = "Histogram");

// Use Histogram with custom boundaries and monotonic values
// Use Histogram with custom boundaries
meter_provider
.add_view(
instrument_name = "X",
aggregator = "Histogram",
victlu marked this conversation as resolved.
Show resolved Hide resolved
aggregator_params = new KeyValuePair<string, object>[]
{
new KeyValuePair<string, object>("Monotonic", true),
new KeyValuePair<string, object>("Boundaries", new double[] { 0.0, 10.0, 100.0 }),
});
```
Expand All @@ -242,25 +241,18 @@ 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. Monotonic=true, Boundaries=[0, 10, 100]).
Default configuration parameters will be use unless overridden by
(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" with incoming Instrument
[Measurement](./api.md#measurement) data.
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"
[Pre-Aggregated Metric](./datamodel.md#timeseries-model) data.
[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.

e.g. When "collect" is acted on a Sum Aggregator, configured for delta
temporality, it will return a delta metric and reset its internal
counts and time-period window. A downstream Exporter, supporting only
cumulative temporality, may choose to 1. drop the delta metric
OR 2. support [Delta to Cumulative](./datamodel.md#sums-delta-to-cumulative)
conversion.

**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
Expand All @@ -277,10 +269,10 @@ The [View](./sdk.md#view) can refer to the following Aggregator by name.
| Gauge | [Last Value Aggregator](./sdk.md#last-value-aggregator) | - |
| Histogram | [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator) | Default |
jsuereth marked this conversation as resolved.
Show resolved Hide resolved

\[1\]: The name "Default" is use to select Aggregator by Instrument Kind.
\[1\]: The name "Default" is used to select Aggregator by Instrument Kind.
See [Default Aggregators](./sdk.md#default-aggregators).

\[2\]: The name "None" is use to specify no Aggregator or
\[2\]: The name "None" is used to specify no Aggregator or
a "virtual" Aggregator which ignores all measurements.

\[3\]: Depends on the Instrument Kind. See [Default Aggregators](./sdk.md#default-aggregators).
Expand All @@ -291,69 +283,71 @@ 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 use the Instrument Kind (e.g. at View registration)
The "Default" Aggregator uses the Instrument Kind (e.g. at View registration)
to select the correct Aggregator and default configuration parameters.

| Instrument Kind | Default Aggregator | Monotonic | Temporality | Boundaries |
| --- | --- | --- | --- | --- |
| [Counter](./api.md#counter) | [Sum Aggregator](./sdk.md#sum-aggregator) | true | Delta | - |
| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregator](./sdk.md#sum-aggregator) | false | Delta | - |
| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregator](./sdk.md#sum-aggregator) | true | Cumulative | - |
| [Asynchrounous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregator](./sdk.md#sum-aggregator) | false | Cumulative | - |
| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregator](./sdk.md#last-value-aggregator) | - | - | - |
| [Histogram](./api.md#histogram) | [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator) | true | Delta | Default<sup>1</sup> |
| Instrument Kind | Default Aggregator | Default Configuration Parameters |
| --- | --- | --- |
| [Counter](./api.md#counter) | [Sum Aggregator](./sdk.md#sum-aggregator) | Temporality = Delta<br>SumType = Monotonic<sup>2</sup> |
jsuereth marked this conversation as resolved.
Show resolved Hide resolved
| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregator](./sdk.md#sum-aggregator) | Temporality = Delta<br>SumType = Non-Monotonic<sup>2</sup> |
| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregator](./sdk.md#sum-aggregator) | Temporality = Cumulative<br>SumType = Monotonic<sup>2</sup> |
| [Asynchrounous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregator](./sdk.md#sum-aggregator) | Temporality = Cumulative<br>SumType = Non-Monotonic<sup>2</sup> |
| [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregator](./sdk.md#last-value-aggregator) | - |
| [Histogram](./api.md#histogram) | [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator) | Temporality = Delta<br>Boundaries = Default<sup>1</sup> |

\[1\]: See Default Bucket Boundaries in [Explicit Bucket Histogram Aggregator](./sdk.md#explicit-bucket-histogram-aggregator).

\[2\]: TBD: See [PR#320](https://github.com/open-telemetry/opentelemetry-proto/pull/320).

### Last Value Aggregator

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

This Aggregator does not have any configuration parameter keys.
This Aggregator does not have any configuration parameters.

This Aggregator reports on:
This Aggregator collects:

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

### Sum Aggregator

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

This Aggregator honors the following configuration parameter keys:
This Aggregator honors the following configuration parameters:

| Key | Value | Default | Description |
| --- | --- | --- | --- |
| Monotonic | boolean | Depends<sup>1</sup> | if true, non-positive values are treated as errors<sup>2</sup>. |
| SumType<sup>2</sup> | Monotonic, Non-Monotonic, Other<sup>2</sup> | Depends<sup>1</sup> | See SumType<sup>2</sup> |
| Temporality | Delta, Cummulative | Depends<sup>1</sup> | See [Temporality](./datamodel.md#temporality). |

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

\[2\]: Language implementation may choose best strategy for handling errors. (i.e. Logged, Discard, etc...)
\[2\]: **TBD**: See [PR#320](https://github.com/open-telemetry/opentelemetry-proto/pull/320).

This Aggregator reports on:
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 collect data for the
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 parameter keys:
This Aggregator honors the following configuration parameters:

| Key | Value | Default | 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 | Delta | See [Temporality](./datamodel.md#temporality). |
| Boundaries | double\[\] | Default<sup>2</sup> | Array of increasing values representing explicit bucket boundary values. |

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

\[2\]: 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;)

This Aggregator reports on:
This Aggregator collects:

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