Propose histogram bucket boundary metric advice (aka hint API) (open-…

…telemetry#3216)

Fixes open-telemetry#2229.
Related to open-telemetry#3061 (lays groundwork but does not resolve).
Related to open-telemetry#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](open-telemetry/opentelemetry-java#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 <reyang@microsoft.com>

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
 

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)