Propose histogram bucket boundary metric advice (aka hint API)

CHANGELOG.md

@@ -15,6 +15,8 @@ release.
 
 - Clarify that units should use UCUM case sensitive variant.
  ([#3306](https:/open-telemetry/opentelemetry-specification/pull/3306))
+- 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**: [Mixed](../document-status.md)
 
 <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)
@@ -57,6 +58,8 @@ linkTitle: API
 
 ## Overview
 
+**Status**: [Stable](../document-status.md)
+
 The Metrics API consists of these main components:
 
 * [MeterProvider](#meterprovider) is the entry point of the API. It provides
@@ -94,6 +97,8 @@ the metrics API:
 
 ## MeterProvider
 
+**Status**: [Stable](../document-status.md)
+
 `Meter`s can be accessed with a `MeterProvider`.
 
 In implementations of the API, the `MeterProvider` is expected to be the
@@ -154,6 +159,8 @@ at least one identifying field has a different value.
 
 ## Meter
 
+**Status**: [Stable](../document-status.md)
+
 The meter is responsible for creating [Instruments](#instrument).
 
 Note: `Meter` SHOULD NOT be responsible for the configuration. This should be
@@ -174,6 +181,8 @@ Also see the respective sections below for more information on instrument creati
 
 ## Instrument
 
+**Status**: [Mixed](../document-status.md)
+
 Instruments are used to report [Measurements](#measurement). Each Instrument
 will have the following fields:
 
@@ -182,6 +191,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.
@@ -193,6 +203,8 @@ floating point numbers SHOULD be considered as identifying.
 
 #### Instrument name syntax
 
+**Status**: [Stable](../document-status.md)
+
 The instrument name syntax is defined below using the [Augmented Backus-Naur
 Form](https://tools.ietf.org/html/rfc5234):
 
@@ -212,6 +224,8 @@ DIGIT = %x30-39 ; 0-9
 
 #### Instrument unit
 
+**Status**: [Stable](../document-status.md)
+
 The `unit` is an optional string provided by the author of the Instrument. The
 API SHOULD treat it as an opaque string.
 
@@ -224,6 +238,8 @@ API SHOULD treat it as an opaque string.
 
 #### Instrument description
 
+**Status**: [Stable](../document-status.md)
+
 The `description` is an optional free-form text provided by the author of the
 instrument. The API MUST treat it as an opaque string.
 
@@ -235,8 +251,26 @@ 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 in [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
 
+**Status**: [Stable](../document-status.md)
+
 Instruments are categorized on whether they are synchronous or
 asynchronous:
 
@@ -295,6 +329,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
@@ -410,6 +455,8 @@ or something else).
 
 ### Counter
 
+**Status**: [Stable](../document-status.md)
+
 `Counter` is a [synchronous Instrument](#synchronous-instrument-api) which supports
 non-negative increments.
 
@@ -512,6 +559,8 @@ counterPowerUsed.Add(200, new PowerConsumption { customer = "Jerry" }, ("is_gree
 
 ### Asynchronous Counter
 
+**Status**: [Stable](../document-status.md)
+
 Asynchronous Counter is an [asynchronous Instrument](#asynchronous-instrument-api)
 which reports [monotonically](https://wikipedia.org/wiki/Monotonic_function)
 increasing value(s) when the instrument is being observed.
@@ -648,6 +697,8 @@ class Device:
 
 ### Histogram
 
+**Status**: [Stable](../document-status.md)
+
 `Histogram` is a [synchronous Instrument](#synchronous-instrument-api) which can be
 used to report arbitrary values that are likely to be statistically meaningful.
 It is intended for statistics such as histograms, summaries, and percentile.
@@ -741,6 +792,8 @@ httpServerDuration.Record(100, new HttpRequestAttributes { method = "GET", schem
 
 ### Asynchronous Gauge
 
+**Status**: [Stable](../document-status.md)
+
 Asynchronous Gauge is an [asynchronous Instrument](#asynchronous-instrument-api)
 which reports non-additive value(s) (e.g. the room temperature - it makes no
 sense to report the temperature value from multiple rooms and sum them up) when
@@ -856,6 +909,8 @@ class Device:
 
 ### UpDownCounter
 
+**Status**: [Stable](../document-status.md)
+
 `UpDownCounter` is a [synchronous Instrument](#synchronous-instrument-api) which
 supports increments and decrements.
 
@@ -982,6 +1037,8 @@ customersInStore.Add(-1, new Account { Type = "residential" });
 
 ### Asynchronous UpDownCounter
 
+**Status**: [Stable](../document-status.md)
+
 Asynchronous UpDownCounter is an [asynchronous
 Instrument](#asynchronous-instrument-api) which reports additive value(s) (e.g. the
 process heap size - it makes sense to report the heap size from multiple
@@ -1102,6 +1159,8 @@ class Device:
 
 ## Measurement
 
+**Status**: [Stable](../document-status.md)
+
 A `Measurement` represents a data point reported via the metrics API to the SDK.
 Please refer to the [Metrics Programming Model](./README.md#programming-model)
 for the interaction between the API and SDK.
@@ -1156,6 +1215,8 @@ class Device:
 
 ## Compatibility requirements
 
+**Status**: [Stable](../document-status.md)
+
 All the metrics components SHOULD allow new APIs to be added to
 existing components without introducing breaking changes.
 
@@ -1164,6 +1225,8 @@ APIs without introducing breaking changes, if possible.
 
 ## Concurrency requirements
 
+**Status**: [Stable](../document-status.md)
+
 For languages which support concurrent execution the Metrics APIs provide
 specific guarantees and safeties.
 

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.
 
@@ -583,11 +584,15 @@ given instrument before starting a subsequent round of collection.
 
 ## Meter
 
+**Status**: [Mixed](../document-status.md)
+
 Distinct meters MUST be treated as separate namespaces for the purposes of detecting
 [duplicate instrument registrations](#duplicate-instrument-registration).
 
 ### Duplicate instrument registration
 
+**Status**: [Stable](../document-status.md)
+
 When more than one Instrument of the same `name` is created for identical
 Meters, denoted _duplicate instrument registration_, the Meter MUST create a
 valid Instrument in every case. Here, "valid" means an instrument that is
@@ -624,6 +629,8 @@ information for the user on how to resolve the conflict, if possible.
 
 ### Instrument name
 
+**Status**: [Stable](../document-status.md)
+
 When a Meter creates an instrument, it SHOULD validate the instrument name
 conforms to the [instrument name syntax](./api.md#instrument-name-syntax)
 
@@ -633,16 +640,28 @@ valid instrument is also returned.
 
 ### Instrument unit
 
+**Status**: [Stable](../document-status.md)
+
 When a Meter creates an instrument, it SHOULD NOT validate the instrument unit.
 If a unit is not provided or the unit is null, the Meter MUST treat it the same
 as an empty unit string.
 
 ### Instrument description
 
+**Status**: [Stable](../document-status.md)
+
 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)