From feb4dac0742e3dd749954af295086ffdcd4571c8 Mon Sep 17 00:00:00 2001 From: jack-berg <34418638+jack-berg@users.noreply.github.com> Date: Sat, 8 Apr 2023 10:55:36 -0500 Subject: [PATCH] Propose histogram bucket boundary metric advice (aka hint API) (#3216) Fixes #2229. Related to #3061 (lays groundwork but does not resolve). Related to #2977, which may use this new API to have `http.server.duration` report in seconds instead of ms without changing / breaking default bucket boundaries. Summary of the change: - Proposes a new parameter to optionally include when creating instruments, called "advice". - For the moment, advice only has one parameter for specifying the bucket boundaries of explicit bucket histogram. - Advice can be expanded with additional parameters in the future (e.g. default attributes to retain). The parameters may be general (aka applicable to all instruments) or specific to a particular instrument kind, like bucket boundaries. - Advice parameters can influence the [default aggregation](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#default-aggregation), which is used if there is no matching view and if the reader does not specify a preferred aggregation. - Not clear that all advice will be oriented towards configuring aggregation, so I've intentionally left the scope of what they can influence open ended. I've prototyped this in java [here](https://github.com/open-telemetry/opentelemetry-java/pull/5217). Example usage: ``` DoubleHistogram doubleHistogram = meterProvider .get("meter") .histogramBuilder("histogram") .setUnit("foo") .setDescription("bar") .setAdvice( advice -> advice.setBoundaries(Arrays.asList(10.0, 20.0, 30.0))) .build(); ``` Advice could easily be changed to "hint" with everything else being equal. I thought "advice" clearly described what we're trying to accomplish, which is advice / recommend the implementation in providing useful output with minimal configuration. --------- Co-authored-by: Reiley Yang --- CHANGELOG.md | 5 +++++ specification/metrics/api.md | 31 ++++++++++++++++++++++++++++++- specification/metrics/sdk.md | 31 ++++++++++++++++++++----------- 3 files changed, 55 insertions(+), 12 deletions(-) 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)