diff --git a/CHANGELOG.md b/CHANGELOG.md index a6590c00b68..4921c3137ad 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ release. ### Metrics +- Add experimental histogram advice API. + ([#3216](https://github.com/open-telemetry/opentelemetry-specification/pull/3216)) + ### Logs - Clarify parameters for emitting a log record. @@ -52,6 +55,8 @@ release. ([#3306](https://github.com/open-telemetry/opentelemetry-specification/pull/3306)) - Remove No-Op instrument and Meter creation requirements. ([#3322](https://github.com/open-telemetry/opentelemetry-specification/pull/3322)) +- Fixed attributes requirement level in semantic conventions for hardware metrics + ([#3258](https://github.com/open-telemetry/opentelemetry-specification/pull/3258)) ### Logs diff --git a/specification/metrics/api.md b/specification/metrics/api.md index d044bc348a6..9cc473b4b7a 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -4,7 +4,7 @@ linkTitle: API # Metrics API -**Status**: [Stable](../document-status.md) +**Status**: [Stable](../document-status.md), except where otherwise specified
Table of Contents @@ -22,6 +22,7 @@ linkTitle: API + [Instrument name syntax](#instrument-name-syntax) + [Instrument unit](#instrument-unit) + [Instrument description](#instrument-description) + + [Instrument advice](#instrument-advice) + [Synchronous and Asynchronous instruments](#synchronous-and-asynchronous-instruments) - [Synchronous Instrument API](#synchronous-instrument-api) - [Asynchronous Instrument API](#asynchronous-instrument-api) @@ -182,6 +183,7 @@ will have the following fields: one of the other kinds, whether it is synchronous or asynchronous * An optional `unit` of measure * An optional `description` +* Optional `advice` (**experimental**) Instruments are associated with the Meter during creation. Instruments are identified by all of these fields. @@ -235,6 +237,22 @@ 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 + +**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. + +* 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`. + * `Histogram`: + * `ExplicitBucketBoundaries` (`double[]`): The recommended set of bucket + boundaries to use if aggregating to + [explicit bucket Histogram metric data point](./data-model.md#histogram). + #### Synchronous and Asynchronous instruments Instruments are categorized on whether they are synchronous or @@ -295,6 +313,17 @@ 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. + + 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. + + `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`. + ##### Asynchronous Instrument API Asynchronous instruments have associated `callback` functions which diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index c3776142538..eab03a4dfd4 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -35,6 +35,7 @@ linkTitle: SDK * [Instrument name](#instrument-name) * [Instrument unit](#instrument-unit) * [Instrument description](#instrument-description) + * [Instrument advice](#instrument-advice) - [Attribute limits](#attribute-limits) - [Exemplar](#exemplar) * [ExemplarFilter](#exemplarfilter) @@ -396,18 +397,18 @@ This Aggregation does not have any configuration parameters. #### Default Aggregation -The Default Aggregation informs the SDK to use the Instrument Kind -(e.g. at View registration OR at first seen measurement) -to select an aggregation and configuration parameters. +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). -| Instrument Kind | Selected Aggregation | -| --- |-----------------------------------------------------------------------------------------| -| [Counter](./api.md#counter) | [Sum Aggregation](./sdk.md#sum-aggregation) | -| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregation](./sdk.md#sum-aggregation) | -| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) | -| [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-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) | +| Instrument Kind | Selected Aggregation | +|-------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [Counter](./api.md#counter) | [Sum Aggregation](./sdk.md#sum-aggregation) | +| [Asynchronous Counter](./api.md#asynchronous-counter) | [Sum Aggregation](./sdk.md#sum-aggregation) | +| [UpDownCounter](./api.md#updowncounter) | [Sum Aggregation](./sdk.md#sum-aggregation) | +| [Asynchronous UpDownCounter](./api.md#asynchronous-updowncounter) | [Sum Aggregation](./sdk.md#sum-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 | This Aggregation does not have any configuration parameters. @@ -643,6 +644,14 @@ 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 + +**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 +notifying the user and proceed as if the parameter was not provided. + ## Attribute limits **Status**: [Stable](../document-status.md)