diff --git a/CHANGELOG.md b/CHANGELOG.md index 7b48d55987c..e20db83708a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -23,6 +23,8 @@ release. ([#3600](https://github.com/open-telemetry/opentelemetry-specification/pull/3600)) - Clarify that advice is non-identifying. ([#3661](https://github.com/open-telemetry/opentelemetry-specification/pull/3661)) +- Rename "advice" to "advisory parameters". + ([#3662](https://github.com/open-telemetry/opentelemetry-specification/pull/3662)) ### Logs diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index 0dfc50555e5..ac4a2b4194e 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -115,15 +115,14 @@ formats is required. Implementing more than one format is optional. | Instruments have kind. | | + | + | + | + | | | + | + | + | + | | | Instruments have an optional unit of measure. | | + | + | + | + | | | + | + | + | + | | | Instruments have an optional description. | | + | + | + | + | | | + | + | + | + | | -| Instruments have an optional advice. | | | | | | | | | | | | | | A valid instrument MUST be created and warning SHOULD be emitted when multiple instruments are registered under the same `Meter` using the same `name`. | | | + | + | + | | | | | | | | | Duplicate instrument registration name conflicts are resolved by using the first-seen for the stream name. | | | + | | | | | | | | | | | It is possible to register two instruments with same `name` under different `Meter`s. | | + | + | + | + | | | | + | + | + | | | Instrument names conform to the specified syntax. | | - | + | | + | | | | + | + | + | | | Instrument units conform to the specified syntax. | | - | + | | + | | | | + | + | + | | | Instrument descriptions conform to the specified syntax. | | - | + | | - | | | | | - | + | | -| Instrument advice supports ExplicitBucketBoundaries. | | | | | | | | | | | | | -| Instrument advice supports Attributes. | | | | | | | | | | | | | +| Instrument supports the advisory ExplicitBucketBoundaries parameter. | | | | | | | | | | | | | +| Instrument supports the advisory Attributes parameter. | | | | | | | | | | | | | | `create_counter` returns a `Counter`. | | + | + | + | + | | | + | + | + | + | | | The API for `Counter` accepts the name, unit and description of the instrument. | | + | + | + | + | | | + | + | + | + | | | `Counter` has an `add` method. | | + | + | + | + | | | + | + | + | + | | diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 33f2121fe4c..6a6e4369c5b 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -22,7 +22,7 @@ linkTitle: API + [Instrument name syntax](#instrument-name-syntax) + [Instrument unit](#instrument-unit) + [Instrument description](#instrument-description) - + [Instrument advice](#instrument-advice) + + [Instrument advisory parameters](#instrument-advisory-parameters) + [Synchronous and Asynchronous instruments](#synchronous-and-asynchronous-instruments) - [Synchronous Instrument API](#synchronous-instrument-api) - [Asynchronous Instrument API](#asynchronous-instrument-api) @@ -180,14 +180,14 @@ Also see the respective sections below for more information on instrument creati ## Instrument Instruments are used to report [Measurements](#measurement). Each Instrument -will have the following fields: +will have the following parameters: * The `name` of the Instrument * The `kind` of the Instrument - whether it is a [Counter](#counter) or one of the other kinds, whether it is synchronous or asynchronous * An optional `unit` of measure * An optional `description` -* Optional `advice` (**experimental**) +* Optional `advisory` parameters (**experimental**) Instruments are associated with the Meter during creation. Instruments are identified by the `name`, `kind`, `unit`, and `description`. @@ -244,17 +244,19 @@ instrument. The API MUST treat it as an opaque string. * It MUST support at least 1023 characters. [OpenTelemetry API](../overview.md#api) authors MAY decide if they want to support more. -#### Instrument advice +#### Instrument advisory parameters **Status**: [Experimental](../document-status.md) -`advice` are an optional set of recommendations provided by the author of the -Instrument, aimed at assisting implementations in providing useful output with -minimal configuration. +`advisory` parameters are an optional set of recommendations provided by the +author of the Instrument, aimed at assisting implementations in providing +useful output with minimal configuration. They differ from other parameters +in that Implementations MAY ignore `advisory` parameters. -* Implementations MAY ignore `advice`. However, OpenTelemetry SDKs - handle `advice` as described [here](./sdk.md#instrument-advice). -* `advice` parameters may be general, or vary by instrument `kind`. +* OpenTelemetry SDKs MUST handle `advisory` parameters as described + [here](./sdk.md#instrument-advisory-parameters). +* `advisory` parameters may be general, or may be accepted only for specific + instrument `kind`s. * `Histogram`: * `ExplicitBucketBoundaries` (`double[]`): The recommended set of bucket boundaries to use if aggregating to @@ -323,16 +325,16 @@ The API to construct synchronous instruments MUST accept the following parameter 0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane) encoded characters and hold at least 1023 characters. -* `advice` for implementations. +* `advisory` parameters associated with the instrument `kind`. - Users can provide `advice`, but its up to their discretion. Therefore, this - API needs to be structured to accept `advice`, but MUST NOT obligate the user - to provide it. + Users can provide `advisory` parameters, but its up to their discretion. + Therefore, this API needs to be structured to accept `advisory` parameters, + but MUST NOT obligate the user to provide it. - `advice` needs to be structured as described - in [instrument advice](#instrument-advice), with parameters that are general - and specific to a particular instrument `kind`. The API SHOULD NOT - validate `advice`. + `advisory` parameters need to be structured as described in + [instrument advisory parameters](#instrument-advisory-parameters), with + parameters that are general and specific to a particular instrument `kind`. + The API SHOULD NOT validate `advisory` parameters. ##### Asynchronous Instrument API @@ -375,6 +377,16 @@ The API to construct asynchronous instruments MUST accept the following paramete supports at least [BMP (Unicode Plane 0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane) encoded characters and hold at least 1023 characters. +* `advisory` parameters associated with the instrument `kind`. + + Users can provide `advisory` parameters, but its up to their discretion. + Therefore, this API needs to be structured to accept `advisory` parameters, + but MUST NOT obligate the user to provide it. + + `advisory` parameters need to be structured as described in + [instrument advisory parameters](#instrument-advisory-parameters), with + parameters that are general and specific to a particular instrument `kind`. + The API SHOULD NOT validate `advisory` parameters. * `callback` functions that report [Measurements](#measurement) of the created instrument. diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 371987b7b38..c0c91871aac 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -46,7 +46,7 @@ linkTitle: SDK * [Instrument name](#instrument-name) * [Instrument unit](#instrument-unit) * [Instrument description](#instrument-description) - * [Instrument advice](#instrument-advice) + * [Instrument advisory parameters](#instrument-advisory-parameters) - [Attribute limits](#attribute-limits) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) @@ -322,8 +322,9 @@ The SDK MUST accept the following stream configuration parameters: 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 value, the SDK SHOULD use - the [`advice`](./api.md#instrument-advice) configured on the instrument - instead. If the `advice` is absent, all attributes MUST be kept. + the [`Attributes`](./api.md#instrument-advisory-parameters) advisory + parameter configured on the instrument instead. If the `Attributes` + advisory parameter is absent, all attributes MUST be kept. * `aggregation`: The name of an [aggregation](#aggregation) function to use in aggregating the metric stream data. @@ -518,8 +519,8 @@ This Aggregation does not have any configuration parameters. #### Default Aggregation The Default Aggregation informs the SDK to use the Instrument `kind` to select -an aggregation and `advice` to influence aggregation configuration parameters -(as noted in the "Selected Aggregation" column). +an aggregation and `advisory` parameters to influence aggregation configuration +parameters (as noted in the "Selected Aggregation" column). | Instrument Kind | Selected Aggregation | |-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -529,7 +530,7 @@ an aggregation and `advice` to influence aggregation configuration parameters | [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) | | [Gauge](./api.md#gauge) | [Last Value Aggregation](./sdk.md#last-value-aggregation) | | [Asynchronous Gauge](./api.md#asynchronous-gauge) | [Last Value Aggregation](./sdk.md#last-value-aggregation) | -| [Histogram](./api.md#histogram) | [Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation), with `ExplicitBucketBoundaries` from [advice](./api.md#instrument-advice) if provided | +| [Histogram](./api.md#histogram) | [Explicit Bucket Histogram Aggregation](./sdk.md#explicit-bucket-histogram-aggregation), with the `ExplicitBucketBoundaries` [advisory parameter](./api.md#instrument-advisory-parameters) if provided | This Aggregation does not have any configuration parameters. @@ -848,12 +849,12 @@ When a Meter creates an instrument, it SHOULD NOT validate the instrument description. If a description is not provided or the description is null, the Meter MUST treat it the same as an empty description string. -### Instrument advice +### Instrument advisory parameters **Status**: [Experimental](../document-status.md) -When a Meter creates an instrument, it SHOULD validate the instrument advice -parameters. If an advice parameter is not valid, the Meter SHOULD emit an error +When a Meter creates an instrument, it SHOULD validate the instrument advisory +parameters. If an advisory parameter is not valid, the Meter SHOULD emit an error notifying the user and proceed as if the parameter was not provided. If multiple [identical Instruments](api.md#instrument) are created with diff --git a/specification/metrics/semantic_conventions/http-metrics.md b/specification/metrics/semantic_conventions/http-metrics.md index 49de8803372..e56b5de8d4f 100644 --- a/specification/metrics/semantic_conventions/http-metrics.md +++ b/specification/metrics/semantic_conventions/http-metrics.md @@ -62,7 +62,7 @@ operations. By adding HTTP attributes to metric events it allows for finely tune This metric is required. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. @@ -247,7 +247,7 @@ SHOULD NOT be set if only IP address is available and capturing name would requi This metric is required. This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/api.md#instrument-advisory-parameters) of `[ 0, 0.005, 0.01, 0.025, 0.05, 0.075, 0.1, 0.25, 0.5, 0.75, 1, 2.5, 5, 7.5, 10 ]`. diff --git a/specification/metrics/semantic_conventions/runtime-environment-metrics.md b/specification/metrics/semantic_conventions/runtime-environment-metrics.md index 2bd417b9c4a..127d9daacfd 100644 --- a/specification/metrics/semantic_conventions/runtime-environment-metrics.md +++ b/specification/metrics/semantic_conventions/runtime-environment-metrics.md @@ -222,7 +222,7 @@ This metric is obtained by subscribing to [`GarbageCollectionNotificationInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GarbageCollectionNotificationInfo.html) events provided by [`GarbageCollectorMXBean`](https://docs.oracle.com/javase/8/docs/api/java/lang/management/GarbageCollectorMXBean.html). The duration value is obtained from [`GcInfo`](https://docs.oracle.com/javase/8/docs/jre/api/management/extension/com/sun/management/GcInfo.html#getDuration--) This metric SHOULD be specified with -[`ExplicitBucketBoundaries`](../../metrics/api.md#instrument-advice) +[`ExplicitBucketBoundaries`](../../metrics/api.md#instrument-advisory-parameters) of `[]` (single bucket histogram capturing count, sum, min, max).