From 2122ce5f4b4cbb452f214d1b4154976abd899388 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Thu, 31 Mar 2022 15:39:02 -0500 Subject: [PATCH 1/7] Clarify view conflicts --- specification/metrics/sdk.md | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index c4d178fd224..f0caa99b79f 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -210,11 +210,13 @@ made with an Instrument: * If the `MeterProvider` has one or more `View`(s) registered: * For each View, if the Instrument could match the instrument selection criteria: - * Try to apply the View configuration. If there is an error or a conflict - (e.g. the View requires to export the metrics using a certain name, but - the name is already used by another View), provide a way to let the user - know (e.g. expose - [self-diagnostics logs](../error-handling.md#self-diagnostics)). + * Try to apply the View configuration. If applying the View results + in [duplicate instruments](./api.md#instrument-type-conflict-detection) + with the same name, the implementation SHOULD apply the View and emit a + warning. If it is not possible to apply the View without producing + semantic errors (e.g. the View sets an asynchronous instrument to use + the [Histogram aggregation](#histogram-aggregation)) the implementation + SHOULD drop the View and emit a warning. * 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) From 2e0176c88dc2b5437e3485d123e8ee96dce82eb3 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Thu, 31 Mar 2022 17:12:40 -0500 Subject: [PATCH 2/7] SDKs may fail fast on view registration conflict --- specification/metrics/sdk.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index f0caa99b79f..a27b9b64a8f 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -196,8 +196,11 @@ In order to avoid conflicts, views which specify a name SHOULD have an instrument selector that selects at most one instrument. For the registration mechanism described above, where selection is provided via configuration, the SDK SHOULD NOT allow Views with a specified name to be declared with instrument -selectors that may select more than one instrument (e.g. wild card instrument name) -in the same Meter. +selectors that may select more than one instrument (e.g. wild card instrument +name) in the same Meter. For this and other cases where registering a view will +cause a conflict, SDKs MAY fail fast in accordance with +initialization [error handling principles](../error-handling.md#basic-error-handling-principles) +. The SDK SHOULD use the following logic to determine how to process Measurements made with an Instrument: From 415e7df9a4f3b40c8ae07bd516e3a589f10cbb9c Mon Sep 17 00:00:00 2001 From: jack-berg Date: Thu, 31 Mar 2022 17:25:54 -0500 Subject: [PATCH 3/7] Conflicting views produce metric identity conflicts --- specification/metrics/sdk.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index a27b9b64a8f..dfdad95f2c2 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -214,10 +214,10 @@ made with an Instrument: * For each View, if the Instrument could match the instrument selection criteria: * Try to apply the View configuration. If applying the View results - in [duplicate instruments](./api.md#instrument-type-conflict-detection) - with the same name, the implementation SHOULD apply the View and emit a - warning. If it is not possible to apply the View without producing - semantic errors (e.g. the View sets an asynchronous instrument to use + in [conflicting metric identities](./datamodel.md#exponentialhistogram-producer-recommendations) + the implementation SHOULD apply the View and emit a warning. If it is not + possible to apply the View without producing semantic errors (e.g. the + View sets an asynchronous instrument to use the [Histogram aggregation](#histogram-aggregation)) the implementation SHOULD drop the View and emit a warning. * If the Instrument could not match with any of the registered `View`(s), the From 97e43af774163749199340702a6f9ef40b52f161 Mon Sep 17 00:00:00 2001 From: Joshua MacDonald Date: Fri, 1 Apr 2022 12:17:04 -0700 Subject: [PATCH 4/7] Update specification/metrics/sdk.md --- 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 dfdad95f2c2..f30a0e57a82 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -214,7 +214,7 @@ made with an Instrument: * For each View, if the Instrument could match the instrument selection criteria: * Try to apply the View configuration. If applying the View results - in [conflicting metric identities](./datamodel.md#exponentialhistogram-producer-recommendations) + in [conflicting metric identities](./datamodel.md#opentelemetry-protocol-data-model-producer-recommendations) the implementation SHOULD apply the View and emit a warning. If it is not possible to apply the View without producing semantic errors (e.g. the View sets an asynchronous instrument to use From 2695c7d7a54c06b5dd04ef57d0c739b1d181cd8e Mon Sep 17 00:00:00 2001 From: jack-berg Date: Wed, 6 Apr 2022 15:30:11 -0500 Subject: [PATCH 5/7] Clarify view semantic error behavior --- specification/metrics/sdk.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index dfdad95f2c2..79a58ffde54 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -199,8 +199,7 @@ SDK SHOULD NOT allow Views with a specified name to be declared with instrument selectors that may select more than one instrument (e.g. wild card instrument name) in the same Meter. For this and other cases where registering a view will cause a conflict, SDKs MAY fail fast in accordance with -initialization [error handling principles](../error-handling.md#basic-error-handling-principles) -. +initialization [error handling principles](../error-handling.md#basic-error-handling-principles). The SDK SHOULD use the following logic to determine how to process Measurements made with an Instrument: @@ -219,7 +218,7 @@ made with an Instrument: possible to apply the View without producing semantic errors (e.g. the View sets an asynchronous instrument to use the [Histogram aggregation](#histogram-aggregation)) the implementation - SHOULD drop the View and emit a warning. + SHOULD emit a warning and proceed as if the View did not exist. * 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) From 0151177171150747b9a5b6b28737016b13b2f1c5 Mon Sep 17 00:00:00 2001 From: jack-berg Date: Wed, 6 Apr 2022 15:33:07 -0500 Subject: [PATCH 6/7] Update changelog --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5a9b68363b1..390db8866a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,9 @@ release. ### Metrics +- Clarify SDK behavior when view conflicts are present + ([#2462](https://github.com/open-telemetry/opentelemetry-specification/pull/2462)). + ### Logs ### Resource From ba43060790e764b8d407e99ca063ebfa0c1cc17e Mon Sep 17 00:00:00 2001 From: jack-berg Date: Wed, 13 Apr 2022 10:36:38 -0500 Subject: [PATCH 7/7] Fix merge --- specification/metrics/sdk.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 06b226b2e9a..e040fabeece 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -216,8 +216,9 @@ made with an Instrument: the implementation SHOULD apply the View and emit a warning. If it is not possible to apply the View without producing semantic errors (e.g. the View sets an asynchronous instrument to use - the [Histogram aggregation](#histogram-aggregation)) the implementation - SHOULD emit a warning and proceed as if the View did not exist. + 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 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)