diff --git a/CHANGELOG.md b/CHANGELOG.md index 50e39aee770..f60d04b1b17 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -18,6 +18,10 @@ release. - Refine SDK MeterProvider configuration section. ([#3522](https://github.com/open-telemetry/opentelemetry-specification/pull/3522)) +- Clarify metric view requirements and recommendations. + ([#3524](https://github.com/open-telemetry/opentelemetry-specification/pull/3524)) +- Change the view name to be the view's stream configuration name. + ([#3524](https://github.com/open-telemetry/opentelemetry-specification/pull/3524)) - Make SDK Meter Creation more normative. ([#3529](https://github.com/open-telemetry/opentelemetry-specification/pull/3529)) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 2e1be1fdc2c..9c772827c14 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -18,6 +18,10 @@ linkTitle: SDK * [Shutdown](#shutdown) * [ForceFlush](#forceflush) * [View](#view) + + [Instrument selection criteria](#instrument-selection-criteria) + + [Stream configuration](#stream-configuration) + + [Measurement processing](#measurement-processing) + + [View examples](#view-examples) * [Aggregation](#aggregation) + [Drop Aggregation](#drop-aggregation) + [Default Aggregation](#default-aggregation) @@ -196,67 +200,165 @@ are output by the SDK. Here are some examples when a `View` might be needed: application developer does not need any attributes (e.g. just get the total count of all incoming requests). -The SDK MUST provide the means to register Views with a `MeterProvider`. Here -are the inputs: - -* The Instrument selection criteria (required), which covers: - * The `type` of the Instrument(s) (optional). - * The `name` of the Instrument(s). [OpenTelemetry SDK](../overview.md#sdk) - authors MAY choose to support wildcard characters, with the question mark - (`?`) matching exactly one character and the asterisk character (`*`) - matching zero or more characters. If wildcards are not supported in general, - OpenTelemetry SDKs MUST specifically recognize the single `*` wildcard - as matching all instruments. - * The `unit` of the Instrument(s) (optional). - * The `name` of the Meter (optional). - * The `version` of the Meter (optional). - * The `schema_url` of the Meter (optional). - * [OpenTelemetry SDK](../overview.md#sdk) authors 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 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 no 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` - MUST be used by default. This will be used as the name of the [metrics - stream](./data-model.md#events--data-stream--timeseries). -* The configuration for the resulting [metrics - stream](./data-model.md#events--data-stream--timeseries): - * The `description`. If not provided, the Instrument `description` MUST be - used by default. - * A list of `attribute keys` (optional). If provided, the attributes that are - not in the list will be ignored. 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 `aggregation` (optional) to be used. If not provided, the SDK MUST - apply a [default aggregation](#default-aggregation) configurable on the - basis of instrument kind according to the [MetricReader](#metricreader) - instance. - * **Status**: [Feature-freeze](../document-status.md) - the - `exemplar_reservoir` (optional) to use for storing exemplars. This should be - a factory or callback similar to aggregation which allows different - reservoirs to be chosen by the aggregation. - * **Status**: [Experimental](../document-status.md) - the - `aggregation_cardinality_limit` (optional) associated with the view. This - should be a positive integer to be taken as a hard limit on the - number of data points that will be emitted during a single - collection by a single instrument. See [cardinality limits](#cardinality-limits), - below. - -In order to avoid conflicts, views which specify a name SHOULD have an -instrument selector that selects at most one instrument. For the registration -mechanism described above, where selection is provided via configuration, the -SDK SHOULD NOT allow Views with a specified name to be declared with instrument -selectors that may select more than one instrument (e.g. wild card instrument -name) in the same Meter. For this and other cases where registering a view will -cause a conflict, SDKs MAY fail fast in accordance with -initialization [error handling principles](../error-handling.md#basic-error-handling-principles). +The SDK MUST provide functionality for a user to create Views for a +`MeterProvider`. This functionality MUST accept as inputs the [Instrument +selection criteria](#instrument-selection-criteria) and the resulting [stream +configuration](#stream-configuration). + +If no Instrument selection criteria are provided by the user, the SDK SHOULD +treat it as an error. It is RECOMMENDED that the SDK fails fast. Refer to [Error +handling in OpenTelemetry](../error-handling.md) for the general guidance. + +The SDK MUST provide the means to register Views with a `MeterProvider`. + +#### Instrument selection criteria + +Instrument selection criteria are the predicates that determine if a View will +be applied to an Instrument or not. + +Criteria SHOULD be treated as additive. This means an Instrument has to match +_all_ the provided criteria for the View to be applied. 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)_. + +The SDK MUST accept the following criteria: + +* `name`: The name of the Instrument(s) to match. This `name` is evaluated to + match an Instrument in the following manner. + + 1. If the value of `name` is `*`, the criterion matches all Instruments. + 2. If the value of `name` is exactly the same as an Instrument, then the + criterion matches that instrument. + + Additionally, the SDK MAY support wildcard pattern matching for the `name` + criterion using the following characters. + + * A question mark (`?`): matches any single character + * An asterisk (`*`): matches any number of any characters including none + + If wildcard pattern matching is supported, the `name` criterion will match if + the wildcard pattern is evaluated to match the Instrument name. + + If the SDK does not support wildcards in general, it MUST still recognize the + special single asterisk (`*`) character as matching all Instruments. + + Users can provide a `name`, but it is up to their descretion. Therefore, the + instrument selection criteria parameter needs to be structured to accept a + `name`, but MUST NOT obligate a user to provide one. +* `type`: The type of Instruments to match. If the value of `type` is the same + as an Instrument's type, then the criterion matches that Instrument. + + Users can provide a `type`, but it is up to their descretion. Therefore, the + instrument selection criteria parameter needs to be structured to accept a + `type`, but MUST NOT obligate a user to provide one. +* `unit`: If the value of `unit` is the same as an Instrument's unit, then the + criterion matches that Instrument. + + Users can provide a `unit`, but it is up to their descretion. Therefore, the + instrument selection criteria parameter needs to be structured to accept a + `unit`, but MUST NOT obligate a user to provide one. +* `meter_name`: If the value of `meter_name` is the same as the Meter that + created an Instrument, then the criterion matches that Instrument. + + Users can provide a `meter_name`, but it is up to their descretion. + Therefore, the instrument selection criteria parameter needs to be structured + to accept a `meter_name`, but MUST NOT obligate a user to provide one. +* `meter_version`: If the value of `meter_version` is the same version as the + Meter that created an Instrument, then the criterion matches that Instrument. + + Users can provide a `meter_version`, but it is up to their descretion. + Therefore, the instrument selection criteria parameter needs to be structured + to accept a `meter_version`, but MUST NOT obligate a user to provide one. +* `meter_schema_url`: If the value of `meter_schema_url` is the same schema URL + as the Meter that created an Instrument, then the criterion matches that + Instrument. + + Users can provide a `meter_schema_url`, but it is up to their descretion. + Therefore, the instrument selection criteria parameter needs to be structured + to accept a `meter_schema_url`, but MUST NOT obligate a user to provide one. + +The SDK MAY accept additional criteria. For example, a strongly typed language +may support point type criterion (e.g. allow the users to select Instruments +based on whether the underlying number is integral or rational). Users can +provide these additional criteria the SDK accepts, but it is up to their +descretion. Therefore, the instrument selection criteria can be structured to +accept the criteria, but MUST NOT obligate a user to provide them. + +#### Stream configuration + +Stream configuration are the parameters that define the [metric +stream](./data-model.md#events--data-stream--timeseries) a `MeterProvider` will +use to define telemetry pipelines. + +The SDK MUST accept the following stream configuration parameters: + +* `name`: The metric stream name that SHOULD be used. + + In order to avoid conflicts, if a `name` is provided the View SHOULD have an + instrument selector that selects at most one instrument. If the Instrument + selection criteria for a View with a stream configuration `name` parameter + can select more than one instrument (i.e. wildcards) the SDK MAY fail fast in + accordance with initialization [error handling + principles](../error-handling.md#basic-error-handling-principles). + + Users can provide a `name`, but it is up to their descretion. Therefore, the + stream configuration parameter needs to be structured to accept a `name`, but + MUST NOT obligate a user to provide one. If the user does not provide a + `name` value, name from the Instrument the View matches MUST be used by + default. +* `description`: The metric stream description that SHOULD be used. + + Users can provide a `description`, but it is up to their descretion. + Therefore, the stream configuration parameter needs to be structured to + accept a `description`, but MUST NOT obligate a user to provide one. If the + user does not provide a `description` value, the description from the + Instrument a View matches MUST be used by default. +* `attribute_keys`: A list of attribute keys that MUST be kept, if provided by + the user during the measurement, for the metric stream. All attributes with + keys other than those in the list MUST be ignored. + + Users can provide `attribute_keys`, but it is up to their descretion. + Therefore, the stream configuration parameter needs to be structured to + accept `attribute_keys`, but MUST NOT obligate a user to provide them. If the + user does not provide any values, all of the attributes MUST be kept (TODO: + once the Hint API is available, the default behavior should respect the Hint + if it is available). +* `aggregation`: The name of an [aggregation](#aggregation) function to use in + aggregating the metric stream data. + + Users can provide an `aggregation`, but it is up to their descretion. + Therefore, the stream configuration parameter needs to be structured to + accept an `aggregation`, but MUST NOT obligate a user to provide one. If the + user does not provide an `aggregation` value, the `MeterProvider` MUST apply + a [default aggregation](#default-aggregation) configurable on the basis of + instrument type according to the [MetricReader](#metricreader) instance. +* **Status**: [Feature-freeze](../document-status.md) - `exemplar_reservoir`: A + functional type that generates an exemplar reservoir a `MeterProvider` will + use when storing exemplars. This functional type needs to be a factory or + callback similar to aggregation selection functionality which allows + different reservoirs to be chosen by the aggregation. + + Users can provide an `exemplar_reservoir`, but it is up to their descretion. + Therefore, the stream configuration parameter needs to be structured to + accept an `exemplar_reservoir`, but MUST NOT obligate a user to provide one. + If the user does not provide an `exemplar_reservoir` value, the + `MeterProvider` MUST apply a [default exemplar + reservoir](#exemplar-defaults). +* **Status**: [Experimental](../document-status.md) - + `aggregation_cardinality_limit`: A positive integer value defining the + maximum number of data points allowed to be emitted in a collection cycle by + a single instrument. See [cardinality limits](#cardinality-limits), below. + + Users can provide an `aggregation_cardinality_limit`, but it is up to their + descretion. Therefore, the stream configuration parameter needs to be + structured to accept an `aggregation_cardinality_limit`, but MUST NOT + obligate a user to provide one. If the user does not provide an + `aggregation_cardinality_limit` value, the `MeterProvider` MUST apply the + [default aggregation cardinality limit](#metricreader) the `MetricReader` is + configured with. + +#### Measurement processing The SDK SHOULD use the following logic to determine how to process Measurements made with an Instrument: @@ -269,20 +371,24 @@ made with an Instrument: * 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 applying the View results - in [conflicting metric identities](./data-model.md#opentelemetry-protocol-data-model-producer-recommendations) + * Try to apply the View's stream configuration. If applying the View + results in [conflicting metric + identities](./data-model.md#opentelemetry-protocol-data-model-producer-recommendations) the implementation SHOULD apply the View and emit a warning. If it is not possible to apply the View without producing semantic errors (e.g. the - View sets an asynchronous instrument to use - the [Explicit bucket histogram aggregation](#explicit-bucket-histogram-aggregation)) - the implementation SHOULD emit a warning and proceed as if the View did - not exist. + View sets an asynchronous instrument to use the [Explicit bucket + histogram aggregation](#explicit-bucket-histogram-aggregation)) the + implementation SHOULD emit a warning and proceed as if the View did not + exist. * If the Instrument could not match with any of the registered `View`(s), the SDK SHOULD enable the instrument using the default aggregation and temporality. Users can configure match-all Views using [Drop aggregation](#drop-aggregation) to disable instruments by default. -Here are some examples: +#### View examples + +The following are examples of an SDK's functionality to create Views for a +`MeterProvider`. ```python # Python