From ba5e8c370c9e99d8336cf62ebc1b4d7c95923711 Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Wed, 7 Jul 2021 16:19:39 -0700 Subject: [PATCH 01/10] Add details for Aggregator in Metric spec --- specification/metrics/sdk.md | 152 +++++++++++++++++++++++++++++++++++ 1 file changed, 152 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 513f88ca4c8..1227a777bc8 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -81,6 +81,158 @@ active span](../trace/api.md#context-interaction)). +------------------+ ``` +### Aggregator + +An `Aggregator` is a type of `MeasurementProcessor` and computes "aggregate" +data from [Measurements](./api.md#measurement) and its `In-Memory State` into +[Pre-Aggregated Metric](./datamodel.md#timeseries-model). + +```text + + +---------------------+ + | Aggregator | + | | + [Measurements]------> "Aggregate" | + | | | + | +-------V---------+ | + | | | | + | | In-Memory State | | + | | | | + | +-------+---------+ | + | | | + | V | + | "Collect" +------[Pre-Aggregated Metrics]--> + | | + +---------------------+ +``` + +An `Aggregator` MUST provide an interface to "aggregate" [Measurement](./api.md#measurement) +data into its `In-Memory State`. + +An `Aggregator` MUST provide an interface to "collect" [Pre-Aggregated Metric](./datamodel.md#timeseries-model) +data from its `In-Memory State`. The collect call should be treated as a +stateful action and may reset in-memory state data. e.g. Resetting the time window +for delta temporality instruments. + +An `Aggregator` MUST have read/write access to memory storage (`In-Memory +State`) where it can store/retreive/manage its own internal state. + +Note: SDK SHOULD provide configuration and control for memory availability to +optimize usage. Aggregators MUST log errors when memory limits are reached +and/or data lost occurs due to memory mitigation strategy. (e.g dropping high +cardinality attributes). + +An `Aggregator` MUST have access to or given the [View](./sdk.md#view) +configuration so it can be properly configure. e.g. Configure a Sum aggregator +for Monoticity and Temporality. + +SDK MUST route measurements to the configured aggregator/s. e.g. SDK +expand a measurement's Attributes to key/value pair combinations, and route +measurements for each distinct key/value pair combinations to zero or more +aggregator/s. + +SDK MUST provide aggregators to support the default configured aggregator +per instrument kind. e.g. Counter instruments default to a "Sum" aggregator +configured for monotonic values. + +### Last Value Aggregator + +The Last Value Aggregator collect data for the [Gauge Metric Point](./datamodel.md#gauge) +and is default aggregator for the following instruments. + +* [Asynchronous Gauge](./api.md#asynchronous-gauge) instrument. + +Last Value Aggregator maintains the following in memory: + +* Last Value (latest Measurement given, avoid any time comparison.) + +### Sum Aggregator + +The Sum Aggregator collect data for the [Sum Metric Point](./datamodel.md#sums) +and is default aggregator for the following instruments. + +* [Counter](./api.md#counter) instruments. +* [UpDown Counter](./api.md#updown-counter) instruments. +* [Asynchronous Counter](./api.md#asynchronous-counter) instruments. +* [Asynchronous UpDown Counter](./api.md#asynchronous-updown-counter) instruments. + +The Sum Aggregator MUST be configurable to support different Monoticity and/or +Temporality. + +Sum Aggregator maintains the following in memory: + +* Time window (e.g. start time, end time) +* Sum (sum of Measurements per Monoticity and Temporality configuration.) + +### Histogram Aggregator + +The Histogram Aggregator collect data for the [Histogram Metric Point](./datamodel.md#histogram) +and is default aggregator for the following instruments. + +* [Histogram](./api.md#histogram) instruments. + +The Histogram Aggregator MUST be configurable to support different Temporality. + +Histogram Aggregator maintains the following in memory: + +* Time window (e.g. start time, end time) +* Count +* Sum +* Bucket Counts (per configured boundaries) + +### An example of SDK implementation + +SDK expand each Measurement's Attribute by the combination of key/value pairs. +For each distinct combination, SDK will route to an instance of a configured +aggregator. + +```text ++------------------+ +-------------------------------------------------------------+ +| MeterProvider | | SDK | +| Meter A | | +----------------------+ | +| Instrument X |-----[Measurements]---->| MeasurementProcessor | | +| Instrument Y | | +-----------+----------+ | +| ... | | | | +| ... | | [Measurements] | ++------------------+ | | | + | SDK expand Measurements per View configuration | + | (e.g. by Attribute key/value pairs) | + | | | + | |"Aggregate" | + | Measurement #1: V | + | +---------------------+ | + | B=Y ----------->| Aggregator #1 (B=Y) |---->+ | + | | In-Memory State: | | | + | | count=1 | | | + | +---------------------+ | | + | A=X -------+ | | + | | +---------------------+ | | + | Measurment #2: +--->| Aggregator #2 (A=X) |---->| | + | | | In-Memory State: | | | + | | | count=2 | | | + | | +---------------------+ | | + | A=X -------+ | | + | +---------------------+ | | + | B=Z ----------->| Aggregator #3 (B=Z) |---->| | + | | In-Memory State: | | | + | | count=1 | | | + | +---------------------+ | | + | |"Collect" | + | | | + | [Metrics] | + | | | + | +---------V-------+ | + | | MetricProcessor | | + | +---------+-------+ | + | | | + | [Metrics] | + | | | + | +---------V-------+ | + | | MetricExporter |=====> OTLP Collector + | +-----------------+ | + +-------------------------------------------------------------+ +``` + ## MetricProcessor `MetricProcessor` is an interface which allows hooks for [pre-aggregated metrics From 2c86ea59544586c3b3c239db8fbf1aa2d1b61593 Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Wed, 7 Jul 2021 16:30:41 -0700 Subject: [PATCH 02/10] Fix mispelling --- specification/metrics/sdk.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 1227a777bc8..995728f19fd 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -115,14 +115,14 @@ stateful action and may reset in-memory state data. e.g. Resetting the time wind for delta temporality instruments. An `Aggregator` MUST have read/write access to memory storage (`In-Memory -State`) where it can store/retreive/manage its own internal state. +State`) where it can store/retrieve/manage its own internal state. Note: SDK SHOULD provide configuration and control for memory availability to optimize usage. Aggregators MUST log errors when memory limits are reached and/or data lost occurs due to memory mitigation strategy. (e.g dropping high cardinality attributes). -An `Aggregator` MUST have access to or given the [View](./sdk.md#view) +An `Aggregator` MUST have access to or given the [View](./sdk.md) configuration so it can be properly configure. e.g. Configure a Sum aggregator for Monoticity and Temporality. @@ -151,10 +151,10 @@ Last Value Aggregator maintains the following in memory: The Sum Aggregator collect data for the [Sum Metric Point](./datamodel.md#sums) and is default aggregator for the following instruments. -* [Counter](./api.md#counter) instruments. -* [UpDown Counter](./api.md#updown-counter) instruments. -* [Asynchronous Counter](./api.md#asynchronous-counter) instruments. -* [Asynchronous UpDown Counter](./api.md#asynchronous-updown-counter) instruments. +* [Counter](./api.md#counter) instrument. +* [Asynchronous Counter](./api.md#asynchronous-counter) instrument. +* [UpDownCounter](./api.md#updowncounter) instrument. +* [Asynchrounous UpDownCounter](./api.md#asynchronous-updowncounter) instrument. The Sum Aggregator MUST be configurable to support different Monoticity and/or Temporality. @@ -169,7 +169,7 @@ Sum Aggregator maintains the following in memory: The Histogram Aggregator collect data for the [Histogram Metric Point](./datamodel.md#histogram) and is default aggregator for the following instruments. -* [Histogram](./api.md#histogram) instruments. +* [Histogram](./api.md#histogram) instrument. The Histogram Aggregator MUST be configurable to support different Temporality. From 885c6f378cb4a27fa560213902514a653751d719 Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Thu, 8 Jul 2021 16:00:26 -0700 Subject: [PATCH 03/10] Updates based on PR feedback. --- specification/metrics/sdk.md | 59 ++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 19 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 995728f19fd..cdd4706c7c9 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -85,7 +85,7 @@ active span](../trace/api.md#context-interaction)). An `Aggregator` is a type of `MeasurementProcessor` and computes "aggregate" data from [Measurements](./api.md#measurement) and its `In-Memory State` into -[Pre-Aggregated Metric](./datamodel.md#timeseries-model). +zero or more [Pre-Aggregated Metrics](./datamodel.md#timeseries-model). ```text @@ -119,17 +119,31 @@ State`) where it can store/retrieve/manage its own internal state. Note: SDK SHOULD provide configuration and control for memory availability to optimize usage. Aggregators MUST log errors when memory limits are reached -and/or data lost occurs due to memory mitigation strategy. (e.g dropping high -cardinality attributes). +and/or data lost occurs due to memory mitigation strategy. e.g dropping high +cardinality attributes. -An `Aggregator` MUST have access to or given the [View](./sdk.md) -configuration so it can be properly configure. e.g. Configure a Sum aggregator -for Monoticity and Temporality. +SDK MUST instantiate and configure aggregator/s based on [View](./sdk.md) +configuration. e.g. Create a Sum aggregator with monotonic values and delta +temporality (per mapping/routing). -SDK MUST route measurements to the configured aggregator/s. e.g. SDK -expand a measurement's Attributes to key/value pair combinations, and route -measurements for each distinct key/value pair combinations to zero or more -aggregator/s. +SDK MUST map/route measurements, based on [View](./sdk.md) configuration, to the +configured aggregator/s. Each map/route has zero or more instances of +aggregators. + +e.g. [View](./sdk.md) configuration specify which Attribute Keys to include, +thus creating a map/route per configured Key/Value combination. The measurement +is routed to each route and its configured aggregator/s. + +e.g. Support for multiple exporters creates a map/route per Exporter. The +measurement is routed to each route and its configured aggregator/s. + +**Note:** An `Aggregator` instance is scoped to "aggregate" values that result +in one metric timeseries (see [Metrics Data Model](./datamodel.md)). The SDK +(via the [View](./sdk.md) configuration) allows Measurements to map/route into +zero or more resulting metric timeseries (aka Aggregators). One map/route scheme +involve expanding measurement `Attributes` to combinations of keys and values. +The SDK will facilitate this map/route scheme. Thus, SDK will create and +configure aggregators and route measurments to these aggregator instances. SDK MUST provide aggregators to support the default configured aggregator per instrument kind. e.g. Counter instruments default to a "Sum" aggregator @@ -138,18 +152,21 @@ configured for monotonic values. ### Last Value Aggregator The Last Value Aggregator collect data for the [Gauge Metric Point](./datamodel.md#gauge) -and is default aggregator for the following instruments. +and is default aggregator for the following instruments: * [Asynchronous Gauge](./api.md#asynchronous-gauge) instrument. Last Value Aggregator maintains the following in memory: -* Last Value (latest Measurement given, avoid any time comparison.) +* Last Timestamp1 +* Last Value1 + +\[1\]: Data from latest Measurement given, avoiding any time comparison. ### Sum Aggregator The Sum Aggregator collect data for the [Sum Metric Point](./datamodel.md#sums) -and is default aggregator for the following instruments. +and is default aggregator for the following instruments: * [Counter](./api.md#counter) instrument. * [Asynchronous Counter](./api.md#asynchronous-counter) instrument. @@ -167,18 +184,22 @@ Sum Aggregator maintains the following in memory: ### Histogram Aggregator The Histogram Aggregator collect data for the [Histogram Metric Point](./datamodel.md#histogram) -and is default aggregator for the following instruments. +and is default aggregator for the following instruments: * [Histogram](./api.md#histogram) instrument. -The Histogram Aggregator MUST be configurable to support different Temporality. +The Histogram Aggregator MUST be configurable to support different Temporality +and bucket Boundary Values. Histogram Aggregator maintains the following in memory: -* Time window (e.g. start time, end time) -* Count -* Sum -* Bucket Counts (per configured boundaries) +* Start Time2 +* Count (count of points in population) +* Sum (sum of point values in population) +* Boundary Values +* Bucket Counts (count of values falling within configured Boundary Values) + +\[2\]: Start Time is exclusive (aka not inclusive) of the provided time. ### An example of SDK implementation From fb6a3571b4bc3ea62ccd8af0be4f2ff22f9a3194 Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Mon, 19 Jul 2021 16:08:14 -0700 Subject: [PATCH 04/10] Updates per PR feedback. --- specification/metrics/sdk.md | 223 +++++++++++++---------------------- 1 file changed, 85 insertions(+), 138 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index cdd4706c7c9..118b1f0005f 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -81,178 +81,125 @@ active span](../trace/api.md#context-interaction)). +------------------+ ``` -### Aggregator +### Aggregation MeasurementProcessor -An `Aggregator` is a type of `MeasurementProcessor` and computes "aggregate" -data from [Measurements](./api.md#measurement) and its `In-Memory State` into -zero or more [Pre-Aggregated Metrics](./datamodel.md#timeseries-model). +An `Aggregation` `MeasurementProcessor` is responsible for computing instrument +`Measurements` into [Pre-Aggregated Metrics](./datamodel.md##opentelemetry-protocol-data-model). -```text +The `Aggregation` `MeasurementProcessor` MUST have access to `In-Memory State`. - +---------------------+ - | Aggregator | - | | - [Measurements]------> "Aggregate" | - | | | - | +-------V---------+ | - | | | | - | | In-Memory State | | - | | | | - | +-------+---------+ | - | | | - | V | - | "Collect" +------[Pre-Aggregated Metrics]--> - | | - +---------------------+ -``` +The `Aggregation` `MeasurementProcessor` MUST create and configure [`Aggregators`](#Aggregator) +based on [View](./sdk.md) configuration. -An `Aggregator` MUST provide an interface to "aggregate" [Measurement](./api.md#measurement) -data into its `In-Memory State`. - -An `Aggregator` MUST provide an interface to "collect" [Pre-Aggregated Metric](./datamodel.md#timeseries-model) -data from its `In-Memory State`. The collect call should be treated as a -stateful action and may reset in-memory state data. e.g. Resetting the time window -for delta temporality instruments. +e.g. Create a Sum Aggregator with monotonic values and delta temporality. -An `Aggregator` MUST have read/write access to memory storage (`In-Memory -State`) where it can store/retrieve/manage its own internal state. +The `Aggregation` `MeasurementProcessor` MUST provide `Measurements` to the +properly configured `Aggregators` based on [View](./sdk.md) configuration. -Note: SDK SHOULD provide configuration and control for memory availability to -optimize usage. Aggregators MUST log errors when memory limits are reached -and/or data lost occurs due to memory mitigation strategy. e.g dropping high -cardinality attributes. +e.g. A View re-configures a temperature Gauge Instrument to use Histogram +aggregator (configured for Cumulative temporality). -SDK MUST instantiate and configure aggregator/s based on [View](./sdk.md) -configuration. e.g. Create a Sum aggregator with monotonic values and delta -temporality (per mapping/routing). +e.g. A View re-configures a temperature Gauge Instrument to count only by +Attribute "Location" (e.g. Location=Portland or Location=Seattle). The +Aggregation MeasurementProcessor provides measurements only to the +Aggregator instance that handles the specific Attribute Key/Value combination. +(i.e. "Location=Portland" => Aggregator #1, "Location=Seattle" => Aggregator #2) -SDK MUST map/route measurements, based on [View](./sdk.md) configuration, to the -configured aggregator/s. Each map/route has zero or more instances of -aggregators. +```text + +---------------------------+ + | Aggregation | + | MeasurementProcessor | + | | +-----------------+ + | ... | | | + [Measurements]-----> ... <--------------------->| In-Memory State | + | ... | | | + | | | +-----------------+ + | | +--------------+ | + | | | Aggregator | | + | | | | | + | +---->"Update" | | + | | | ... | | + | | | "Collect"--------[Pre-Aggregated Metrics]--> + | | +--------------+ | + | | | + | | +--------------+ | + | | | Aggregator | | + | | | | | + | +---->"Update" | | + | | ... | | + | | "Collect"--------[Pre-Aggregated Metrics]--> + | +--------------+ | + | | + +---------------------------+ +``` -e.g. [View](./sdk.md) configuration specify which Attribute Keys to include, -thus creating a map/route per configured Key/Value combination. The measurement -is routed to each route and its configured aggregator/s. +#### Default Instrument to Aggregator Mapping -e.g. Support for multiple exporters creates a map/route per Exporter. The -measurement is routed to each route and its configured aggregator/s. +| 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) | [Gauge Aggregator](#GaugeAggregator) | n/a | Cumulative | | +| [Histogram](./api.md#histogram) | [Histogram Aggregator](#HistogramAggregator) | n/a | Delta | TBD Boundaries| -**Note:** An `Aggregator` instance is scoped to "aggregate" values that result -in one metric timeseries (see [Metrics Data Model](./datamodel.md)). The SDK -(via the [View](./sdk.md) configuration) allows Measurements to map/route into -zero or more resulting metric timeseries (aka Aggregators). One map/route scheme -involve expanding measurement `Attributes` to combinations of keys and values. -The SDK will facilitate this map/route scheme. Thus, SDK will create and -configure aggregators and route measurments to these aggregator instances. +### Aggregator -SDK MUST provide aggregators to support the default configured aggregator -per instrument kind. e.g. Counter instruments default to a "Sum" aggregator -configured for monotonic values. +An `Aggregator` computes incoming [Measurements](./api.md#measurement) into a +[Pre-Aggregated Metric](./datamodel.md#opentelemetry-protocol-data-model). -### Last Value Aggregator +An `Aggregator` MUST provide an interface to "update" itself given [Measurement](./api.md#measurement) +data. -The Last Value Aggregator collect data for the [Gauge Metric Point](./datamodel.md#gauge) -and is default aggregator for the following instruments: +An `Aggregator` MUST provide an interface 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. -* [Asynchronous Gauge](./api.md#asynchronous-gauge) instrument. +The SDK MUST provide the following Aggregators to support the [Metric Points](./datamodel.md#metric-points) +in the [Metrics Data Model](./datamodel.md). -Last Value Aggregator maintains the following in memory: +- [Sum Aggregator](#SumAggregator) +- [Gauge Aggregator](#GaugeAggregator) +- [Histogram Aggregator](#HistogramAggregator) -* Last Timestamp1 -* Last Value1 +### SumAggregator -\[1\]: Data from latest Measurement given, avoiding any time comparison. +The Sum Aggregator collect data for the [Sum Metric Point](./datamodel.md#sums) +and MUST be configurable to support Monotonicity and/or Temporality. -### Sum Aggregator +Sum Aggregator maintains the following state: -The Sum Aggregator collect data for the [Sum Metric Point](./datamodel.md#sums) -and is default aggregator for the following instruments: +* Start Time1 +* Sum (sum of Measurements) -* [Counter](./api.md#counter) instrument. -* [Asynchronous Counter](./api.md#asynchronous-counter) instrument. -* [UpDownCounter](./api.md#updowncounter) instrument. -* [Asynchrounous UpDownCounter](./api.md#asynchronous-updowncounter) instrument. +\[1\]: Start Time is exclusive (aka not inclusive) of the provided time. -The Sum Aggregator MUST be configurable to support different Monoticity and/or -Temporality. +### GaugeAggregator -Sum Aggregator maintains the following in memory: +The Gauge Aggregator collect data for the [Gauge Metric Point](./datamodel.md#gauge). -* Time window (e.g. start time, end time) -* Sum (sum of Measurements per Monoticity and Temporality configuration.) +Gauge Aggregator maintains the following state: -### Histogram Aggregator +* Last Timestamp2 +* Last Value2 -The Histogram Aggregator collect data for the [Histogram Metric Point](./datamodel.md#histogram) -and is default aggregator for the following instruments: +\[2\]: Data from latest Measurement given, avoiding any time comparison. -* [Histogram](./api.md#histogram) instrument. +### HistogramAggregator -The Histogram Aggregator MUST be configurable to support different Temporality -and bucket Boundary Values. +The Histogram Aggregator collect data for the [Histogram Metric Point](./datamodel.md#histogram) +and MUST be configurable to support Temporality and Bucket Boundary values. -Histogram Aggregator maintains the following in memory: +Histogram Aggregator maintains the following state: -* Start Time2 +* Start Time3 * Count (count of points in population) * Sum (sum of point values in population) -* Boundary Values +* Bucket Boundary values * Bucket Counts (count of values falling within configured Boundary Values) -\[2\]: Start Time is exclusive (aka not inclusive) of the provided time. - -### An example of SDK implementation - -SDK expand each Measurement's Attribute by the combination of key/value pairs. -For each distinct combination, SDK will route to an instance of a configured -aggregator. - -```text -+------------------+ +-------------------------------------------------------------+ -| MeterProvider | | SDK | -| Meter A | | +----------------------+ | -| Instrument X |-----[Measurements]---->| MeasurementProcessor | | -| Instrument Y | | +-----------+----------+ | -| ... | | | | -| ... | | [Measurements] | -+------------------+ | | | - | SDK expand Measurements per View configuration | - | (e.g. by Attribute key/value pairs) | - | | | - | |"Aggregate" | - | Measurement #1: V | - | +---------------------+ | - | B=Y ----------->| Aggregator #1 (B=Y) |---->+ | - | | In-Memory State: | | | - | | count=1 | | | - | +---------------------+ | | - | A=X -------+ | | - | | +---------------------+ | | - | Measurment #2: +--->| Aggregator #2 (A=X) |---->| | - | | | In-Memory State: | | | - | | | count=2 | | | - | | +---------------------+ | | - | A=X -------+ | | - | +---------------------+ | | - | B=Z ----------->| Aggregator #3 (B=Z) |---->| | - | | In-Memory State: | | | - | | count=1 | | | - | +---------------------+ | | - | |"Collect" | - | | | - | [Metrics] | - | | | - | +---------V-------+ | - | | MetricProcessor | | - | +---------+-------+ | - | | | - | [Metrics] | - | | | - | +---------V-------+ | - | | MetricExporter |=====> OTLP Collector - | +-----------------+ | - +-------------------------------------------------------------+ -``` +\[3\]: Start Time is exclusive (aka not inclusive) of the provided time. ## MetricProcessor From c3e3912c403f3a49d6ab2a4c719a12ee870b37e3 Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Mon, 19 Jul 2021 16:42:58 -0700 Subject: [PATCH 05/10] Updates per PR feedback. --- specification/metrics/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 118b1f0005f..2fbf7dc34e1 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -83,8 +83,8 @@ active span](../trace/api.md#context-interaction)). ### Aggregation MeasurementProcessor -An `Aggregation` `MeasurementProcessor` is responsible for computing instrument -`Measurements` into [Pre-Aggregated Metrics](./datamodel.md##opentelemetry-protocol-data-model). +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`. From 37906d0f25cbff08c11254a44c0ff16aa5d38cba Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Mon, 26 Jul 2021 12:04:54 -0700 Subject: [PATCH 06/10] Updates based on PR feedback --- specification/metrics/sdk.md | 114 +++++++++++++++++++---------------- 1 file changed, 61 insertions(+), 53 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 2fbf7dc34e1..3d56a8bb42c 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -88,23 +88,26 @@ 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](./sdk.md) configuration. +The `Aggregation` `MeasurementProcessor` MUST create and configure +[`Aggregators`](#Aggregator) based on [View](./sdk.md) configuration. e.g. Create a Sum Aggregator with monotonic values and delta temporality. The `Aggregation` `MeasurementProcessor` MUST provide `Measurements` to the properly configured `Aggregators` based on [View](./sdk.md) configuration. -e.g. A View re-configures a temperature Gauge Instrument to use Histogram -aggregator (configured for Cumulative temporality). +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 only by -Attribute "Location" (e.g. Location=Portland or Location=Seattle). The -Aggregation MeasurementProcessor provides measurements only to the -Aggregator instance that handles the specific Attribute Key/Value combination. +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 be ignored and not +generate any metrics. + ```text +---------------------------+ | Aggregation | @@ -133,73 +136,78 @@ Aggregator instance that handles the specific Attribute Key/Value combination. +---------------------------+ ``` -#### Default Instrument to Aggregator Mapping - -| 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) | [Gauge Aggregator](#GaugeAggregator) | n/a | Cumulative | | -| [Histogram](./api.md#histogram) | [Histogram Aggregator](#HistogramAggregator) | n/a | Delta | TBD Boundaries| - ### Aggregator -An `Aggregator` computes incoming [Measurements](./api.md#measurement) into a -[Pre-Aggregated Metric](./datamodel.md#opentelemetry-protocol-data-model). +An `Aggregator` computes incoming [Measurements](./api.md#measurement) into +[Pre-Aggregated Metrics](./datamodel.md#opentelemetry-protocol-data-model). -An `Aggregator` MUST provide an interface to "update" itself given [Measurement](./api.md#measurement) -data. +An `Aggregator` MUST provide a mean to "update" itself given +[Measurement](./api.md#measurement) data. -An `Aggregator` MUST provide an interface to "collect" [Pre-Aggregated Metric](./datamodel.md#timeseries-model) -data. The collect call should be treated as a stateful action and may reset its +An `Aggregator` MUST provide a mean 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. -The SDK MUST provide the following Aggregators to support the [Metric Points](./datamodel.md#metric-points) -in the [Metrics Data Model](./datamodel.md). +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. -- [Sum Aggregator](#SumAggregator) -- [Gauge Aggregator](#GaugeAggregator) -- [Histogram Aggregator](#HistogramAggregator) +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. -### SumAggregator +The SDK MUST provide the following Aggregators to support the +[Metric Points](./datamodel.md#metric-points) in the +[Metrics Data Model](./datamodel.md). -The Sum Aggregator collect data for the [Sum Metric Point](./datamodel.md#sums) -and MUST be configurable to support Monotonicity and/or Temporality. +- [Sum Aggregator](#SumAggregator) +- [Last Value Aggregator](#LastValueAggregator) (For Gauge Metric Point) +- [Explicit Bucket Histogram Aggregator](#ExplicitBucketHistogramAggregator) -Sum Aggregator maintains the following state: +#### SumAggregator -* Start Time1 -* Sum (sum of Measurements) +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 monoticity and temporality. -\[1\]: Start Time is exclusive (aka not inclusive) of the provided time. +A [Default Aggregator](#DefaultAggregators) MUST be provided. -### GaugeAggregator +#### LastValueAggregator -The Gauge Aggregator collect data for the [Gauge Metric Point](./datamodel.md#gauge). +The Last Value Aggregator collect data for the +[Gauge Metric Point](./datamodel.md#gauge) +and reports the last seen `Measurement`. -Gauge Aggregator maintains the following state: +A [Default Aggregator](#DefaultAggregators) MUST be provided. -* Last Timestamp2 -* Last Value2 +#### ExplicitBucketHistogramAggregator -\[2\]: Data from latest Measurement given, avoiding any time comparison. +The Explict Bucket Histogram Aggregator collect data for the +[Histogram Metric Point](./datamodel.md#histogram) +and reports a histogram with explict bucket boundaries of seen `Measurements`. +This Aggregator may be configured for custom bucket boundaries, monoticity, and +temporality. -### HistogramAggregator +A [Default Aggregator](#DefaultAggregators) MUST be provided. -The Histogram Aggregator collect data for the [Histogram Metric Point](./datamodel.md#histogram) -and MUST be configurable to support Temporality and Bucket Boundary values. +This Aggregator MUST also report on the arithmetic sum of seen `Measurements`. +The [Histogram Metric Point](./datamodel.md#histogram) requires Sum. -Histogram Aggregator maintains the following state: +### DefaultAggregators -* Start Time3 -* Count (count of points in population) -* Sum (sum of point values in population) -* Bucket Boundary values -* Bucket Counts (count of values falling within configured Boundary Values) +An `Aggregation` `MeasurementProcessor` MUST provide the following default +`Aggregators`. -\[3\]: Start Time is exclusive (aka not inclusive) of the provided time. +| 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 | ## MetricProcessor From 1219f3b2a724af0f68cb3ed5bf2b937fe0147c96 Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Mon, 26 Jul 2021 16:21:31 -0700 Subject: [PATCH 07/10] Add examples of in-memory state. --- specification/metrics/sdk.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 3d56a8bb42c..3be3ece2aa5 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -155,7 +155,7 @@ 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. +OR support CUMULATIVE to DELTA conversion. The SDK MUST provide the following Aggregators to support the [Metric Points](./datamodel.md#metric-points) in the @@ -195,10 +195,24 @@ 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 latest measurement given, avoiding any time comparison. + ### DefaultAggregators -An `Aggregation` `MeasurementProcessor` MUST provide the following default -`Aggregators`. +An `Aggregation` `MeasurementProcessor` MUST provide the following **DEFAULT** +`Aggregators` based on the reporting Instrument. | Instrument Kind | Default Aggregator | Monotonic | Temporality | Notes | | --- | --- | --- | --- | --- | From 78a7faf5ef5f2e1cf8564a0094cfb1234dd81794 Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Mon, 26 Jul 2021 16:24:37 -0700 Subject: [PATCH 08/10] Mix misspelling --- specification/metrics/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 3be3ece2aa5..e7d879067f4 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -184,9 +184,9 @@ A [Default Aggregator](#DefaultAggregators) MUST be provided. #### ExplicitBucketHistogramAggregator -The Explict Bucket Histogram Aggregator collect data for the +The Explicit Bucket Histogram Aggregator collect data for the [Histogram Metric Point](./datamodel.md#histogram) -and reports a histogram with explict bucket boundaries of seen `Measurements`. +and reports a histogram with explicit bucket boundaries of seen `Measurements`. This Aggregator may be configured for custom bucket boundaries, monoticity, and temporality. From 8b05ed6c8e9345422dbe8eedd3deac0fc40d58ad Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Tue, 27 Jul 2021 08:04:41 -0700 Subject: [PATCH 09/10] Fix misspellings --- specification/metrics/sdk.md | 67 ++++++++++++++++++------------------ 1 file changed, 34 insertions(+), 33 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index e7d879067f4..761b9755921 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -94,7 +94,8 @@ The `Aggregation` `MeasurementProcessor` MUST create and configure e.g. Create a Sum Aggregator with monotonic values and delta temporality. The `Aggregation` `MeasurementProcessor` MUST provide `Measurements` to the -properly configured `Aggregators` based on [View](./sdk.md) configuration. +correct and properly configured `Aggregators` based on [View](./sdk.md) +configuration. e.g. A View re-configures a temperature Gauge Instrument to use a Histogram aggregator with custom bucket boundaries and cumulative temporality. @@ -105,35 +106,35 @@ 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 be ignored and not -generate any metrics. +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 | | - | | | | | - | +---->"Update" | | - | | | ... | | - | | | "Collect"--------[Pre-Aggregated Metrics]--> - | | +--------------+ | - | | | - | | +--------------+ | - | | | Aggregator | | - | | | | | - | +---->"Update" | | - | | ... | | - | | "Collect"--------[Pre-Aggregated Metrics]--> - | +--------------+ | - | | - +---------------------------+ + +----------------------------+ + | Aggregation | + | MeasurementProcessor | + | | +-----------------+ + | ... | | | + [Measurements]-----> ... <---------------------->| In-Memory State | + | ... | | | + | | | +-----------------+ + | | +---------------+ | + | | | Aggregator #1 | | + | | | | | + | +---->"Update" | | + | | | ... | | + | | | "Collect"-----------[Pre-Aggregated Metrics]--> + | | +---------------+ | + | | | + | | +---------------+ | + | | | Aggregator #2 | | + | | | | | + | +---->"Update" | | + | | ... | | + | | "Collect"-----------[Pre-Aggregated Metrics]--> + | +---------------+ | + | | + +----------------------------+ ``` ### Aggregator @@ -141,10 +142,10 @@ generate any metrics. An `Aggregator` computes incoming [Measurements](./api.md#measurement) into [Pre-Aggregated Metrics](./datamodel.md#opentelemetry-protocol-data-model). -An `Aggregator` MUST provide a mean to "update" itself given +An `Aggregator` MUST provide a means to "update" with given [Measurement](./api.md#measurement) data. -An `Aggregator` MUST provide a mean to "collect" +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. @@ -170,7 +171,7 @@ The SDK MUST provide the following Aggregators to support the 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 monoticity and temporality. +This Aggregator may be configured for monotonicity and temporality. A [Default Aggregator](#DefaultAggregators) MUST be provided. @@ -187,7 +188,7 @@ A [Default Aggregator](#DefaultAggregators) MUST be provided. 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, monoticity, and +This Aggregator may be configured for custom bucket boundaries, monotonicity, and temporality. A [Default Aggregator](#DefaultAggregators) MUST be provided. @@ -207,7 +208,7 @@ The following are examples of `In-Memory State`: \[1\]: Start Time is exclusive (e.g. not inclusive) of the provided time. -\[2\]: From latest measurement given, avoiding any time comparison. +\[2\]: From last measurement given, avoiding any time comparison. ### DefaultAggregators From d0b8730b6102e37959d848e08993fe810926e6c3 Mon Sep 17 00:00:00 2001 From: Victor Lu Date: Tue, 27 Jul 2021 10:20:58 -0700 Subject: [PATCH 10/10] Update Links and add footnote for bucket boundaries --- specification/metrics/sdk.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 2b875754ae2..a3e9dbf3d7a 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -256,12 +256,12 @@ 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](./sdk.md) configuration. +[`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](./sdk.md) +correct and properly configured `Aggregators` based on [View](#View) configuration. e.g. A View re-configures a temperature Gauge Instrument to use a Histogram @@ -389,7 +389,9 @@ An `Aggregation` `MeasurementProcessor` MUST provide the following **DEFAULT** | [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 | +| [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