From 4b866a8c0bb8e46a560b71f6ca3d097f23ca0252 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 28 May 2021 13:51:13 -0700 Subject: [PATCH 01/25] Add View API --- specification/metrics/sdk.md | 72 +++++++++++++++++++++++++++++++++++- 1 file changed, 71 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 513f88ca4c8..ec477f5da21 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -33,10 +33,80 @@ Table of Contents ## MeterProvider +### Meter Creation + +New `Meter` instances are always created through a `MeterProvider` (see +[API](./api.md#meterprovider)). The `name` and `version` arguments supplied to +the `MeterProvider` must be used to create an +[`InstrumentationLibrary`](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md) +instance which is stored on the created `Meter`. + +Configuration (i.e., [MeasurementProcessors](#measurementprocessor), +[MetricProcessors](#metricprocessors), [MetricExporters](#metricexporter) and +[`Views`](#view)) MUST be managed solely by the `MeterProvider` and it MUST +provide some way to configure all of them that are implemented in the SDK, at +least when creating or initializing it. + +The `MeterProvider` MAY provide methods to update the configuration. If +configuration is updated (e.g., adding a `MetricProcessor`), the updated +configuration MUST also apply to all already returned `Meters` (i.e. it MUST NOT +matter whether a `Meter` was obtained from the `MeterProvider` before or after +the configuration change). Note: Implementation-wise, this could mean that +`Meter` instances have a reference to their `MeterProvider` and access +configuration only via this reference. + +### Shutdown + +TODO + +### ForceFlush + +TODO + +### View + +`View` gives the SDK users flexibility to customize the metrics they want. Here +are some examples when `View` is needed: + +* Customize which [Instrument](./api.md#instrument) to be processed/ignored. For + example, an [instrumented library](../glossary.md#instrumented-library) can + provide both temperature and humidity, but the application developer only + wants temperature information. +* Customize the aggregation - if the default aggregation associated with the + Instrument does not meet the expectation. For example, an HTTP client library + might expose HTTP client request duration as [Histogram](./api.md#histogram) + by default, but the application developer only wants the total count (sum + aggregation) of outgoing requests. +* Customize which metrics dimension(s) to be reported. For example, an HTTP + server library might expose HTTP verb (e.g. GET, POST), HTTP status code (e.g. + 200, 301, 404), and a [Baggage](../baggage/api.md) value indicating whether + the request is coming from a bot/crawler or not. The application developer + might only care about HTTP status code (e.g. reporting the total count of HTTP + requests for each HTTP status code). There are also extreme scenario that the + application developer does not need any dimension (e.g. just get the total + count of all incoming requests). + +The MeterProvider MUST provide a way to register Views, and here are the +inputs: + +* The Instrument selection criteria (required), which MUST cover: + * The `name` of the Meter. + * The `version` of the Meter. + * The `name` of the Instrument. + * The `kind` of the Instrument. +* The `name` of the View (optional). If not provided, the Instrument `name` + would be used by default. +* The `description` of the View (optional). If not provided, the Instrument + `description` would be used by default. +* The `attribute keys` (optional). If not provided, all the attribute keys will + be used by default (TODO: once the Hint API is available, the default behavior + should respect the Hint if it is available). +* The `extra dimensions` which come from Baggage/Context (optional). If not + provided, no extra dimension will be used. + TODO: * Allow multiple pipelines (processors, exporters). -* Configure "Views". * Configure timing (related to [issue 1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)). From b3259fcfd38bfc59d190bafd5ae450a610486db6 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Fri, 28 May 2021 16:09:17 -0700 Subject: [PATCH 02/25] fix link --- 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 ec477f5da21..8e86779ec9d 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -42,7 +42,7 @@ the `MeterProvider` must be used to create an instance which is stored on the created `Meter`. Configuration (i.e., [MeasurementProcessors](#measurementprocessor), -[MetricProcessors](#metricprocessors), [MetricExporters](#metricexporter) and +[MetricProcessors](#metricprocessor), [MetricExporters](#metricexporter) and [`Views`](#view)) MUST be managed solely by the `MeterProvider` and it MUST provide some way to configure all of them that are implemented in the SDK, at least when creating or initializing it. From be9beb5805c18498efa587c22ff5952e7ff3350f Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 23 Jun 2021 23:35:45 -0700 Subject: [PATCH 03/25] address comments --- specification/metrics/sdk.md | 27 ++++++++++++++++----------- 1 file changed, 16 insertions(+), 11 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 8e86779ec9d..7f743685964 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -36,8 +36,9 @@ Table of Contents ### Meter Creation New `Meter` instances are always created through a `MeterProvider` (see -[API](./api.md#meterprovider)). The `name` and `version` arguments supplied to -the `MeterProvider` must be used to create an +[API](./api.md#meterprovider)). The `name`, `version` (optional), and +`schema_url` (optional) arguments supplied to the `MeterProvider` MUST be used +to create an [`InstrumentationLibrary`](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md) instance which is stored on the created `Meter`. @@ -75,16 +76,20 @@ are some examples when `View` is needed: * Customize the aggregation - if the default aggregation associated with the Instrument does not meet the expectation. For example, an HTTP client library might expose HTTP client request duration as [Histogram](./api.md#histogram) - by default, but the application developer only wants the total count (sum - aggregation) of outgoing requests. -* Customize which metrics dimension(s) to be reported. For example, an HTTP - server library might expose HTTP verb (e.g. GET, POST), HTTP status code (e.g. - 200, 301, 404), and a [Baggage](../baggage/api.md) value indicating whether - the request is coming from a bot/crawler or not. The application developer - might only care about HTTP status code (e.g. reporting the total count of HTTP - requests for each HTTP status code). There are also extreme scenario that the + by default, but the application developer only wants the total count of + outgoing requests. +* Customize which attribute(s) to be reported as metrics dimension(s). For + example, an HTTP server library might expose HTTP verb (e.g. GET, POST) and + HTTP status code (e.g. 200, 301, 404). The application developer might only + care about HTTP status code (e.g. reporting the total count of HTTP requests + for each HTTP status code). There are also extreme scenario that the application developer does not need any dimension (e.g. just get the total count of all incoming requests). +* Add additional dimension(s) from the [Context](../context/context.md). For + example, a [Baggage](../baggage/api.md) value might be available indicating + whether an HTTP request is coming from a bot/crawler or not. The application + developer might want this to be converted to a dimension for HTTP server + metrics. The MeterProvider MUST provide a way to register Views, and here are the inputs: @@ -178,7 +183,7 @@ in the SDK: ## MetricExporter -`MetricExporter` defines the interface that protocol-specific exporters must +`MetricExporter` defines the interface that protocol-specific exporters MUST implement so that they can be plugged into OpenTelemetry SDK and support sending of telemetry data. From c5c73aad861f42f5a5a19328f4954fe111c41ee7 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 24 Jun 2021 00:49:20 -0700 Subject: [PATCH 04/25] provide one example --- specification/metrics/sdk.md | 51 +++++++++++++++++++++++++++++++----- 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7f743685964..0fe1cf91720 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -89,16 +89,16 @@ are some examples when `View` is needed: example, a [Baggage](../baggage/api.md) value might be available indicating whether an HTTP request is coming from a bot/crawler or not. The application developer might want this to be converted to a dimension for HTTP server - metrics. + metrics (e.g. the request/second from bots vs. real users). The MeterProvider MUST provide a way to register Views, and here are the inputs: -* The Instrument selection criteria (required), which MUST cover: - * The `name` of the Meter. - * The `version` of the Meter. - * The `name` of the Instrument. - * The `kind` of the Instrument. +* The Instrument selection criteria (required), which covers: + * The `name` of the Meter (optional). + * The `version` of the Meter (optional). + * The `schema_url` of the Meter (optional). + * The `name` of the Instrument (required). * The `name` of the View (optional). If not provided, the Instrument `name` would be used by default. * The `description` of the View (optional). If not provided, the Instrument @@ -108,6 +108,45 @@ inputs: should respect the Hint if it is available). * The `extra dimensions` which come from Baggage/Context (optional). If not provided, no extra dimension will be used. +* The `aggregation` (optional) to be used. If not provided, the default + aggregation (based on the type of the Instrument) will be applied. + +If there is no Instrument meeting the selection criteria, or there are more than +one Instruments meeting the selection criteria, the SDK SHOULD fail fast and let +the caller know. + +If there is no View registered, all the Instruments associated with the +MeterProvider SHOULD be used. + +If there is any View registered, only the registered View(s) should be used. + +Here is one example: + +```python +# Python +''' ++------------------+ +| MeterProvider | +| Meter A | +| Counter X | +| Histogram Y | +| Meter B | +| Gauge Z | ++------------------+ +''' + +meter_provider.start_pipeline( + # metrics from X, Y and Z will be exported to console every 5 seconds (default) + pipeline: pipeline + .add_exporter(ConsoleExporter()) +).start_pipeline( + # metrics from X and Y (renamed to Foo) will be exported to Prometheus upon scraping + pipeline: pipeline + .add_view(name="X") + .add_view(name="Foo", instrument_name="Y") + .add_exporter(PrometheusExporter()) +) +``` TODO: From f82475ed64ff42a83106bcc755b039af99df76ea Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 24 Jun 2021 00:52:33 -0700 Subject: [PATCH 05/25] update wording --- 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 0fe1cf91720..c32b29b5386 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -140,7 +140,7 @@ meter_provider.start_pipeline( pipeline: pipeline .add_exporter(ConsoleExporter()) ).start_pipeline( - # metrics from X and Y (renamed to Foo) will be exported to Prometheus upon scraping + # metrics from X and Y (reported as Foo) will be exported to Prometheus upon scraping pipeline: pipeline .add_view(name="X") .add_view(name="Foo", instrument_name="Y") From 7359e9a9e429f8abb3d27cc9d050abb734299ff8 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 24 Jun 2021 10:53:09 -0700 Subject: [PATCH 06/25] polish wording --- specification/metrics/sdk.md | 40 +++++++++++++++++++++--------------- 1 file changed, 23 insertions(+), 17 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index c32b29b5386..3434647700b 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -94,26 +94,31 @@ are some examples when `View` is needed: The MeterProvider MUST provide a way to register Views, and here are the inputs: +* The `name` of the View (optional). If not provided, the Instrument `name` + would be used by default. * The Instrument selection criteria (required), which covers: * The `name` of the Meter (optional). * The `version` of the Meter (optional). * The `schema_url` of the Meter (optional). * The `name` of the Instrument (required). -* The `name` of the View (optional). If not provided, the Instrument `name` - would be used by default. -* The `description` of the View (optional). If not provided, the Instrument - `description` would be used by default. -* The `attribute keys` (optional). If not provided, all the attribute keys will - be used by default (TODO: once the Hint API is available, the default behavior - should respect the Hint if it is available). -* The `extra dimensions` which come from Baggage/Context (optional). If not - provided, no extra dimension will be used. -* The `aggregation` (optional) to be used. If not provided, the default - aggregation (based on the type of the Instrument) will be applied. - -If there is no Instrument meeting the selection criteria, or there are more than -one Instruments meeting the selection criteria, the SDK SHOULD fail fast and let -the caller know. +* The configuration for the resulting [metrics + stream](./datamodel.md#events--data-stream--timeseries): + * The `description`. If not provided, the Instrument `description` would be + used by default. + * The `attribute keys` (optional). If not provided, all the attribute keys + will be used by default (TODO: once the Hint API is available, the default + behavior should respect the Hint if it is available). + * The `extra dimensions` which come from Baggage/Context (optional). If not + provided, no extra dimension will be used. + * The `aggregation` (optional) to be used. If not provided, the default + aggregation (based on the type of the Instrument) will be applied. + +If there is no Instrument meeting the selection criteria, the SDK SHOULD fail +fast and let the caller know. + +If there are more than one Instruments meeting the selection criteria, +individual language implementation can decide what is the proper behavior, as +long as the behavior is well defined and deterministic. If there is no View registered, all the Instruments associated with the MeterProvider SHOULD be used. @@ -140,17 +145,18 @@ meter_provider.start_pipeline( pipeline: pipeline .add_exporter(ConsoleExporter()) ).start_pipeline( - # metrics from X and Y (reported as Foo) will be exported to Prometheus upon scraping + # metrics from X and Y (reported as Foo and Bar) will be exported to Prometheus upon scraping pipeline: pipeline .add_view(name="X") .add_view(name="Foo", instrument_name="Y") + .add_view(name="Bar", instrument_name="Y") .add_exporter(PrometheusExporter()) ) ``` TODO: -* Allow multiple pipelines (processors, exporters). +* Support multiple pipelines (processors, exporters). * Configure timing (related to [issue 1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)). From 2df446b7ac7e9ec32535e01030e604a2386ebd30 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 24 Jun 2021 10:58:15 -0700 Subject: [PATCH 07/25] update wording --- 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 3434647700b..109f5cb41b8 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -95,7 +95,8 @@ The MeterProvider MUST provide a way to register Views, and here are the inputs: * The `name` of the View (optional). If not provided, the Instrument `name` - would be used by default. + would be used by default. This will be used as the name of the [metrics + stream](./datamodel.md#events--data-stream--timeseries). * The Instrument selection criteria (required), which covers: * The `name` of the Meter (optional). * The `version` of the Meter (optional). From 09501aa3543eec84e759a8f94cf70808b69aae67 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 24 Jun 2021 11:41:16 -0700 Subject: [PATCH 08/25] mention histogram bucket in the view aggregation --- specification/metrics/sdk.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 109f5cb41b8..b2fce435a3d 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -121,6 +121,10 @@ If there are more than one Instruments meeting the selection criteria, individual language implementation can decide what is the proper behavior, as long as the behavior is well defined and deterministic. +If the `aggregation` is not provided, and the default aggregation doesn't have +sufficient information (e.g. a Histogram without any bucket configuration), the +SDK SHOULD fail fast and let the caller know. + If there is no View registered, all the Instruments associated with the MeterProvider SHOULD be used. From 87e3bfe54188132b621526c6d0856b3559048438 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Sun, 27 Jun 2021 12:34:46 -0700 Subject: [PATCH 09/25] resolve comments based on discussion during the SIG meeting --- specification/metrics/sdk.md | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b2fce435a3d..a49bffd4896 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -91,8 +91,8 @@ are some examples when `View` is needed: developer might want this to be converted to a dimension for HTTP server metrics (e.g. the request/second from bots vs. real users). -The MeterProvider MUST provide a way to register Views, and here are the -inputs: +The SDK must provide the means to register Views with a MeterProvider. Here are +the inputs: * The `name` of the View (optional). If not provided, the Instrument `name` would be used by default. This will be used as the name of the [metrics @@ -102,6 +102,7 @@ inputs: * The `version` of the Meter (optional). * The `schema_url` of the Meter (optional). * The `name` of the Instrument (required). + * Individual language client MAY choose to support more criterias. * The configuration for the resulting [metrics stream](./datamodel.md#events--data-stream--timeseries): * The `description`. If not provided, the Instrument `description` would be @@ -114,21 +115,19 @@ inputs: * The `aggregation` (optional) to be used. If not provided, the default aggregation (based on the type of the Instrument) will be applied. -If there is no Instrument meeting the selection criteria, the SDK SHOULD fail -fast and let the caller know. - If there are more than one Instruments meeting the selection criteria, individual language implementation can decide what is the proper behavior, as long as the behavior is well defined and deterministic. If the `aggregation` is not provided, and the default aggregation doesn't have sufficient information (e.g. a Histogram without any bucket configuration), the -SDK SHOULD fail fast and let the caller know. +SDK SHOULD provide a way to let the user know (e.g. expose [self-diagnostics +logs](../error-handling.md#self-diagnostics)). If there is no View registered, all the Instruments associated with the MeterProvider SHOULD be used. -If there is any View registered, only the registered View(s) should be used. +If there is any View registered, only the registered View(s) SHOULD be used. Here is one example: From 0c32806d606c9272725644d3f68fd817feaddaf6 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Sun, 27 Jun 2021 12:37:43 -0700 Subject: [PATCH 10/25] fix typo --- 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 a49bffd4896..673695785f8 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -102,7 +102,7 @@ the inputs: * The `version` of the Meter (optional). * The `schema_url` of the Meter (optional). * The `name` of the Instrument (required). - * Individual language client MAY choose to support more criterias. + * Individual language client MAY choose to support more criteria. * The configuration for the resulting [metrics stream](./datamodel.md#events--data-stream--timeseries): * The `description`. If not provided, the Instrument `description` would be From 142a3452cc7ae1c13e67e0a028edfbf164fdcb58 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 29 Jun 2021 14:24:11 -0700 Subject: [PATCH 11/25] update the spec based on discussion during the SIG meeting --- specification/metrics/sdk.md | 31 +++++++++++++++++++------------ 1 file changed, 19 insertions(+), 12 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 673695785f8..f47915f9b31 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -111,18 +111,25 @@ the inputs: will be used by default (TODO: once the Hint API is available, the default behavior should respect the Hint if it is available). * The `extra dimensions` which come from Baggage/Context (optional). If not - provided, no extra dimension will be used. - * The `aggregation` (optional) to be used. If not provided, the default - aggregation (based on the type of the Instrument) will be applied. - -If there are more than one Instruments meeting the selection criteria, -individual language implementation can decide what is the proper behavior, as -long as the behavior is well defined and deterministic. - -If the `aggregation` is not provided, and the default aggregation doesn't have -sufficient information (e.g. a Histogram without any bucket configuration), the -SDK SHOULD provide a way to let the user know (e.g. expose [self-diagnostics -logs](../error-handling.md#self-diagnostics)). + provided, no extra dimension will be used. Please note that this only + applies to [synchronous Instruments](./api.md#synchronous-instrument), any + `extra dimensions` configured on [asynchronous + Instruments](./api.md#asynchronous-instrument) will be considered as error. + * The `aggregation` (optional) to be used. If not provided, a default + aggregation will be applied by the SDK. The default aggregation is a TODO + (e.g. first see if there is an explicitly specified aggregation from the + View, if not, see if there is a Hint, if not, fallback to the default + aggregation that is associated with the Instrument type), and for histogram, + the default buckets would be [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, +∞). + +The SDK SHOULD consider the following situation as user error and provide a way +to let the user know (e.g. expose [self-diagnostics +logs](../error-handling.md#self-diagnostics)): + +* If there are more than one Instruments meeting the selection criteria. +* If the name of the View has conflict with other Views. If there is no View registered, all the Instruments associated with the MeterProvider SHOULD be used. From 8b9a7f0fb80a9b86ce7f7737058b153d46c67550 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Sat, 10 Jul 2021 15:11:40 -0700 Subject: [PATCH 12/25] add more diagrams --- specification/metrics/sdk.md | 91 +++++++++++++++++++++++++++++------- 1 file changed, 73 insertions(+), 18 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f47915f9b31..b109ac49a2c 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -64,6 +64,57 @@ TODO TODO +### Pipeline + +`MeterProvider` MUST support multiple pipelines, each pipeline is a logical +group of: + +* An ordered list of [View](#view)s +* A [MeasurementProcessor](#measurementprocessor) +* An ordered list of [MetricProcessor](#metricprocessor)s +* A [MetricExporter](#metricexporter) + +Here goes an example of multiple pipelines: + +```text ++------------------+ +------------+ +| MeterProvider +----->| Pipeline 1 | +| Meter A | +------------+ +| Counter X | +| Histogram Y | +------------+ +| Meter B +----->| Pipeline 2 | +| Gauge Z | +------------+ +| ... | +| ... |-----> More Pipelines ... ++------------------+ +``` + +Pipeline: + +```text + +----------------------+ +-----------------+ + | | | | +View(s) --> MeasurementProcessor +--> In-memory state +--+ + | | | | | + +----------------------+ +-----------------+ | + | + +------------------------------------------------------+ + | + | +-------------------+ +-------------------+ + | | | | | + +--> MetricProcessor 1 +--> ... ... -> MetricProcessor N +--+ + | | | | | + +-------------------+ +-------------------+ | + | + +-----------------------------------------------------------+ + | + | +----------------+ + | | | + +--> MetricExporter +--> Another process + | | + +----------------+ +``` + ### View `View` gives the SDK users flexibility to customize the metrics they want. Here @@ -91,18 +142,21 @@ are some examples when `View` is needed: developer might want this to be converted to a dimension for HTTP server metrics (e.g. the request/second from bots vs. real users). -The SDK must provide the means to register Views with a MeterProvider. Here are +The SDK MUST provide the means to register Views with a MeterProvider. Here are the inputs: -* The `name` of the View (optional). If not provided, the Instrument `name` - would be used by default. This will be used as the name of the [metrics - stream](./datamodel.md#events--data-stream--timeseries). * The Instrument selection criteria (required), which covers: + * The `name` of the Instrument(s), with wildcard support (required). * The `name` of the Meter (optional). * The `version` of the Meter (optional). * The `schema_url` of the Meter (optional). - * The `name` of the Instrument (required). - * Individual language client MAY choose to support more criteria. + * Individual language client MAY choose to support more criteria. For example, + a strong typed language MAY support point type (e.g. allow the users to + select Instruments based on whether the underlying type is integer or + double). +* The `name` of the View (optional). If not provided, the Instrument `name` + would be used by default. This will be used as the name of the [metrics + stream](./datamodel.md#events--data-stream--timeseries). * The configuration for the resulting [metrics stream](./datamodel.md#events--data-stream--timeseries): * The `description`. If not provided, the Instrument `description` would be @@ -131,10 +185,8 @@ logs](../error-handling.md#self-diagnostics)): * If there are more than one Instruments meeting the selection criteria. * If the name of the View has conflict with other Views. -If there is no View registered, all the Instruments associated with the -MeterProvider SHOULD be used. - -If there is any View registered, only the registered View(s) SHOULD be used. +When initalizing an Instrument, if no View is registered, then a View with +default aggregation is configured for this instrument. Here is one example: @@ -154,14 +206,17 @@ Here is one example: meter_provider.start_pipeline( # metrics from X, Y and Z will be exported to console every 5 seconds (default) pipeline: pipeline - .add_exporter(ConsoleExporter()) + .set_exporter(ConsoleExporter()) ).start_pipeline( # metrics from X and Y (reported as Foo and Bar) will be exported to Prometheus upon scraping pipeline: pipeline .add_view(name="X") .add_view(name="Foo", instrument_name="Y") - .add_view(name="Bar", instrument_name="Y") - .add_exporter(PrometheusExporter()) + .add_view( + name="Bar", + instrument_name="Y", + aggregation=HistogramAggregation(buckets=[5.0, 10.0, 25.0, 50.0, 100.0])) + .set_exporter(PrometheusExporter()) ) ``` @@ -200,13 +255,13 @@ active span](../trace/api.md#context-interaction)). +------------------+ | MeterProvider | +----------------------+ +-----------------+ | Meter A | Measurements... | | Metrics... | | -| Instrument X |-----------------> MeasurementProcessor +------------> In-memory state | -| Instrument Y + | | | | +| Instrument X +-----------------> MeasurementProcessor +------------> In-memory state | +| Instrument Y | | | | | | Meter B | +----------------------+ +-----------------+ | Instrument Z | | ... | +----------------------+ +-----------------+ | ... | Measurements... | | Metrics... | | -| ... |-----------------> MeasurementProcessor +------------> In-memory state | +| ... +-----------------> MeasurementProcessor +------------> In-memory state | | ... | | | | | | ... | +----------------------+ +-----------------+ +------------------+ @@ -226,13 +281,13 @@ in the SDK: ```text +-----------------+ +-----------------+ +-----------------------+ | | Metrics... | | Metrics... | | -> In-memory state | -----------> MetricProcessor | -----------> MetricExporter (push) |--> Another process +| In-memory state +------------> MetricProcessor +------------> MetricExporter (push) +--> Another process | | | | | | +-----------------+ +-----------------+ +-----------------------+ +-----------------+ +-----------------+ +-----------------------+ | | Metrics... | | Metrics... | | -> In-memory state |------------> MetricProcessor |------------> MetricExporter (pull) |--> Another process (scraper) +| In-memory state +------------> MetricProcessor +------------> MetricExporter (pull) +--> Another process (scraper) | | | | | | +-----------------+ +-----------------+ +-----------------------+ ``` From d14d005e3952234b8566821173a271480746226f Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Sat, 10 Jul 2021 16:20:21 -0700 Subject: [PATCH 13/25] update the spec based on the discussion during Metrics SIG meeting --- specification/metrics/sdk.md | 131 ++++++++++++++++++++++------------- 1 file changed, 84 insertions(+), 47 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b109ac49a2c..2a2d42cfccf 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -66,39 +66,21 @@ TODO ### Pipeline -`MeterProvider` MUST support multiple pipelines, each pipeline is a logical -group of: +A pipeline is a logical group of: * An ordered list of [View](#view)s * A [MeasurementProcessor](#measurementprocessor) * An ordered list of [MetricProcessor](#metricprocessor)s * A [MetricExporter](#metricexporter) -Here goes an example of multiple pipelines: - -```text -+------------------+ +------------+ -| MeterProvider +----->| Pipeline 1 | -| Meter A | +------------+ -| Counter X | -| Histogram Y | +------------+ -| Meter B +----->| Pipeline 2 | -| Gauge Z | +------------+ -| ... | -| ... |-----> More Pipelines ... -+------------------+ -``` - -Pipeline: - ```text - +----------------------+ +-----------------+ - | | | | -View(s) --> MeasurementProcessor +--> In-memory state +--+ - | | | | | - +----------------------+ +-----------------+ | - | - +------------------------------------------------------+ + +----------------------+ +-----------------+ + | | | | +Measurements --> MeasurementProcessor +--> In-memory state +--+ + | | | | | + +----------------------+ +-----------------+ | + | + +-----------------------------------------------------------+ | | +-------------------+ +-------------------+ | | | | | @@ -115,6 +97,28 @@ View(s) --> MeasurementProcessor +--> In-memory state +--+ +----------------+ ``` +`MeterProvider` MUST support multiple pipelines: + +```text ++------------------+ +------------+ +| MeterProvider +----->| Pipeline 1 | +| Meter A | +------------+ +| Counter X | +| Histogram Y | +------------+ +| Meter B +----->| Pipeline 2 | +| Gauge Z | +------------+ +| ... | +| ... |-----> More Pipelines ... ++------------------+ +``` + +Each pipeline has an ordered list of [View](#view)s, which provides +configuration for: + +* Whether the Measurements from a certain Instrument should go through the + pipeline or not. +* How should the Measurements turn into Metrics. + ### View `View` gives the SDK users flexibility to customize the metrics they want. Here @@ -142,8 +146,8 @@ are some examples when `View` is needed: developer might want this to be converted to a dimension for HTTP server metrics (e.g. the request/second from bots vs. real users). -The SDK MUST provide the means to register Views with a MeterProvider. Here are -the inputs: +The SDK MUST provide the means to register Views with a [MeterProvider +Pipeline](#pipeline). Here are the inputs: * The Instrument selection criteria (required), which covers: * The `name` of the Instrument(s), with wildcard support (required). @@ -178,17 +182,27 @@ the inputs: 50.0], (50.0, 75.0], (75.0, 100.0], (100.0, 250.0], (250.0, 500.0], (500.0, 1000.0], (1000.0, +∞). -The SDK SHOULD consider the following situation as user error and provide a way -to let the user know (e.g. expose [self-diagnostics -logs](../error-handling.md#self-diagnostics)): - -* If there are more than one Instruments meeting the selection criteria. -* If the name of the View has conflict with other Views. - -When initalizing an Instrument, if no View is registered, then a View with -default aggregation is configured for this instrument. - -Here is one example: +The SDK SHOULD use the following logic to determine how to process an +Instrument: + +* Determine the MeterProvider which "owns" the Instrument. +* If the MeterProvider has no [Pipeline](#pipeline) registered, go to the END. +* For each Pipeline: + * If the Pipeline has no `View` registered, take the Instrument and apply the + default configuration. + * If the Pipeline has one or more `View`(s) registered, for each View: + * If the Instrument could match the instrument selection criteria: + * Try to apply the View configuration. If there is an error (e.g. the View + asks for extra dimensions from the Baggage, but the Instrument is + [asynchronous](./api.md#asynchronous-instrument) which doesn't have + Context) or a conflict (e.g. the View requires to export the metrics + using a certain name, but the name is already used by another View), + provide a way to let the user know (e.g. expose [self-diagnostics + logs](../error-handling.md#self-diagnostics)). + * Stop processing the remaining Views (proceed to the next Pipeline). +* END. + +Here are some examples: ```python # Python @@ -204,27 +218,50 @@ Here is one example: ''' meter_provider.start_pipeline( - # metrics from X, Y and Z will be exported to console every 5 seconds (default) + # all the metrics will be exported using the default configuration pipeline: pipeline .set_exporter(ConsoleExporter()) ).start_pipeline( # metrics from X and Y (reported as Foo and Bar) will be exported to Prometheus upon scraping pipeline: pipeline - .add_view(name="X") - .add_view(name="Foo", instrument_name="Y") + .add_view("X") + .add_view("Foo", instrument_name="Y") .add_view( - name="Bar", + "Bar", instrument_name="Y", aggregation=HistogramAggregation(buckets=[5.0, 10.0, 25.0, 50.0, 100.0])) .set_exporter(PrometheusExporter()) ) ``` -TODO: +```python +meter_provider.start_pipeline( + # all the metrics will be exported using the default configuration + pipeline: pipeline + .add_view("*") # a wildcard view that matches everything + .set_exporter(ConsoleExporter()) +) +``` -* Support multiple pipelines (processors, exporters). -* Configure timing (related to [issue - 1432](https://github.com/open-telemetry/opentelemetry-specification/issues/1432)). +```python +meter_provider.start_pipeline( + # Counter X will be exported as cumulative sum + pipeline: pipeline + .add_view("X", aggregation=SumAggregation(CUMULATIVE)) + .set_exporter(ConsoleExporter()) +) +``` + +```python +meter_provider.start_pipeline( + # Counter X will be exported as delta sum + # Histogram Y and Gauge Z will be exported with 2 dimensions (a and b) + pipeline: pipeline + .add_view("X", aggregation=SumAggregation(DELTA)) + .add_view("*", attribute_keys=["a", "b"]) + .set_exporter(ConsoleExporter()) +) +``` ## MeasurementProcessor From bbe5b4014ea65dfdd512f0f387e72e32bfc98a9f Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Sat, 10 Jul 2021 17:41:17 -0700 Subject: [PATCH 14/25] minor tweak diagram --- specification/metrics/sdk.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 2a2d42cfccf..2fb9cce242a 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -100,15 +100,15 @@ Measurements --> MeasurementProcessor +--> In-memory state +--+ `MeterProvider` MUST support multiple pipelines: ```text -+------------------+ +------------+ -| MeterProvider +----->| Pipeline 1 | -| Meter A | +------------+ ++------------------+ +| MeterProvider | +| Meter A +-----> Pipeline 1 | Counter X | -| Histogram Y | +------------+ -| Meter B +----->| Pipeline 2 | -| Gauge Z | +------------+ -| ... | -| ... |-----> More Pipelines ... +| Histogram Y +-----> ... +| Meter B | ... +| Gauge Z | +| ... +-----> Pipeline N +| ... | +------------------+ ``` From 49bf1b1ea6e111d9f67068aebc76b677450d65ed Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 13 Jul 2021 00:00:22 -0700 Subject: [PATCH 15/25] address review comment --- 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 2fb9cce242a..572ddac7a04 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -165,9 +165,9 @@ Pipeline](#pipeline). Here are the inputs: stream](./datamodel.md#events--data-stream--timeseries): * The `description`. If not provided, the Instrument `description` would be used by default. - * The `attribute keys` (optional). If not provided, all the attribute keys - will be used by default (TODO: once the Hint API is available, the default - behavior should respect the Hint if it is available). + * A list of `attribute keys` (optional). If not provided, all the attribute + keys will be used by default (TODO: once the Hint API is available, the + default behavior should respect the Hint if it is available). * The `extra dimensions` which come from Baggage/Context (optional). If not provided, no extra dimension will be used. Please note that this only applies to [synchronous Instruments](./api.md#synchronous-instrument), any From 7d8336d7bdc12adf8bb364c94c9a98d15c1fec1f Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 13 Jul 2021 11:02:44 -0700 Subject: [PATCH 16/25] update the default histogram buckets --- 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 572ddac7a04..05c024d696d 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -178,9 +178,9 @@ Pipeline](#pipeline). Here are the inputs: (e.g. first see if there is an explicitly specified aggregation from the View, if not, see if there is a Hint, if not, fallback to the default aggregation that is associated with the Instrument type), and for histogram, - the default buckets would be [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, +∞). + the default buckets would be (-∞, 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, +∞). The SDK SHOULD use the following logic to determine how to process an Instrument: From 083c51c8e8d5bf085f775d288a4c6ffac83f02b0 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 20 Jul 2021 08:07:16 -0700 Subject: [PATCH 17/25] remove pipeline from this PR --- specification/metrics/sdk.md | 149 ++++++++++------------------------- 1 file changed, 42 insertions(+), 107 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 05c024d696d..efa793b73a5 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -64,61 +64,6 @@ TODO TODO -### Pipeline - -A pipeline is a logical group of: - -* An ordered list of [View](#view)s -* A [MeasurementProcessor](#measurementprocessor) -* An ordered list of [MetricProcessor](#metricprocessor)s -* A [MetricExporter](#metricexporter) - -```text - +----------------------+ +-----------------+ - | | | | -Measurements --> MeasurementProcessor +--> In-memory state +--+ - | | | | | - +----------------------+ +-----------------+ | - | - +-----------------------------------------------------------+ - | - | +-------------------+ +-------------------+ - | | | | | - +--> MetricProcessor 1 +--> ... ... -> MetricProcessor N +--+ - | | | | | - +-------------------+ +-------------------+ | - | - +-----------------------------------------------------------+ - | - | +----------------+ - | | | - +--> MetricExporter +--> Another process - | | - +----------------+ -``` - -`MeterProvider` MUST support multiple pipelines: - -```text -+------------------+ -| MeterProvider | -| Meter A +-----> Pipeline 1 -| Counter X | -| Histogram Y +-----> ... -| Meter B | ... -| Gauge Z | -| ... +-----> Pipeline N -| ... | -+------------------+ -``` - -Each pipeline has an ordered list of [View](#view)s, which provides -configuration for: - -* Whether the Measurements from a certain Instrument should go through the - pipeline or not. -* How should the Measurements turn into Metrics. - ### View `View` gives the SDK users flexibility to customize the metrics they want. Here @@ -146,8 +91,8 @@ are some examples when `View` is needed: developer might want this to be converted to a dimension for HTTP server metrics (e.g. the request/second from bots vs. real users). -The SDK MUST provide the means to register Views with a [MeterProvider -Pipeline](#pipeline). Here are the inputs: +The SDK MUST provide the means to register Views with a `MeterProvider`. Here +are the inputs: * The Instrument selection criteria (required), which covers: * The `name` of the Instrument(s), with wildcard support (required). @@ -185,21 +130,18 @@ Pipeline](#pipeline). Here are the inputs: The SDK SHOULD use the following logic to determine how to process an Instrument: -* Determine the MeterProvider which "owns" the Instrument. -* If the MeterProvider has no [Pipeline](#pipeline) registered, go to the END. -* For each Pipeline: - * If the Pipeline has no `View` registered, take the Instrument and apply the - default configuration. - * If the Pipeline has one or more `View`(s) registered, for each View: - * If the Instrument could match the instrument selection criteria: - * Try to apply the View configuration. If there is an error (e.g. the View - asks for extra dimensions from the Baggage, but the Instrument is - [asynchronous](./api.md#asynchronous-instrument) which doesn't have - Context) or a conflict (e.g. the View requires to export the metrics - using a certain name, but the name is already used by another View), - provide a way to let the user know (e.g. expose [self-diagnostics - logs](../error-handling.md#self-diagnostics)). - * Stop processing the remaining Views (proceed to the next Pipeline). +* Determine the `MeterProvider` which "owns" the Instrument. +* If the `MeterProvider` has no `View` registered, take the Instrument and apply + the default configuration. +* If the `MeterProvider` has one or more `View`(s) registered, for each View: + * If the Instrument could match the instrument selection criteria: + * Try to apply the View configuration. If there is an error (e.g. the View + asks for extra dimensions from the Baggage, but the Instrument is + [asynchronous](./api.md#asynchronous-instrument) which doesn't have + Context) or a conflict (e.g. the View requires to export the metrics using + a certain name, but the name is already used by another View), provide a + way to let the user know (e.g. expose [self-diagnostics + logs](../error-handling.md#self-diagnostics)). * END. Here are some examples: @@ -217,50 +159,43 @@ Here are some examples: +------------------+ ''' -meter_provider.start_pipeline( - # all the metrics will be exported using the default configuration - pipeline: pipeline - .set_exporter(ConsoleExporter()) -).start_pipeline( - # metrics from X and Y (reported as Foo and Bar) will be exported to Prometheus upon scraping - pipeline: pipeline - .add_view("X") - .add_view("Foo", instrument_name="Y") - .add_view( - "Bar", - instrument_name="Y", - aggregation=HistogramAggregation(buckets=[5.0, 10.0, 25.0, 50.0, 100.0])) - .set_exporter(PrometheusExporter()) -) +# metrics from X and Y (reported as Foo and Bar) will be exported +meter_provider + .add_view("X") + .add_view("Foo", instrument_name="Y") + .add_view( + "Bar", + instrument_name="Y", + aggregation=HistogramAggregation(buckets=[5.0, 10.0, 25.0, 50.0, 100.0])) + .set_exporter(PrometheusExporter()) +``` + +```python +# all the metrics will be exported using the default configuration +meter_provider.set_exporter(ConsoleExporter()) ``` ```python -meter_provider.start_pipeline( - # all the metrics will be exported using the default configuration - pipeline: pipeline - .add_view("*") # a wildcard view that matches everything - .set_exporter(ConsoleExporter()) -) +# all the metrics will be exported using the default configuration +meter_provider + .add_view("*") # a wildcard view that matches everything + .set_exporter(ConsoleExporter()) ``` ```python -meter_provider.start_pipeline( - # Counter X will be exported as cumulative sum - pipeline: pipeline - .add_view("X", aggregation=SumAggregation(CUMULATIVE)) - .set_exporter(ConsoleExporter()) -) +# Counter X will be exported as cumulative sum +meter_provider + .add_view("X", aggregation=SumAggregation(CUMULATIVE)) + .set_exporter(ConsoleExporter()) ``` ```python -meter_provider.start_pipeline( - # Counter X will be exported as delta sum - # Histogram Y and Gauge Z will be exported with 2 dimensions (a and b) - pipeline: pipeline - .add_view("X", aggregation=SumAggregation(DELTA)) - .add_view("*", attribute_keys=["a", "b"]) - .set_exporter(ConsoleExporter()) -) +# Counter X will be exported as delta sum +# Histogram Y and Gauge Z will be exported with 2 dimensions (a and b) +meter_provider + .add_view("X", aggregation=SumAggregation(DELTA)) + .add_view("*", attribute_keys=["a", "b"]) + .set_exporter(ConsoleExporter()) ``` ## MeasurementProcessor From 4f00ac7a97fdaf5dc78b73c35e721407f15bf7ad Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 20 Jul 2021 08:19:33 -0700 Subject: [PATCH 18/25] address comments regarding error handling --- specification/metrics/sdk.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index efa793b73a5..cd39a68df78 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -115,9 +115,7 @@ are the inputs: default behavior should respect the Hint if it is available). * The `extra dimensions` which come from Baggage/Context (optional). If not provided, no extra dimension will be used. Please note that this only - applies to [synchronous Instruments](./api.md#synchronous-instrument), any - `extra dimensions` configured on [asynchronous - Instruments](./api.md#asynchronous-instrument) will be considered as error. + applies to [synchronous Instruments](./api.md#synchronous-instrument). * The `aggregation` (optional) to be used. If not provided, a default aggregation will be applied by the SDK. The default aggregation is a TODO (e.g. first see if there is an explicitly specified aggregation from the From 2d5a8886a4123d605c8e3f8749ab9c026bb4d7e7 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Wed, 21 Jul 2021 10:24:07 -0700 Subject: [PATCH 19/25] Update specification/metrics/sdk.md Co-authored-by: John Watson --- 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 cd39a68df78..b4f9738f313 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -44,9 +44,9 @@ instance which is stored on the created `Meter`. Configuration (i.e., [MeasurementProcessors](#measurementprocessor), [MetricProcessors](#metricprocessor), [MetricExporters](#metricexporter) and -[`Views`](#view)) MUST be managed solely by the `MeterProvider` and it MUST -provide some way to configure all of them that are implemented in the SDK, at -least when creating or initializing it. +[`Views`](#view)) MUST be managed solely by the `MeterProvider` and the SDK MUST +provide a way to configure all options that are implemented by the SDK. This MAY be done at the +time of MeterProvider creation if appropriate. The `MeterProvider` MAY provide methods to update the configuration. If configuration is updated (e.g., adding a `MetricProcessor`), the updated From f1621e7b1e9e72c1303080e5a72280f49a38174a Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Thu, 22 Jul 2021 11:20:07 -0700 Subject: [PATCH 20/25] adjust wording --- specification/metrics/sdk.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index b4f9738f313..1bf23a395bf 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -66,23 +66,23 @@ TODO ### View -`View` gives the SDK users flexibility to customize the metrics they want. Here -are some examples when `View` is needed: +A `View` provides SDK users with the flexibility to customize the metrics that +are output by the SDK. Here are some examples when a `View` might be needed: -* Customize which [Instrument](./api.md#instrument) to be processed/ignored. For - example, an [instrumented library](../glossary.md#instrumented-library) can - provide both temperature and humidity, but the application developer only - wants temperature information. +* Customize which [Instruments](./api.md#instrument) are to be + processed/ignored. For example, an [instrumented + library](../glossary.md#instrumented-library) can provide both temperature and + humidity, but the application developer might only want temperature. * Customize the aggregation - if the default aggregation associated with the - Instrument does not meet the expectation. For example, an HTTP client library - might expose HTTP client request duration as [Histogram](./api.md#histogram) - by default, but the application developer only wants the total count of - outgoing requests. -* Customize which attribute(s) to be reported as metrics dimension(s). For + Instrument does not meet the needs of the user. For example, an HTTP client + library might expose HTTP client request duration as + [Histogram](./api.md#histogram) by default, but the application developer + might only want the total count of outgoing requests. +* Customize which attribute(s) are to be reported as metrics dimension(s). For example, an HTTP server library might expose HTTP verb (e.g. GET, POST) and HTTP status code (e.g. 200, 301, 404). The application developer might only care about HTTP status code (e.g. reporting the total count of HTTP requests - for each HTTP status code). There are also extreme scenario that the + for each HTTP status code). There could also be extreme scenarios in which the application developer does not need any dimension (e.g. just get the total count of all incoming requests). * Add additional dimension(s) from the [Context](../context/context.md). For @@ -125,8 +125,8 @@ are the inputs: 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, +∞). -The SDK SHOULD use the following logic to determine how to process an -Instrument: +The SDK SHOULD use the following logic to determine how to process Measurements +made with an Instrument: * Determine the `MeterProvider` which "owns" the Instrument. * If the `MeterProvider` has no `View` registered, take the Instrument and apply From 4d0913a31a8633e44e30aabec4022fb0f547aee3 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 26 Jul 2021 09:56:11 -0700 Subject: [PATCH 21/25] add instrument type and clarify the selection criteria --- specification/metrics/sdk.md | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 1bf23a395bf..055936ee7de 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -95,7 +95,8 @@ The SDK MUST provide the means to register Views with a `MeterProvider`. Here are the inputs: * The Instrument selection criteria (required), which covers: - * The `name` of the Instrument(s), with wildcard support (required). + * The `type` of the Instrument(s) (optional). + * The `name` of the Instrument(s), with wildcard support (optional). * The `name` of the Meter (optional). * The `version` of the Meter (optional). * The `schema_url` of the Meter (optional). @@ -103,6 +104,15 @@ are the inputs: a strong typed language MAY support point type (e.g. allow the users to select Instruments based on whether the underlying type is integer or double). + * The criteria SHOULD be treated as additive, which means the Instrument has + to meet _all_ the provided criteria. For example, if the criteria are + _instrument name == "Foobar"_ and _instrument type is Histogram_, it will be + treated as _(instrument name == "Foobar") AND (instrument type is + Histogram)_. + * If _none_ the optional criteria is provided, the SDK SHOULD treat it as an + error. It is recommended that the SDK implementations fail fast. Please + refer to [Error handling in OpenTelemetry](error-handling.md) for the + general guidance. * The `name` of the View (optional). If not provided, the Instrument `name` would be used by default. This will be used as the name of the [metrics stream](./datamodel.md#events--data-stream--timeseries). From 6261507c83e2df890ca352e76c9a86b8485f96af Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 26 Jul 2021 10:13:02 -0700 Subject: [PATCH 22/25] update the view selection logic --- specification/metrics/sdk.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 055936ee7de..14af7f61277 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -150,6 +150,12 @@ made with an Instrument: a certain name, but the name is already used by another View), provide a way to let the user know (e.g. expose [self-diagnostics logs](../error-handling.md#self-diagnostics)). + * If the Instrument could not match with any of the registered `View`(s), the + SDK SHOULD provide a default behavior. The SDK SHOULD also provide a way for + the user to turn off the default behavior via MeterProvider (which means the + Instrument will be ignored when there is no match). Individual + implementations can decide what the default behavior is, and how to turn the + default behavior off. * END. Here are some examples: From 954102fd59c31d84ca9a05b2c92e48ad9407b09c Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 26 Jul 2021 10:14:58 -0700 Subject: [PATCH 23/25] update the view selection logic --- specification/metrics/sdk.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 14af7f61277..d6e7be5a596 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -141,8 +141,9 @@ made with an Instrument: * Determine the `MeterProvider` which "owns" the Instrument. * If the `MeterProvider` has no `View` registered, take the Instrument and apply the default configuration. -* If the `MeterProvider` has one or more `View`(s) registered, for each View: - * If the Instrument could match the instrument selection criteria: +* If the `MeterProvider` has one or more `View`(s) registered: + * For each View, if the Instrument could match the instrument selection + criteria: * Try to apply the View configuration. If there is an error (e.g. the View asks for extra dimensions from the Baggage, but the Instrument is [asynchronous](./api.md#asynchronous-instrument) which doesn't have From 5fc05002015e07266748ae62761f78121238b3a2 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Mon, 26 Jul 2021 10:20:08 -0700 Subject: [PATCH 24/25] fix broken link --- 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 d6e7be5a596..717be89d8f8 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -111,7 +111,7 @@ are the inputs: Histogram)_. * If _none_ the optional criteria is provided, the SDK SHOULD treat it as an error. It is recommended that the SDK implementations fail fast. Please - refer to [Error handling in OpenTelemetry](error-handling.md) for the + refer to [Error handling in OpenTelemetry](../error-handling.md) for the general guidance. * The `name` of the View (optional). If not provided, the Instrument `name` would be used by default. This will be used as the name of the [metrics From 4ab346579a9570aab2baf6fabc0686341e69ff26 Mon Sep 17 00:00:00 2001 From: Reiley Yang Date: Tue, 27 Jul 2021 09:58:26 -0700 Subject: [PATCH 25/25] update the TODO part by removing the details --- specification/metrics/sdk.md | 8 +------- 1 file changed, 1 insertion(+), 7 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 717be89d8f8..7af4f22c6d3 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -127,13 +127,7 @@ are the inputs: provided, no extra dimension will be used. Please note that this only applies to [synchronous Instruments](./api.md#synchronous-instrument). * The `aggregation` (optional) to be used. If not provided, a default - aggregation will be applied by the SDK. The default aggregation is a TODO - (e.g. first see if there is an explicitly specified aggregation from the - View, if not, see if there is a Hint, if not, fallback to the default - aggregation that is associated with the Instrument type), and for histogram, - the default buckets would be (-∞, 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, +∞). + aggregation will be applied by the SDK. The default aggregation is a TODO. The SDK SHOULD use the following logic to determine how to process Measurements made with an Instrument: