From a76d952d08bd754490b13f91d38c0709804a0616 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 15 Jul 2024 11:13:09 +0200 Subject: [PATCH 01/15] Clarify in API spec that instrumentation scope attributes MUST be handled --- specification/logs/bridge-api.md | 7 ++++--- specification/metrics/api.md | 5 +++++ specification/trace/api.md | 8 ++++---- 3 files changed, 13 insertions(+), 7 deletions(-) diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index 6fccedd6f87..c70f10515eb 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -95,9 +95,10 @@ The term *identical* applied to `Logger`s describes instances where all identifying fields are equal. The term *distinct* applied to `Logger`s describes instances where at least one identifying field has a different value. -The effect of associating a Schema URL with a `Logger` MUST be that the telemetry -emitted using the `Logger` will be associated with the Schema URL, provided that -the emitted data format is capable of representing such association. +The effect of associating a Schema URL and instrumentation scope attributes with +a `Logger` MUST be that the telemetry emitted using the `Logger` will be +associated with the Schema URL and instrumentation scope attributes, provided +that the emitted data format is capable of representing such association. ## Logger diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 1103869a115..34e1f326c3d 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -159,6 +159,11 @@ The term *identical* applied to Meters describes instances where all identifying fields are equal. The term *distinct* applied to Meters describes instances where at least one identifying field has a different value. +The effect of associating a Schema URL and instrumentation scope attributes with +a `Meter` MUST be that the telemetry emitted using the `Meter` will be +associated with the Schema URL and instrumentation scope attributes, provided +that the emitted data format is capable of representing such association. + ## Meter The meter is responsible for creating [Instruments](#instrument). diff --git a/specification/trace/api.md b/specification/trace/api.md index b06810ecc53..4e0560f3128 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -161,10 +161,10 @@ the tracer could, for example, do a look-up with its identity in a map in the `TracerProvider`, or the `TracerProvider` could maintain a registry of all returned `Tracer`s and actively update their configuration if it changes. -The effect of associating a Schema URL with a `Tracer` MUST be that the -telemetry emitted using the `Tracer` will be associated with the Schema URL, -provided that the emitted data format is capable of representing such -association. +The effect of associating a Schema URL and instrumentation scope attributes with +a `Tracer` MUST be that the telemetry emitted using the `Tracer` will be +associated with the Schema URL and instrumentation scope attributes, provided +that the emitted data format is capable of representing such association. ## Context Interaction From 7086186f07ddcb00248b14c10eaf6ee8c3b5b4fe Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 15 Jul 2024 11:39:29 +0200 Subject: [PATCH 02/15] Define how SDKs should handle identifacal creation calls --- specification/logs/sdk.md | 7 +++++++ specification/metrics/api.md | 5 ----- specification/metrics/sdk.md | 10 ++++++++-- specification/trace/sdk.md | 5 +++++ 4 files changed, 20 insertions(+), 7 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index be06ddc56b6..154e9839f00 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -67,11 +67,18 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Logger`. +The method MUST return the same instance when the caller requests *identical* +`Logger`s. In such scenario, the `Logger` MUST have the non-identifying fields' +values (e.g. isntrumentation scope attributes) assigned during the first +*identical* `Logger` creation call. + In the case where an invalid `name` (null or empty string) is specified, a working `Logger` MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. +In case where the + **Status**: [Development](../document-status.md) - The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) using the configured [LoggerConfigurator](#loggerconfigurator), and create diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 34e1f326c3d..1103869a115 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -159,11 +159,6 @@ The term *identical* applied to Meters describes instances where all identifying fields are equal. The term *distinct* applied to Meters describes instances where at least one identifying field has a different value. -The effect of associating a Schema URL and instrumentation scope attributes with -a `Meter` MUST be that the telemetry emitted using the `Meter` will be -associated with the Schema URL and instrumentation scope attributes, provided -that the emitted data format is capable of representing such association. - ## Meter The meter is responsible for creating [Instruments](#instrument). diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 8823b4b69f1..4b8c90607f8 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -123,13 +123,19 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Meter`. +The method MUST return the same instance when the caller requests *identical* +`Meter`s. In such scenario, the `Meter` MUST have the non-identifying fields' +values (e.g. isntrumentation scope attributes) assigned during the first +*identical* `Meter` creation call. + In the case where an invalid `name` (null or empty string) is specified, a working Meter MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. -When a Schema URL is passed as an argument when creating a `Meter` the emitted -telemetry for that `Meter` MUST be associated with the Schema URL, provided +When a Schema URL and instrumentation scope attributes are passed as an argument +when creating a `Meter` the emitted telemetry for that `Meter` MUST be +associated with the Schema URL and instrumentation scope attributes, provided that the emitted data format is capable of representing such association. **Status**: [Development](../document-status.md) - The `MeterProvider` MUST diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 4208c4d89d5..9d193be917a 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -71,6 +71,11 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. +The method MUST return the same instance when the caller requests *identical* +`Tracer`s. In such scenario, the `Tracer` MUST have the non-identifying fields' +values (e.g. isntrumentation scope attributes) assigned during the first +*identical* `Tracer` creation call. + **Status**: [Development](../document-status.md) - The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) using the configured [TracerConfigurator](#tracerconfigurator), and create From 289eea1cf724ba6cbbc59d0ff5e01b91455fcc5e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 15 Jul 2024 11:42:21 +0200 Subject: [PATCH 03/15] Update changelog --- CHANGELOG.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 6deddc0e763..4e8c7a8038a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,10 +11,19 @@ release. ### Traces +- Define how `TracerProvider` handles identical `Tracer` creation calls. + ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) + ### Metrics +- Define how `MeterProvider` handles identical `Meter` creation calls. + ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) + ### Logs +- Define how `LoggerProvider` handles identical `Logger` creation calls. + ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) + ### Events ### Resource From df9b94f69b18a6210ca064cdeff5eb724b800202 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 15 Jul 2024 11:43:07 +0200 Subject: [PATCH 04/15] Remove leftover --- specification/logs/sdk.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 154e9839f00..7827a9c31a9 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -77,8 +77,6 @@ working `Logger` MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. -In case where the - **Status**: [Development](../document-status.md) - The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) using the configured [LoggerConfigurator](#loggerconfigurator), and create From f3496206d3bcb74ff5e2371a37c83df0c71c3686 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 15 Jul 2024 11:45:38 +0200 Subject: [PATCH 05/15] Refine description --- specification/logs/sdk.md | 4 ++-- specification/metrics/sdk.md | 4 ++-- specification/trace/sdk.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 7827a9c31a9..b124872b2e5 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -68,8 +68,8 @@ an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Logger`. The method MUST return the same instance when the caller requests *identical* -`Logger`s. In such scenario, the `Logger` MUST have the non-identifying fields' -values (e.g. isntrumentation scope attributes) assigned during the first +`Logger`s. In such scenario, the returned `Logger` MUST have the non-identifying +fields' values (e.g. isntrumentation scope attributes) assigned during the first *identical* `Logger` creation call. In the case where an invalid `name` (null or empty string) is specified, a diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 4b8c90607f8..a1731a5a962 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -124,8 +124,8 @@ an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Meter`. The method MUST return the same instance when the caller requests *identical* -`Meter`s. In such scenario, the `Meter` MUST have the non-identifying fields' -values (e.g. isntrumentation scope attributes) assigned during the first +`Meter`s. In such scenario, the returned `Meter` MUST have the non-identifying +fields' values (e.g. isntrumentation scope attributes) assigned during the first *identical* `Meter` creation call. In the case where an invalid `name` (null or empty string) is specified, a diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 9d193be917a..2359d6f33ff 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -72,8 +72,8 @@ an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. The method MUST return the same instance when the caller requests *identical* -`Tracer`s. In such scenario, the `Tracer` MUST have the non-identifying fields' -values (e.g. isntrumentation scope attributes) assigned during the first +`Tracer`s. In such scenario, the returned `Tracer` MUST have the non-identifying +fields' values (e.g. isntrumentation scope attributes) assigned during the first *identical* `Tracer` creation call. **Status**: [Development](../document-status.md) - The `TracerProvider` MUST From 6425b5ef23699aa4eb7f9f80a772fca32b27c13b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 15 Jul 2024 21:34:42 +0200 Subject: [PATCH 06/15] Use underscore for emphasis --- specification/logs/sdk.md | 6 +++--- specification/metrics/sdk.md | 6 +++--- specification/trace/sdk.md | 6 +++--- 3 files changed, 9 insertions(+), 9 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index b124872b2e5..6badb2d21d2 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -67,10 +67,10 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Logger`. -The method MUST return the same instance when the caller requests *identical* +The method MUST return the same instance when the caller requests _identical_ `Logger`s. In such scenario, the returned `Logger` MUST have the non-identifying -fields' values (e.g. isntrumentation scope attributes) assigned during the first -*identical* `Logger` creation call. +fields' values (e.g. instrumentation scope attributes) assigned during the first +_identical_ `Logger` creation call. In the case where an invalid `name` (null or empty string) is specified, a working `Logger` MUST be returned as a fallback rather than returning null or diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index a1731a5a962..23e0d2baa17 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -123,10 +123,10 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Meter`. -The method MUST return the same instance when the caller requests *identical* +The method MUST return the same instance when the caller requests _identical_ `Meter`s. In such scenario, the returned `Meter` MUST have the non-identifying -fields' values (e.g. isntrumentation scope attributes) assigned during the first -*identical* `Meter` creation call. +fields' values (e.g. instrumentation scope attributes) assigned during the first +_identical_ `Meter` creation call. In the case where an invalid `name` (null or empty string) is specified, a working Meter MUST be returned as a fallback rather than returning null or diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 2359d6f33ff..c0279da99d7 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -71,10 +71,10 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. -The method MUST return the same instance when the caller requests *identical* +The method MUST return the same instance when the caller requests _identical_ `Tracer`s. In such scenario, the returned `Tracer` MUST have the non-identifying -fields' values (e.g. isntrumentation scope attributes) assigned during the first -*identical* `Tracer` creation call. +fields' values (e.g. instrumentation scope attributes) assigned during the first +_identical_ `Tracer` creation call. **Status**: [Development](../document-status.md) - The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) using the From 8f5530175b2238bd71a0110fc24cb6dfb63fdeb4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 15 Jul 2024 21:49:39 +0200 Subject: [PATCH 07/15] Fix MD049 --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index c0279da99d7..2b4e92992aa 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -241,7 +241,7 @@ Thus, the SDK specification defines sets of possible requirements for both the full span API as defined in the [API-level definition for span's interface](api.md#span-operations) and additionally must be able to retrieve all information that was added to the span - (as with *readable span*). + (as with _readable span_). It MUST be possible for functions being called with this to somehow obtain the same `Span` instance and type From 867ee026681b3480a4402d26d0e889f2a214defd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Mon, 15 Jul 2024 22:05:44 +0200 Subject: [PATCH 08/15] Update CHANGELOG.md --- CHANGELOG.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4e8c7a8038a..0be14a55bd5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,16 +12,19 @@ release. ### Traces - Define how `TracerProvider` handles identical `Tracer` creation calls. + Require that the telemetry emitted using the `Tracer` will be associated with the passed instrumentation scope attributes, provided that the emitted data format is capable of representing such association. ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) ### Metrics - Define how `MeterProvider` handles identical `Meter` creation calls. + Require that the telemetry emitted using the `Meter` will be associated with the passed instrumentation scope attributes, provided that the emitted data format is capable of representing such association. ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) ### Logs - Define how `LoggerProvider` handles identical `Logger` creation calls. + Require that the telemetry emitted using the `Logger` will be associated with the passed instrumentation scope attributes, provided that the emitted data format is capable of representing such association. ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) ### Events From 275fcacb936117398606290cd7b9e11af9e0ec52 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 17 Jul 2024 12:08:39 +0200 Subject: [PATCH 09/15] Loosen the requirements --- CHANGELOG.md | 3 --- specification/logs/bridge-api.md | 7 +++---- specification/logs/sdk.md | 13 ++++++++----- specification/metrics/sdk.md | 18 ++++++++++-------- specification/trace/api.md | 8 ++++---- specification/trace/sdk.md | 14 +++++++++----- 6 files changed, 34 insertions(+), 29 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0be14a55bd5..4e8c7a8038a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -12,19 +12,16 @@ release. ### Traces - Define how `TracerProvider` handles identical `Tracer` creation calls. - Require that the telemetry emitted using the `Tracer` will be associated with the passed instrumentation scope attributes, provided that the emitted data format is capable of representing such association. ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) ### Metrics - Define how `MeterProvider` handles identical `Meter` creation calls. - Require that the telemetry emitted using the `Meter` will be associated with the passed instrumentation scope attributes, provided that the emitted data format is capable of representing such association. ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) ### Logs - Define how `LoggerProvider` handles identical `Logger` creation calls. - Require that the telemetry emitted using the `Logger` will be associated with the passed instrumentation scope attributes, provided that the emitted data format is capable of representing such association. ([#4146](https://github.com/open-telemetry/opentelemetry-specification/pull/4146)) ### Events diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index c70f10515eb..6fccedd6f87 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -95,10 +95,9 @@ The term *identical* applied to `Logger`s describes instances where all identifying fields are equal. The term *distinct* applied to `Logger`s describes instances where at least one identifying field has a different value. -The effect of associating a Schema URL and instrumentation scope attributes with -a `Logger` MUST be that the telemetry emitted using the `Logger` will be -associated with the Schema URL and instrumentation scope attributes, provided -that the emitted data format is capable of representing such association. +The effect of associating a Schema URL with a `Logger` MUST be that the telemetry +emitted using the `Logger` will be associated with the Schema URL, provided that +the emitted data format is capable of representing such association. ## Logger diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 6badb2d21d2..aea3d6568a9 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -67,16 +67,19 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Logger`. -The method MUST return the same instance when the caller requests _identical_ -`Logger`s. In such scenario, the returned `Logger` MUST have the non-identifying -fields' values (e.g. instrumentation scope attributes) assigned during the first -_identical_ `Logger` creation call. - In the case where an invalid `name` (null or empty string) is specified, a working `Logger` MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. +The first _identical_ `Logger` MUST be associated with all +(both identifying and non-identifying) passed parameters. +Currently, it is a user error to create `Logger`s with different +non-identifying parameter values (e.g. instrumentation scope attributes) but +the same identifying parameters. The SDK can handle such cases in its preferred +way. However, it MUST be documented that the behavior may change in future +releases, as this is currently an unsupported usage of the API. + **Status**: [Development](../document-status.md) - The `LoggerProvider` MUST compute the relevant [LoggerConfig](#loggerconfig) using the configured [LoggerConfigurator](#loggerconfigurator), and create diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 23e0d2baa17..5ed82442bcb 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -123,19 +123,21 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Meter`. -The method MUST return the same instance when the caller requests _identical_ -`Meter`s. In such scenario, the returned `Meter` MUST have the non-identifying -fields' values (e.g. instrumentation scope attributes) assigned during the first -_identical_ `Meter` creation call. - In the case where an invalid `name` (null or empty string) is specified, a working Meter MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. -When a Schema URL and instrumentation scope attributes are passed as an argument -when creating a `Meter` the emitted telemetry for that `Meter` MUST be -associated with the Schema URL and instrumentation scope attributes, provided +The first _identical_ `Meter` MUST be associated with all +(both identifying and non-identifying) passed parameters. +Currently, it is a user error to create `Meter`s with different +non-identifying parameter values (e.g. instrumentation scope attributes) but +the same identifying parameters. The SDK can handle such cases in its preferred +way. However, it MUST be documented that the behavior may change in future +releases, as this is currently an unsupported usage of the API. + +When a Schema URL is passed as an argument when creating a `Meter` the emitted +telemetry for that `Meter` MUST be associated with the Schema URL, provided that the emitted data format is capable of representing such association. **Status**: [Development](../document-status.md) - The `MeterProvider` MUST diff --git a/specification/trace/api.md b/specification/trace/api.md index 4e0560f3128..b06810ecc53 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -161,10 +161,10 @@ the tracer could, for example, do a look-up with its identity in a map in the `TracerProvider`, or the `TracerProvider` could maintain a registry of all returned `Tracer`s and actively update their configuration if it changes. -The effect of associating a Schema URL and instrumentation scope attributes with -a `Tracer` MUST be that the telemetry emitted using the `Tracer` will be -associated with the Schema URL and instrumentation scope attributes, provided -that the emitted data format is capable of representing such association. +The effect of associating a Schema URL with a `Tracer` MUST be that the +telemetry emitted using the `Tracer` will be associated with the Schema URL, +provided that the emitted data format is capable of representing such +association. ## Context Interaction diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 2b4e92992aa..88a5ff8a0a8 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -71,10 +71,14 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. -The method MUST return the same instance when the caller requests _identical_ -`Tracer`s. In such scenario, the returned `Tracer` MUST have the non-identifying -fields' values (e.g. instrumentation scope attributes) assigned during the first -_identical_ `Tracer` creation call. +The first _identical_ `Tracer` MUST be associated with all +(both identifying and non-identifying) passed parameters. +Currently, it is a user error to create `Tracer`s with different +non-identifying parameter values (e.g. instrumentation scope attributes) but +the same identifying parameters. The SDK can handle such cases in its preferred +way. However, it MUST be documented that the behavior may change in future +releases, as this is currently an unsupported usage of the API. + **Status**: [Development](../document-status.md) - The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) using the @@ -241,7 +245,7 @@ Thus, the SDK specification defines sets of possible requirements for both the full span API as defined in the [API-level definition for span's interface](api.md#span-operations) and additionally must be able to retrieve all information that was added to the span - (as with _readable span_). + (as with *readable span*). It MUST be possible for functions being called with this to somehow obtain the same `Span` instance and type From 7943abc3e2521f49a9d5688e0307b8f58c0c6dae Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 17 Jul 2024 12:09:40 +0200 Subject: [PATCH 10/15] Remove EOL --- specification/trace/sdk.md | 1 - 1 file changed, 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 88a5ff8a0a8..36eaf466862 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -79,7 +79,6 @@ the same identifying parameters. The SDK can handle such cases in its preferred way. However, it MUST be documented that the behavior may change in future releases, as this is currently an unsupported usage of the API. - **Status**: [Development](../document-status.md) - The `TracerProvider` MUST compute the relevant [TracerConfig](#tracerconfig) using the configured [TracerConfigurator](#tracerconfigurator), and create From 8a12ad9b26a093d7c92c1a1d7ee66a0ed556a305 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 17 Jul 2024 12:15:25 +0200 Subject: [PATCH 11/15] Remove not needed spaces --- specification/logs/sdk.md | 8 ++++---- specification/metrics/sdk.md | 8 ++++---- specification/trace/sdk.md | 8 ++++---- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index aea3d6568a9..5e0065f61b7 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -74,10 +74,10 @@ message reporting that the specified value is invalid SHOULD be logged. The first _identical_ `Logger` MUST be associated with all (both identifying and non-identifying) passed parameters. -Currently, it is a user error to create `Logger`s with different -non-identifying parameter values (e.g. instrumentation scope attributes) but -the same identifying parameters. The SDK can handle such cases in its preferred -way. However, it MUST be documented that the behavior may change in future +Currently, it is a user error to create `Logger`s with different +non-identifying parameter values (e.g. instrumentation scope attributes) but +the same identifying parameters. The SDK can handle such cases in its preferred +way. However, it MUST be documented that the behavior may change in future releases, as this is currently an unsupported usage of the API. **Status**: [Development](../document-status.md) - The `LoggerProvider` MUST diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 5ed82442bcb..e9279f3bea8 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -130,10 +130,10 @@ message reporting that the specified value is invalid SHOULD be logged. The first _identical_ `Meter` MUST be associated with all (both identifying and non-identifying) passed parameters. -Currently, it is a user error to create `Meter`s with different -non-identifying parameter values (e.g. instrumentation scope attributes) but -the same identifying parameters. The SDK can handle such cases in its preferred -way. However, it MUST be documented that the behavior may change in future +Currently, it is a user error to create `Meter`s with different +non-identifying parameter values (e.g. instrumentation scope attributes) but +the same identifying parameters. The SDK can handle such cases in its preferred +way. However, it MUST be documented that the behavior may change in future releases, as this is currently an unsupported usage of the API. When a Schema URL is passed as an argument when creating a `Meter` the emitted diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 36eaf466862..21dce795f06 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -73,10 +73,10 @@ is stored on the created `Tracer`. The first _identical_ `Tracer` MUST be associated with all (both identifying and non-identifying) passed parameters. -Currently, it is a user error to create `Tracer`s with different -non-identifying parameter values (e.g. instrumentation scope attributes) but -the same identifying parameters. The SDK can handle such cases in its preferred -way. However, it MUST be documented that the behavior may change in future +Currently, it is a user error to create `Tracer`s with different +non-identifying parameter values (e.g. instrumentation scope attributes) but +the same identifying parameters. The SDK can handle such cases in its preferred +way. However, it MUST be documented that the behavior may change in future releases, as this is currently an unsupported usage of the API. **Status**: [Development](../document-status.md) - The `TracerProvider` MUST From 81ac51c6a1d75d02a1b011fc5086035d9b35e39b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Wed, 17 Jul 2024 12:21:11 +0200 Subject: [PATCH 12/15] Fix MD049/emphasis-style Emphasis style should be consistent --- specification/trace/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 21dce795f06..e6e3bd22660 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -244,7 +244,7 @@ Thus, the SDK specification defines sets of possible requirements for both the full span API as defined in the [API-level definition for span's interface](api.md#span-operations) and additionally must be able to retrieve all information that was added to the span - (as with *readable span*). + (as with _readable span_). It MUST be possible for functions being called with this to somehow obtain the same `Span` instance and type From a27c6110982f4f408cd33a1214f4e3503e85c8ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 23 Jul 2024 10:02:49 +0200 Subject: [PATCH 13/15] Apply suggestions from code review --- specification/logs/sdk.md | 4 ++-- specification/metrics/sdk.md | 4 ++-- specification/trace/sdk.md | 4 ++-- 3 files changed, 6 insertions(+), 6 deletions(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 5e0065f61b7..940e467263f 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -72,8 +72,8 @@ working `Logger` MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. -The first _identical_ `Logger` MUST be associated with all -(both identifying and non-identifying) passed parameters. +For each unique set of identifying parameters, the non-identifying +parameters MUST be associated with the `Logger` at least once. Currently, it is a user error to create `Logger`s with different non-identifying parameter values (e.g. instrumentation scope attributes) but the same identifying parameters. The SDK can handle such cases in its preferred diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index e9279f3bea8..7dc09248eb2 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -128,8 +128,8 @@ working Meter MUST be returned as a fallback rather than returning null or throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. -The first _identical_ `Meter` MUST be associated with all -(both identifying and non-identifying) passed parameters. +For each unique set of identifying parameters, the non-identifying +parameters MUST be associated with the `Meter` at least once. Currently, it is a user error to create `Meter`s with different non-identifying parameter values (e.g. instrumentation scope attributes) but the same identifying parameters. The SDK can handle such cases in its preferred diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 433ff3be979..3a9f058d625 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -71,8 +71,8 @@ The input provided by the user MUST be used to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. -The first _identical_ `Tracer` MUST be associated with all -(both identifying and non-identifying) passed parameters. +For each unique set of identifying parameters, the non-identifying +parameters MUST be associated with the `Tracer` at least once. Currently, it is a user error to create `Tracer`s with different non-identifying parameter values (e.g. instrumentation scope attributes) but the same identifying parameters. The SDK can handle such cases in its preferred From 64d9ee3690359ae99e7b928c437e31c2c9b78b46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 23 Jul 2024 10:20:46 +0200 Subject: [PATCH 14/15] Update sdk.md --- specification/logs/sdk.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 940e467263f..f781c713e40 100644 --- a/specification/logs/sdk.md +++ b/specification/logs/sdk.md @@ -73,7 +73,7 @@ throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. For each unique set of identifying parameters, the non-identifying -parameters MUST be associated with the `Logger` at least once. +parameters MUST be associated with the `Logger` at least once. Currently, it is a user error to create `Logger`s with different non-identifying parameter values (e.g. instrumentation scope attributes) but the same identifying parameters. The SDK can handle such cases in its preferred From 921abb7c7d7ed77b0332c971d0832bcc9e977987 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 23 Jul 2024 10:31:39 +0200 Subject: [PATCH 15/15] format --- specification/metrics/sdk.md | 2 +- specification/trace/sdk.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 7dc09248eb2..a079c857185 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -129,7 +129,7 @@ throwing an exception, its `name` SHOULD keep the original invalid value, and a message reporting that the specified value is invalid SHOULD be logged. For each unique set of identifying parameters, the non-identifying -parameters MUST be associated with the `Meter` at least once. +parameters MUST be associated with the `Meter` at least once. Currently, it is a user error to create `Meter`s with different non-identifying parameter values (e.g. instrumentation scope attributes) but the same identifying parameters. The SDK can handle such cases in its preferred diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 3a9f058d625..3fa25af4b78 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -72,7 +72,7 @@ an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Tracer`. For each unique set of identifying parameters, the non-identifying -parameters MUST be associated with the `Tracer` at least once. +parameters MUST be associated with the `Tracer` at least once. Currently, it is a user error to create `Tracer`s with different non-identifying parameter values (e.g. instrumentation scope attributes) but the same identifying parameters. The SDK can handle such cases in its preferred