From 3f3186a4578f6590d378b0b1dc462fa8508be53d Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Tue, 3 Dec 2024 11:11:46 +0100 Subject: [PATCH 01/20] Add MeasurementProcessor specification to Metrics SDK TODO Closes #4298. --- specification/metrics/sdk.md | 78 +++++++++++++++++++++++++++++++++++- 1 file changed, 76 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 325c252fd7e..aed8721e25b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -51,6 +51,11 @@ linkTitle: SDK * [Instrument advisory parameters](#instrument-advisory-parameters) * [Instrument enabled](#instrument-enabled) - [Attribute limits](#attribute-limits) +- [MeasurementProcessor](#measurementprocessor) + * [MeasurementProcessor operations](#measurementprocessor-operations) + + [OnMeasure](#onmeasure) + + [Shutdown](#shutdown-1) + + [ForceFlush](#forceflush-1) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) + [AlwaysOn](#alwayson) @@ -64,9 +69,9 @@ linkTitle: SDK - [MetricReader](#metricreader) * [MetricReader operations](#metricreader-operations) + [Collect](#collect) - + [Shutdown](#shutdown-1) + + [Shutdown](#shutdown-2) * [Periodic exporting MetricReader](#periodic-exporting-metricreader) - + [ForceFlush](#forceflush-1) + + [ForceFlush](#forceflush-2) - [MetricExporter](#metricexporter) * [Push Metric Exporter](#push-metric-exporter) + [Interface Definition](#interface-definition) @@ -986,6 +991,75 @@ Attributes which belong to Metrics are exempt from the time. Attribute truncation or deletion could affect identity of metric time series and the topic requires further analysis. +## MeasurementProcessor + +`MeasurementProcessor` is an interface which allows hooks when a `Measurement` is recorded by an `Instrument`. + +`MeasurementProcessors` can be registered directly on SDK `MeterProvider` and they are invoked in the same order as they were registered. + +SDK MUST allow users to implement and configure custom processors. + +The following diagram shows `MeasurementProcessor`'s relationship to other components in the SDK: + +```plaintext ++------------------+ +| MeterProvider | +----------------------+ +-----------------+ +| Meter A | Measurements... | | Metrics... | | +| Instrument X |-----------------> MeasurementProcessor +------------> In-memory state | +| Instrument Y + | | | | +| Meter B | +----------------------+ +-----------------+ +| Instrument Z | +| ... | +----------------------+ +-----------------+ +| ... | Measurements... | | Metrics... | | +| ... |-----------------> MeasurementProcessor +------------> In-memory state | +| ... | | | | | +| ... | +----------------------+ +-----------------+ ++------------------+ +``` + +### MeasurementProcessor operations + +#### OnMeasure + +`OnMeasure` is called when a `Measurement` is recorded. This method is called synchronously on the thread that emitted the `Measurement`, therefore it SHOULD NOT block or throw exceptions. + +**Parameters:** + +* `measurement` - a [Measurement](./api.md#measurement) that was recorded +* `context` - the resolved `Context` (the explicitly passed `Context` or the current `Contex`) + +**Returns:** Void + +For a `MeasurementProcessor` registered directly on SDK `MeterProvider`, the `measurement` mutations MUST be visible in next registered processors. + +A `MeasuremenetProcessor` may freely modify `measurement` for the duration of the `OnMeasure` call. + +#### Shutdown + +Shuts down the processor. Called when the SDK is shut down. This is an opportunity for the processor to do any cleanup required. + +`Shutdown` SHOULD be called only once for each`MeasurementProcessor` instance. After the call to `Shutdow`, subsequent calls to `OnMeasure` are not allowed. SDKs SHOULD ignore these calls gracefully, if possible. + +`Shutdown` SHOULD provide a way to let the caller know whether it succeeded, failed or timed out. + +`Shutdown` MUST include the effects of `ForceFlush`. + +`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` can be implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. OpenTelemetry SDK authors can decide if they want to make the shutdown timeout configurable. + +#### ForceFlush + +This is a hint to ensure that any tasks associated with `Measurements` for which the `MeasurementProcessor` had already received events prior to the call to `ForceFlush` SHOULD be completed as soon as possible, preferably before returning from this method. + + + +In particular, if any `MeasurementProcessor` has any associated exporter, it SHOULD try to call the exporter's `Export` with all `Measurements` for which this was not already done and then invoke `ForceFlush` on it. If a timeout is specified (see below), the `MeasurementProcessor` MUST prioritize honoring the timeout over finishing all calls. It MAY skip or abort some or all `Export` or `ForceFlush` calls it has made to achieve this goal. + +`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded, failed or timed out. + +`ForceFlush` SHOULD only be called in cases where it is absolutely necessary, such as when using some FaaS providers that may suspend the process after an invocation, but before the `MeasurementProcessor` exports the emitted `Measuremenets`. + +`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. OpenTelemetry SDK authors can decide if they want to make the flush timeout configurable. + ## Exemplar **Status**: [Stable](../document-status.md) From a8f5de39859491b002fb0c44bf0124ffc0bc301b Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Tue, 3 Dec 2024 11:33:40 +0100 Subject: [PATCH 02/20] Update TODO --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index aed8721e25b..2e17d4a3b21 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1050,7 +1050,7 @@ Shuts down the processor. Called when the SDK is shut down. This is an opportuni This is a hint to ensure that any tasks associated with `Measurements` for which the `MeasurementProcessor` had already received events prior to the call to `ForceFlush` SHOULD be completed as soon as possible, preferably before returning from this method. - + In particular, if any `MeasurementProcessor` has any associated exporter, it SHOULD try to call the exporter's `Export` with all `Measurements` for which this was not already done and then invoke `ForceFlush` on it. If a timeout is specified (see below), the `MeasurementProcessor` MUST prioritize honoring the timeout over finishing all calls. It MAY skip or abort some or all `Export` or `ForceFlush` calls it has made to achieve this goal. From 1ce9e4dd24148c86bfe8eb1059989eb341ec88a7 Mon Sep 17 00:00:00 2001 From: Lukasz Gut <40406905+Blinkuu@users.noreply.github.com> Date: Tue, 3 Dec 2024 16:57:45 +0100 Subject: [PATCH 03/20] Update specification/metrics/sdk.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add status field Co-authored-by: Robert Pająk --- specification/metrics/sdk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 2e17d4a3b21..25d5b53b177 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -993,6 +993,8 @@ series and the topic requires further analysis. ## MeasurementProcessor +**Status**: [Development](../document-status.md) + `MeasurementProcessor` is an interface which allows hooks when a `Measurement` is recorded by an `Instrument`. `MeasurementProcessors` can be registered directly on SDK `MeterProvider` and they are invoked in the same order as they were registered. From 4b0a58d077271bf2b0e24296a62d5a42def4eaa7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 3 Dec 2024 17:39:11 +0100 Subject: [PATCH 04/20] Update specification/metrics/sdk.md Co-authored-by: Reiley Yang --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 25d5b53b177..5d46af32677 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1028,7 +1028,7 @@ The following diagram shows `MeasurementProcessor`'s relationship to other compo **Parameters:** * `measurement` - a [Measurement](./api.md#measurement) that was recorded -* `context` - the resolved `Context` (the explicitly passed `Context` or the current `Contex`) +* `context` - the resolved `Context` (the explicitly passed `Context` or the current `Context`) **Returns:** Void From 449d2fb8593645db8ea3871210546e05fa224ea6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 3 Dec 2024 17:50:12 +0100 Subject: [PATCH 05/20] Update specification/metrics/sdk.md Co-authored-by: Reiley Yang --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 5d46af32677..81933d4c6b9 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1040,7 +1040,7 @@ A `MeasuremenetProcessor` may freely modify `measurement` for the duration of th Shuts down the processor. Called when the SDK is shut down. This is an opportunity for the processor to do any cleanup required. -`Shutdown` SHOULD be called only once for each`MeasurementProcessor` instance. After the call to `Shutdow`, subsequent calls to `OnMeasure` are not allowed. SDKs SHOULD ignore these calls gracefully, if possible. +`Shutdown` SHOULD be called only once for each `MeasurementProcessor` instance. After the call to `Shutdown`, subsequent calls to `OnMeasure` are not allowed. SDKs SHOULD ignore these calls gracefully, if possible. `Shutdown` SHOULD provide a way to let the caller know whether it succeeded, failed or timed out. From 60adbd3265005cd8cbf4e897075182245d1097f6 Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Fri, 6 Dec 2024 12:25:52 +0100 Subject: [PATCH 06/20] Remove Shutdown and ForceFlush from MeasurementProcessor spec --- specification/metrics/sdk.md | 52 +++++++++--------------------------- 1 file changed, 12 insertions(+), 40 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 81933d4c6b9..a683327c438 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -54,8 +54,6 @@ linkTitle: SDK - [MeasurementProcessor](#measurementprocessor) * [MeasurementProcessor operations](#measurementprocessor-operations) + [OnMeasure](#onmeasure) - + [Shutdown](#shutdown-1) - + [ForceFlush](#forceflush-1) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) + [AlwaysOn](#alwayson) @@ -69,9 +67,9 @@ linkTitle: SDK - [MetricReader](#metricreader) * [MetricReader operations](#metricreader-operations) + [Collect](#collect) - + [Shutdown](#shutdown-2) + + [Shutdown](#shutdown-1) * [Periodic exporting MetricReader](#periodic-exporting-metricreader) - + [ForceFlush](#forceflush-2) + + [ForceFlush](#forceflush-1) - [MetricExporter](#metricexporter) * [Push Metric Exporter](#push-metric-exporter) + [Interface Definition](#interface-definition) @@ -1005,17 +1003,17 @@ The following diagram shows `MeasurementProcessor`'s relationship to other compo ```plaintext +------------------+ -| MeterProvider | +----------------------+ +-----------------+ -| Meter A | Measurements... | | Metrics... | | -| Instrument X |-----------------> MeasurementProcessor +------------> In-memory state | -| Instrument Y + | | | | -| Meter B | +----------------------+ +-----------------+ +| MeterProvider | +----------------------+ +-----------------+ +| Meter A | Measurements... | | Measurements... | | +| Instrument X |-----------------> MeasurementProcessor +-----------------> In-memory state | +| Instrument Y + | | | | +| Meter B | +----------------------+ +-----------------+ | Instrument Z | -| ... | +----------------------+ +-----------------+ -| ... | Measurements... | | Metrics... | | -| ... |-----------------> MeasurementProcessor +------------> In-memory state | -| ... | | | | | -| ... | +----------------------+ +-----------------+ +| ... | +----------------------+ +-----------------+ +| ... | Measurements... | | Measurements... | | +| ... |-----------------> MeasurementProcessor +-----------------> In-memory state | +| ... | | | | | +| ... | +----------------------+ +-----------------+ +------------------+ ``` @@ -1036,32 +1034,6 @@ For a `MeasurementProcessor` registered directly on SDK `MeterProvider`, the `me A `MeasuremenetProcessor` may freely modify `measurement` for the duration of the `OnMeasure` call. -#### Shutdown - -Shuts down the processor. Called when the SDK is shut down. This is an opportunity for the processor to do any cleanup required. - -`Shutdown` SHOULD be called only once for each `MeasurementProcessor` instance. After the call to `Shutdown`, subsequent calls to `OnMeasure` are not allowed. SDKs SHOULD ignore these calls gracefully, if possible. - -`Shutdown` SHOULD provide a way to let the caller know whether it succeeded, failed or timed out. - -`Shutdown` MUST include the effects of `ForceFlush`. - -`Shutdown` SHOULD complete or abort within some timeout. `Shutdown` can be implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. OpenTelemetry SDK authors can decide if they want to make the shutdown timeout configurable. - -#### ForceFlush - -This is a hint to ensure that any tasks associated with `Measurements` for which the `MeasurementProcessor` had already received events prior to the call to `ForceFlush` SHOULD be completed as soon as possible, preferably before returning from this method. - - - -In particular, if any `MeasurementProcessor` has any associated exporter, it SHOULD try to call the exporter's `Export` with all `Measurements` for which this was not already done and then invoke `ForceFlush` on it. If a timeout is specified (see below), the `MeasurementProcessor` MUST prioritize honoring the timeout over finishing all calls. It MAY skip or abort some or all `Export` or `ForceFlush` calls it has made to achieve this goal. - -`ForceFlush` SHOULD provide a way to let the caller know whether it succeeded, failed or timed out. - -`ForceFlush` SHOULD only be called in cases where it is absolutely necessary, such as when using some FaaS providers that may suspend the process after an invocation, but before the `MeasurementProcessor` exports the emitted `Measuremenets`. - -`ForceFlush` SHOULD complete or abort within some timeout. `ForceFlush` can be implemented as a blocking API or an asynchronous API which notifies the caller via a callback or an event. OpenTelemetry SDK authors can decide if they want to make the flush timeout configurable. - ## Exemplar **Status**: [Stable](../document-status.md) From 01bcc0abd7642a862964e0cf8202027b6d1edc15 Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Thu, 2 Jan 2025 12:54:03 +0100 Subject: [PATCH 07/20] feat: define built-in measurement processor --- specification/metrics/sdk.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 84d0dad46d1..616c4a56a48 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -54,6 +54,8 @@ linkTitle: SDK - [MeasurementProcessor](#measurementprocessor) * [MeasurementProcessor operations](#measurementprocessor-operations) + [OnMeasure](#onmeasure) + * [Built-in processors](#built-in-processors) + + [SimpleProcessor](#simpleprocessor) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) + [AlwaysOn](#alwayson) @@ -993,6 +995,8 @@ series and the topic requires further analysis. `MeasurementProcessor` is an interface which allows hooks when a `Measurement` is recorded by an `Instrument`. +Built-in measurement processors are responsible for [Measurement Processing](#measurement-processing). + `MeasurementProcessors` can be registered directly on SDK `MeterProvider` and they are invoked in the same order as they were registered. SDK MUST allow users to implement and configure custom processors. @@ -1032,6 +1036,16 @@ For a `MeasurementProcessor` registered directly on SDK `MeterProvider`, the `me A `MeasuremenetProcessor` may freely modify `measurement` for the duration of the `OnMeasure` call. +A `MeasurementProcessor` MUST invoke `OnMeasure` on the next registered processor. + +### Built-in processors + +The standard OpenTelemetry SDK MUST implement simple processor as described below. + +#### SimpleProcessor + +This is an implementation of `MeasurementProcessor` which calculates an in-memory state from incoming `Measurements`. + ## Exemplar **Status**: [Stable](../document-status.md) From 90d331d4c546b8420a109136d09bc5f4b739b6fd Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Tue, 7 Jan 2025 15:24:45 +0100 Subject: [PATCH 08/20] chore: update the wording --- 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 616c4a56a48..489a4bc4fcc 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1034,9 +1034,9 @@ The following diagram shows `MeasurementProcessor`'s relationship to other compo For a `MeasurementProcessor` registered directly on SDK `MeterProvider`, the `measurement` mutations MUST be visible in next registered processors. -A `MeasuremenetProcessor` may freely modify `measurement` for the duration of the `OnMeasure` call. +A `MeasuremenetProcessor` MAY freely modify `measurement` for the duration of the `OnMeasure` call. -A `MeasurementProcessor` MUST invoke `OnMeasure` on the next registered processor. +A `MeasurementProcessor` SHOULD invoke `OnMeasure` on the next registered processor. A `MeasurementProcessor` MAY decide to drop the `Measurement` by not invoking the next processor. ### Built-in processors From ee72e3ff8e321348677e137a1cbf9d7f23264b60 Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Tue, 7 Jan 2025 15:25:23 +0100 Subject: [PATCH 09/20] chore: rename simple processor to default processor --- specification/metrics/sdk.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 489a4bc4fcc..6d47fe1a91d 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -55,7 +55,7 @@ linkTitle: SDK * [MeasurementProcessor operations](#measurementprocessor-operations) + [OnMeasure](#onmeasure) * [Built-in processors](#built-in-processors) - + [SimpleProcessor](#simpleprocessor) + + [DefaultProcessor](#defaultprocessor) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) + [AlwaysOn](#alwayson) @@ -1040,9 +1040,9 @@ A `MeasurementProcessor` SHOULD invoke `OnMeasure` on the next registered proces ### Built-in processors -The standard OpenTelemetry SDK MUST implement simple processor as described below. +The standard OpenTelemetry SDK MUST implement default processor as described below. -#### SimpleProcessor +#### DefaultProcessor This is an implementation of `MeasurementProcessor` which calculates an in-memory state from incoming `Measurements`. From 225000acc59cb83bbf9d2aa678a7fff26fa5dcca Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Tue, 7 Jan 2025 15:50:57 +0100 Subject: [PATCH 10/20] feat: specify how we reference the next processor in the chain --- specification/metrics/sdk.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 6d47fe1a91d..287bb2ffd70 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -56,6 +56,7 @@ linkTitle: SDK + [OnMeasure](#onmeasure) * [Built-in processors](#built-in-processors) + [DefaultProcessor](#defaultprocessor) + + [NoopProcessor](#noopprocessor) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) + [AlwaysOn](#alwayson) @@ -999,6 +1000,8 @@ Built-in measurement processors are responsible for [Measurement Processing](#me `MeasurementProcessors` can be registered directly on SDK `MeterProvider` and they are invoked in the same order as they were registered. +Each processor registered on the `MeterProvider` is part of a pipeline. The SDK MUST inject the `OnMeasure` function from the next processor in the chain into the current processor. It is RECOMMENDED that the SDK adds a `NoopProcessor` at the end of a pipeline. + SDK MUST allow users to implement and configure custom processors. The following diagram shows `MeasurementProcessor`'s relationship to other components in the SDK: @@ -1027,8 +1030,9 @@ The following diagram shows `MeasurementProcessor`'s relationship to other compo **Parameters:** -* `measurement` - a [Measurement](./api.md#measurement) that was recorded * `context` - the resolved `Context` (the explicitly passed `Context` or the current `Context`) +* `measurement` - a [Measurement](./api.md#measurement) that was recorded +* `next` - the `OnMeasure` function from the next processor in the chain **Returns:** Void @@ -1046,6 +1050,10 @@ The standard OpenTelemetry SDK MUST implement default processor as described bel This is an implementation of `MeasurementProcessor` which calculates an in-memory state from incoming `Measurements`. +#### NoopProcessor + +This is an implementation of `MeasurementProcessor` which does nothing. It can be used to entirely disable processing of `Measurements` or to safely terminate a chain of processors. + ## Exemplar **Status**: [Stable](../document-status.md) From f57fe00625586e9438b972943a2a407fc01bcd13 Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Wed, 22 Jan 2025 11:40:19 +0100 Subject: [PATCH 11/20] Update specification of the `next` parameter and remove `NoopProcessor` --- specification/metrics/sdk.md | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 10675bfe3d6..6fbc75954af 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -56,7 +56,6 @@ linkTitle: SDK + [OnMeasure](#onmeasure) * [Built-in processors](#built-in-processors) + [DefaultProcessor](#defaultprocessor) - + [NoopProcessor](#noopprocessor) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) + [AlwaysOn](#alwayson) @@ -1000,7 +999,7 @@ Built-in measurement processors are responsible for [Measurement Processing](#me `MeasurementProcessors` can be registered directly on SDK `MeterProvider` and they are invoked in the same order as they were registered. -Each processor registered on the `MeterProvider` is part of a pipeline. The SDK MUST inject the `OnMeasure` function from the next processor in the chain into the current processor. It is RECOMMENDED that the SDK adds a `NoopProcessor` at the end of a pipeline. +Each processor registered on the `MeterProvider` is part of a pipeline. SDK MUST allow users to implement and configure custom processors. @@ -1032,7 +1031,7 @@ The following diagram shows `MeasurementProcessor`'s relationship to other compo * `context` - the resolved `Context` (the explicitly passed `Context` or the current `Context`) * `measurement` - a [Measurement](./api.md#measurement) that was recorded -* `next` - the `OnMeasure` function from the next processor in the chain +* `next` - a callback to invoke `OnMeasure` on the next processor in the chain. It MUST be callable without a reference to the next processor. **Returns:** Void @@ -1040,7 +1039,7 @@ For a `MeasurementProcessor` registered directly on SDK `MeterProvider`, the `me A `MeasuremenetProcessor` MAY freely modify `measurement` for the duration of the `OnMeasure` call. -A `MeasurementProcessor` SHOULD invoke `OnMeasure` on the next registered processor. A `MeasurementProcessor` MAY decide to drop the `Measurement` by not invoking the next processor. +A `MeasurementProcessor` SHOULD invoke `next`. A `MeasurementProcessor` MAY decide to drop the `Measurement` by not invoking the next processor. ### Built-in processors @@ -1050,10 +1049,6 @@ The standard OpenTelemetry SDK MUST implement default processor as described bel This is an implementation of `MeasurementProcessor` which calculates an in-memory state from incoming `Measurements`. -#### NoopProcessor - -This is an implementation of `MeasurementProcessor` which does nothing. It can be used to entirely disable processing of `Measurements` or to safely terminate a chain of processors. - ## Exemplar **Status**: [Stable](../document-status.md) From 66c6926a28d2dbaddda4f82c4738ce141a468e46 Mon Sep 17 00:00:00 2001 From: Lukasz Gut <40406905+Blinkuu@users.noreply.github.com> Date: Thu, 23 Jan 2025 15:54:19 +0100 Subject: [PATCH 12/20] Update specification/metrics/sdk.md Updates specification of `next`. Co-authored-by: Reiley Yang --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 6fbc75954af..7b05379902c 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1031,7 +1031,7 @@ The following diagram shows `MeasurementProcessor`'s relationship to other compo * `context` - the resolved `Context` (the explicitly passed `Context` or the current `Context`) * `measurement` - a [Measurement](./api.md#measurement) that was recorded -* `next` - a callback to invoke `OnMeasure` on the next processor in the chain. It MUST be callable without a reference to the next processor. +* `next` - this allows the MeasurementProcessor to pass the measurements to the next MeasurementProcessor in the chain. It can be a reference to the next MeasurementProcessor, a bound callback to invoke `OnMeasure` on the next processor in the chain without an explicit reference to the next processor, or something else. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide the language idiomatic approach. **Returns:** Void From e5850289ffdccdeb010e36c99d75163853454d78 Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Thu, 23 Jan 2025 15:58:15 +0100 Subject: [PATCH 13/20] Update CHANGELOG.md --- CHANGELOG.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4dfa39488f8..c2989b1cd1f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ release. ### Metrics +- Add `MeasurementProcessor` to the Metrics SDK specification [#4318](https://github.com/open-telemetry/opentelemetry-specification/pull/4318) + ### Logs ### Baggage From 83a81a5298da41d5ed907880c5bbd2de63e51ff5 Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Thu, 23 Jan 2025 16:02:14 +0100 Subject: [PATCH 14/20] Update metrics/sdk.md Add backticks around references to MeasurementProcessor. --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7b05379902c..58a483337fd 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1031,7 +1031,7 @@ The following diagram shows `MeasurementProcessor`'s relationship to other compo * `context` - the resolved `Context` (the explicitly passed `Context` or the current `Context`) * `measurement` - a [Measurement](./api.md#measurement) that was recorded -* `next` - this allows the MeasurementProcessor to pass the measurements to the next MeasurementProcessor in the chain. It can be a reference to the next MeasurementProcessor, a bound callback to invoke `OnMeasure` on the next processor in the chain without an explicit reference to the next processor, or something else. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide the language idiomatic approach. +* `next` - this allows the `MeasurementProcessor` to pass the measurements to the next `MeasurementProcessor` in the chain. It can be a reference to the next `MeasurementProcessor`, a bound callback to invoke `OnMeasure` on the next processor in the chain without an explicit reference to the next processor, or something else. [OpenTelemetry SDK](../overview.md#sdk) authors MAY decide the language idiomatic approach. **Returns:** Void From e6eec36d0207562123b1c529b33bd7c974474fec Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Thu, 13 Feb 2025 15:29:42 +0100 Subject: [PATCH 15/20] Ensure that the pipeline ends with DefaultProcessor --- specification/metrics/sdk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 46f8fc04eb7..8c1a49f6aa0 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1003,6 +1003,8 @@ Each processor registered on the `MeterProvider` is part of a pipeline. SDK MUST allow users to implement and configure custom processors. +SDK MUST ensure that the pipeline concludes with the built-in [DefaultProcessor](#defaultprocessor). + The following diagram shows `MeasurementProcessor`'s relationship to other components in the SDK: ```plaintext From e706183ee89f4a07c28d203e67f8dfc17eb6b0ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 19 Feb 2025 19:08:52 +0100 Subject: [PATCH 16/20] Apply suggestions from code review Co-authored-by: Aaron Abbott --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 8c1a49f6aa0..7bdbcc24cbb 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1039,7 +1039,7 @@ The following diagram shows `MeasurementProcessor`'s relationship to other compo For a `MeasurementProcessor` registered directly on SDK `MeterProvider`, the `measurement` mutations MUST be visible in next registered processors. -A `MeasuremenetProcessor` MAY freely modify `measurement` for the duration of the `OnMeasure` call. +A `MeasurementProcessor` MAY freely modify `measurement` for the duration of the `OnMeasure` call. A `MeasurementProcessor` SHOULD invoke `next`. A `MeasurementProcessor` MAY decide to drop the `Measurement` by not invoking the next processor. From fc8b59dd34eb3c3b2e7d4ccfd2989629118689f1 Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Fri, 21 Mar 2025 16:05:14 +0100 Subject: [PATCH 17/20] Remove redundant CHANGELOG.md entry after conflict resolution --- CHANGELOG.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 172fe9edff9..62f55f53870 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,8 +15,6 @@ release. - Add `MeasurementProcessor` to the Metrics SDK specification ([#4318](https://github.com/open-telemetry/opentelemetry-specification/pull/4318)) -- Clarify STDOUT exporter format is unspecified. - ([#4418](https://github.com/open-telemetry/opentelemetry-specification/pull/4418)) ### Logs From 756de836c6128ce340263184ea215d0b31ce359d Mon Sep 17 00:00:00 2001 From: Lukasz Gut Date: Thu, 10 Jul 2025 16:13:21 +0200 Subject: [PATCH 18/20] Update description on DefaultProcessor --- specification/metrics/sdk.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index cd3448706d3..b6e4ae72781 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1087,7 +1087,8 @@ The standard OpenTelemetry SDK MUST implement default processor as described bel #### DefaultProcessor -This is an implementation of `MeasurementProcessor` which calculates an in-memory state from incoming `Measurements`. +This is an implementation of `MeasurementProcessor` which calculates an in-memory state from incoming `Measurements`. The `DefaultProcessor` implementation SHOULD be private; +meaning it SHOULD NOT be possible for the user to create an instance of `DefaultProcessor`. ## Exemplar From 11d423b5d9850afec2270f1398f37b7d8bb12be1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 10 Jul 2025 17:28:50 +0200 Subject: [PATCH 19/20] Update sdk.md --- specification/metrics/sdk.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b6e4ae72781..6c7d20b5f47 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -1087,7 +1087,8 @@ The standard OpenTelemetry SDK MUST implement default processor as described bel #### DefaultProcessor -This is an implementation of `MeasurementProcessor` which calculates an in-memory state from incoming `Measurements`. The `DefaultProcessor` implementation SHOULD be private; +This is an implementation of `MeasurementProcessor` which calculates an in-memory state from incoming `Measurements`. +The `DefaultProcessor` implementation SHOULD be private; meaning it SHOULD NOT be possible for the user to create an instance of `DefaultProcessor`. ## Exemplar From 9cedc06208806e874a2b6b528bb7846d7ef99908 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Thu, 10 Jul 2025 17:33:42 +0200 Subject: [PATCH 20/20] Update CHANGELOG.md --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 60ff12b7525..346c4ec187d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,9 @@ release. ### Metrics +- Add `MeasurementProcessor` to the SDK. + ([#4318](https://github.com/open-telemetry/opentelemetry-specification/pull/4318)) + ### Logs - Stabilize `Event Name` parameter of `Logger.Enabled`. @@ -125,8 +128,6 @@ release. ### Metrics -- Add `MeasurementProcessor` to the Metrics SDK specification - ([#4318](https://github.com/open-telemetry/opentelemetry-specification/pull/4318)) - Clarify SDK behavior for Instrument Advisory Parameter. ([#4389](https://github.com/open-telemetry/opentelemetry-specification/pull/4389))