From 69b7573c3adb2aaf6c1693dd21fc09236e512cdb Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Tue, 28 Jan 2025 10:45:32 -0800 Subject: [PATCH 1/4] Clarify SDK behavior for Instrument Advisory Parameter --- specification/metrics/sdk.md | 46 ++++++++++++++++++++++++++++++++---- 1 file changed, 41 insertions(+), 5 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f8cabadf05f..31fdcf53221 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -418,9 +418,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: @@ -436,7 +437,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. + exist. If any configuration is provided via View and [Instrument advisory + parameters](#instrument-advisory-parameters), then the View configuration + MUST take precedence. * 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) @@ -945,7 +948,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) 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 @@ -956,6 +959,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 a [View](#view) is configured with the same settings as advisory parameters, +the View MUST take precedence over the advisory parameters. + +#### Instrument advisory parameter: `ExplicitBucketBoundaries` + +**Status**: [Stable](../document-status.md) + +This parameter is applicable when the [Explicit Bucket +Histogram](#explicit-bucket-histogram-aggregation) aggregation is utilized. + +`ExplicitBucketBoundaries` (`double[]`) specifies the recommended set of bucket +boundaries to use during the [Explicit Bucket +Histogram](#explicit-bucket-histogram-aggregation) aggregation. If the user has +configured a View with specific bucket boundaries, those boundaries should take +precedence. In the absence of such a configuration, the advisory parameter +should be used. If neither is provided, the default bucket boundaries must be +applied. + +#### Instrument advisory parameter: `Attributes` + +**Status**: [Development](../document-status.md) + +This parameter is applicable 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 a View, those keys should take +precedence. If no View is configured, the advisory parameter configured on the +instrument should be used. If the `Attributes` advisory parameter is also +absent, all attributes must be retained. + ### Instrument enabled **Status**: [Development](../document-status.md) From ee844ac1c96c36fb810aa6f0732b1d12743710d7 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Tue, 28 Jan 2025 10:50:37 -0800 Subject: [PATCH 2/4] fix TOC --- specification/metrics/sdk.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 31fdcf53221..dd5a5bab033 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -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) From f24387769733fddccebfe0cf690b1d418f94b2be Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Tue, 28 Jan 2025 11:06:08 -0800 Subject: [PATCH 3/4] Update specification/metrics/sdk.md Co-authored-by: Trask Stalnaker --- specification/metrics/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index dd5a5bab033..6b4079f1b0e 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -950,7 +950,7 @@ Meter MUST treat it the same as an empty description string. ### Instrument advisory parameters -**Status**: [Stable](../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 From daabd2d42163f2c308c2b4f4a002660a8a559f10 Mon Sep 17 00:00:00 2001 From: Cijo Thomas Date: Wed, 19 Feb 2025 09:25:00 -0800 Subject: [PATCH 4/4] better wording based on feedback --- specification/metrics/sdk.md | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 060b196348e..ab477c1deab 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -961,38 +961,37 @@ 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 a [View](#view) is configured with the same settings as advisory parameters, -the View MUST take precedence over the advisory parameters. +If both a [View](#view) and advisory parameters specify the same aspect of the +[Stream configuration](#stream-configuration), the settings defined by the View +MUST take precedence over the advisory parameters. #### Instrument advisory parameter: `ExplicitBucketBoundaries` **Status**: [Stable](../document-status.md) -This parameter is applicable when the [Explicit Bucket -Histogram](#explicit-bucket-histogram-aggregation) aggregation is utilized. +This advisory parameter applies when the [Explicit Bucket +Histogram](#explicit-bucket-histogram-aggregation) aggregation is used. `ExplicitBucketBoundaries` (`double[]`) specifies the recommended set of bucket -boundaries to use during the [Explicit Bucket +boundaries for the [Explicit Bucket Histogram](#explicit-bucket-histogram-aggregation) aggregation. If the user has -configured a View with specific bucket boundaries, those boundaries should take -precedence. In the absence of such a configuration, the advisory parameter -should be used. If neither is provided, the default bucket boundaries must be -applied. +configured custom bucket boundaries via View(s), those boundaries take +precedence. If no View is configured, the advisory parameter should be used. If +neither is provided, the default bucket boundaries must be applied. #### Instrument advisory parameter: `Attributes` **Status**: [Development](../document-status.md) -This parameter is applicable to all aggregations. +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 a View, those keys should take -precedence. If no View is configured, the advisory parameter configured on the -instrument should be used. If the `Attributes` advisory parameter is also -absent, all attributes must be retained. +If the user has provided attribute keys via View(s), those keys take precedence. +If no View is configured, the advisory parameter should be used. If neither is +provided, all attributes must be retained. ### Instrument enabled