Propose histogram bucket boundary metric advice (aka hint API)

CHANGELOG.md

@@ -25,6 +25,8 @@ release.
  ([#3322](https:/open-telemetry/opentelemetry-specification/pull/3322))
 - Fixed attributes requirement level in semantic conventions for hardware metrics
  ([#3258](https:/open-telemetry/opentelemetry-specification/pull/3258))
+- Add experimental histogram advice API.
+ ([#3216](https:/open-telemetry/opentelemetry-specification/pull/3216))
 
 ### Logs
 

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
 
 <details>
 <summary>Table of Contents</summary>
@@ -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

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)