Skip to content

Commit d83c63d

Browse files
authored
Clarify SDK behavior for Instrument Advisory Parameter (#4389)
Also Fixes #4317 ## Changes Mostly editorial, to specify SDK behavior for Advisory Parameters, explicitly calling out that SDK MUST give precedence to View config over InstrumentAdvisory. I believe this is already the intention, but was less specified. Though some wordings exist in the View spec about attribute-keys, no mention about Histogram buckets.
1 parent 9c8c306 commit d83c63d

File tree

1 file changed

+43
-5
lines changed

1 file changed

+43
-5
lines changed

specification/metrics/sdk.md

Lines changed: 43 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -49,6 +49,8 @@ linkTitle: SDK
4949
* [Instrument unit](#instrument-unit)
5050
* [Instrument description](#instrument-description)
5151
* [Instrument advisory parameters](#instrument-advisory-parameters)
52+
+ [Instrument advisory parameter: `ExplicitBucketBoundaries`](#instrument-advisory-parameter-explicitbucketboundaries)
53+
+ [Instrument advisory parameter: `Attributes`](#instrument-advisory-parameter-attributes)
5254
* [Instrument enabled](#instrument-enabled)
5355
- [Attribute limits](#attribute-limits)
5456
- [Exemplar](#exemplar)
@@ -418,9 +420,10 @@ made with an Instrument:
418420

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

946951
### Instrument advisory parameters
947952

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

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

964+
If both a [View](#view) and advisory parameters specify the same aspect of the
965+
[Stream configuration](#stream-configuration), the setting defined by the View
966+
MUST take precedence over the advisory parameters.
967+
968+
#### Instrument advisory parameter: `ExplicitBucketBoundaries`
969+
970+
This advisory parameter applies when the [Explicit Bucket
971+
Histogram](#explicit-bucket-histogram-aggregation) aggregation is used.
972+
973+
If a matching View specifies Explicit Bucket Histogram aggregation (with or
974+
without bucket boundaries), the `ExplicitBucketBoundaries` advisory parameter is
975+
ignored.
976+
977+
If no View matches, or if a matching View selects the [default
978+
aggregation](#default-aggregation), the `ExplicitBucketBoundaries` advisory
979+
parameter MUST be used. If neither is provided, the default bucket boundaries
980+
apply.
981+
982+
#### Instrument advisory parameter: `Attributes`
983+
984+
**Status**: [Development](../document-status.md)
985+
986+
This advisory parameter applies to all aggregations.
987+
988+
`Attributes` (a list of [attribute keys](../common/README.md#attribute))
989+
specifies the recommended set of attribute keys for measurements aggregated to
990+
produce a metric stream.
991+
992+
If the user has provided attribute keys via View(s), those keys take precedence.
993+
If no View is configured, or if a matching view does not specify attribute keys,
994+
the advisory parameter should be used. If neither is provided, all attributes
995+
must be retained.
996+
959997
### Instrument enabled
960998

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

0 commit comments

Comments
 (0)