Skip to content
Merged
Changes from all commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
48 changes: 43 additions & 5 deletions specification/metrics/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,8 @@ linkTitle: SDK
* [Instrument unit](#instrument-unit)
* [Instrument description](#instrument-description)
* [Instrument advisory parameters](#instrument-advisory-parameters)
+ [Instrument advisory parameter: `ExplicitBucketBoundaries`](#instrument-advisory-parameter-explicitbucketboundaries)
+ [Instrument advisory parameter: `Attributes`](#instrument-advisory-parameter-attributes)
* [Instrument enabled](#instrument-enabled)
- [Attribute limits](#attribute-limits)
- [Exemplar](#exemplar)
Expand Down Expand Up @@ -418,9 +420,10 @@ made with an Instrument:

* Determine the `MeterProvider` which "owns" the Instrument.
* If the `MeterProvider` has no `View` registered, take the Instrument
and apply the default Aggregation on the basis of instrument kind
according to the [MetricReader](#metricreader) instance's
`aggregation` property.
and apply the default Aggregation on the basis of instrument kind according
to the [MetricReader](#metricreader) instance's `aggregation` property.
[Instrument advisory parameters](#instrument-advisory-parameters), if any,
MUST be honored.
* If the `MeterProvider` has one or more `View`(s) registered:
* If the Instrument could match the instrument selection criteria, for each
View:
Expand All @@ -436,7 +439,9 @@ made with an Instrument:
View sets an asynchronous instrument to use the [Explicit bucket
histogram aggregation](#explicit-bucket-histogram-aggregation)) the
implementation SHOULD emit a warning and proceed as if the View did not
exist.
If both a View and [Instrument advisory parameters](#instrument-advisory-parameters)
specify the same aspect of the [Stream configuration](#stream-configuration),
the setting defined by the View MUST take precedence over the advisory parameters.
* If the Instrument could not match with any of the registered `View`(s), the
SDK SHOULD enable the instrument using the default aggregation and temporality.
Users can configure match-all Views using [Drop aggregation](#drop-aggregation)
Expand Down Expand Up @@ -945,7 +950,7 @@ Meter MUST treat it the same as an empty description string.

### Instrument advisory parameters

**Status**: [Development](../document-status.md)
**Status**: [Stable](../document-status.md), except where otherwise specified

When a Meter creates an instrument, it SHOULD validate the instrument advisory
parameters. If an advisory parameter is not valid, the Meter SHOULD emit an error
Expand All @@ -956,6 +961,39 @@ different advisory parameters, the Meter MUST return an instrument using the
first-seen advisory parameters and log an appropriate error as described in
[duplicate instrument registrations](#duplicate-instrument-registration).

If both a [View](#view) and advisory parameters specify the same aspect of the
[Stream configuration](#stream-configuration), the setting defined by the View
MUST take precedence over the advisory parameters.

#### Instrument advisory parameter: `ExplicitBucketBoundaries`

This advisory parameter applies when the [Explicit Bucket
Histogram](#explicit-bucket-histogram-aggregation) aggregation is used.

If a matching View specifies Explicit Bucket Histogram aggregation (with or
without bucket boundaries), the `ExplicitBucketBoundaries` advisory parameter is
ignored.

If no View matches, or if a matching View selects the [default
aggregation](#default-aggregation), the `ExplicitBucketBoundaries` advisory
parameter MUST be used. If neither is provided, the default bucket boundaries
apply.

#### Instrument advisory parameter: `Attributes`

**Status**: [Development](../document-status.md)

This advisory parameter applies to all aggregations.

`Attributes` (a list of [attribute keys](../common/README.md#attribute))
specifies the recommended set of attribute keys for measurements aggregated to
produce a metric stream.

If the user has provided attribute keys via View(s), those keys take precedence.
If no View is configured, or if a matching view does not specify attribute keys,
the advisory parameter should be used. If neither is provided, all attributes
must be retained.

### Instrument enabled

**Status**: [Development](../document-status.md)
Expand Down