From ee00d2e0741f35bdf43221cc9efeb1e7dad6e423 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Robert=20Paj=C4=85k?= Date: Tue, 24 Sep 2024 17:24:15 +0200 Subject: [PATCH] Define attributes equality and make all fields as identifying for Tracer, Meter, Logger, EventLogger (#4161) --- CHANGELOG.md | 10 ++++++++++ specification/common/README.md | 6 ++++++ specification/logs/bridge-api.md | 16 +++------------- specification/logs/event-api.md | 14 ++++---------- specification/metrics/api.md | 14 ++++---------- specification/metrics/sdk.md | 4 ---- specification/trace/api.md | 17 +++-------------- 7 files changed, 30 insertions(+), 51 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 867556439e4..ce635a47357 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,17 +11,24 @@ release. ### Traces +- Make all fields as identifying for Tracer. Previously attributes were omitted from being identifying. + ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) + ### Metrics - Add support for filtering attribute keys for streams via an exclude list. ([#4188](https://github.com/open-telemetry/opentelemetry-specification/pull/4188)) - Clarify that `Enabled` only applies to synchronous instruments. ([#4211](https://github.com/open-telemetry/opentelemetry-specification/pull/4211)) +- Make all fields as identifying for Meter. Previously attributes were omitted from being identifying. + ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) ### Logs - Define `Enabled` parameters for `Logger`. ([#4203](https://github.com/open-telemetry/opentelemetry-specification/pull/4203)) +- Make all fields as identifying for Logger. Previously attributes were omitted from being identifying. + ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) ### Events @@ -37,6 +44,9 @@ release. ### Common +- Define equality for attributes and collection of attributes. + ([#4161](https://github.com/open-telemetry/opentelemetry-specification/pull/4161)) + ### Supplementary Guidelines ## v1.37.0 (2024-09-13) diff --git a/specification/common/README.md b/specification/common/README.md index 9f91708e647..aed9e558262 100644 --- a/specification/common/README.md +++ b/specification/common/README.md @@ -59,6 +59,8 @@ indices that are kept in sync (e.g., two attributes `header_keys` and `header_va both containing an array of strings to represent a mapping `header_keys[i] -> header_values[i]`). +Attributes are equal when their keys and values are equal. + See [Attribute Naming](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-naming.md) for naming guidelines. See [Requirement Level](https://github.com/open-telemetry/semantic-conventions/blob/main/docs/general/attribute-requirement-level.md) for requirement levels guidelines. @@ -185,3 +187,7 @@ Some other implementations may use a streaming approach where every that individual attribute value being exported using a streaming wire protocol. In such cases the enforcement of uniqueness will likely be the responsibility of the recipient of this data. + +Collection of attributes are equal when they contain the same attributes, +irrespective of the order in which those elements appear +(unordered collection equality). diff --git a/specification/logs/bridge-api.md b/specification/logs/bridge-api.md index fd310fc09b7..0d1e80d7cd7 100644 --- a/specification/logs/bridge-api.md +++ b/specification/logs/bridge-api.md @@ -63,7 +63,7 @@ The `LoggerProvider` MUST provide the following functions: This API MUST accept the following [instrumentation scope](data-model.md#field-instrumentationscope) parameters: -* `name`: This name uniquely identifies the [instrumentation scope](../glossary.md#instrumentation-scope), +* `name`: Specifies the name of the [instrumentation scope](../glossary.md#instrumentation-scope), such as the [instrumentation library](../glossary.md#instrumentation-library) (e.g. `io.opentelemetry.contrib.mongodb`), package, module or class name. If an application or library has built-in OpenTelemetry instrumentation, both @@ -85,19 +85,9 @@ parameters: associate with emitted telemetry. This API MUST be structured to accept a variable number of attributes, including none. -`Logger`s are identified by `name`, `version`, and `schema_url` fields. When more -than one `Logger` of the same `name`, `version`, and `schema_url` is created, it -is unspecified whether or under which conditions the same or different `Logger` -instances are returned. It is a user error to create Loggers with different -`attributes` but the same identity. - 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. +parameters are equal. The term *distinct* applied to `Logger`s describes +instances where at least one parameter has a different value. ## Logger diff --git a/specification/logs/event-api.md b/specification/logs/event-api.md index 9a769f498a0..ea5c58116fe 100644 --- a/specification/logs/event-api.md +++ b/specification/logs/event-api.md @@ -98,7 +98,7 @@ The `EventLoggerProvider` MUST provide the following functions: This API MUST accept the following parameters: -* `name`: This name uniquely identifies the [instrumentation scope](../glossary.md#instrumentation-scope), +* `name`: Specifies the name of the [instrumentation scope](../glossary.md#instrumentation-scope), such as the [instrumentation library](../glossary.md#instrumentation-library) (e.g. `io.opentelemetry.contrib.mongodb`), package, module or class name. If an application or library has built-in OpenTelemetry instrumentation, both @@ -117,15 +117,9 @@ This API MUST accept the following parameters: associate with emitted telemetry. This API MUST be structured to accept a variable number of attributes, including none. -`EventLogger`s are identified by `name`, `version`, and `schema_url` fields. When more -than one `EventLogger` of the same `name`, `version`, and `schema_url` is created, it -is unspecified whether or under which conditions the same or different `EventLogger` -instances are returned. It is a user error to create `EventLogger`s with different -`attributes` but the same identity. - -The effect of associating a Schema URL with a `EventLogger` MUST be that the telemetry -emitted using the `EventLogger` will be associated with the Schema URL, provided that -the emitted data format is capable of representing such association. +The term *identical* applied to `EventLogger`s describes instances where all +parameters are equal. The term *distinct* applied to `EventLogger`s describes +instances where at least one parameter has a different value. ## EventLogger diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 28069f60fdb..22de9707d1e 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -120,7 +120,7 @@ The `MeterProvider` MUST provide the following functions: This API MUST accept the following parameters: -* `name`: This name uniquely identifies the [instrumentation +* `name`: Specifies the name of the [instrumentation scope](../glossary.md#instrumentation-scope), such as the [instrumentation library](../glossary.md#instrumentation-library) (e.g. `io.opentelemetry.contrib.mongodb`), package, @@ -149,15 +149,9 @@ This API MUST accept the following parameters: it is up to their discretion. Therefore, this API MUST be structured to accept a variable number of attributes, including none. -Meters are identified by `name`, `version`, and `schema_url` fields. When more -than one `Meter` of the same `name`, `version`, and `schema_url` is created, it -is unspecified whether or under which conditions the same or different `Meter` -instances are returned. It is a user error to create Meters with different -attributes but the same identity. - -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 term *identical* applied to Meters describes instances where all parameters +are equal. The term *distinct* applied to Meters describes instances where at +least one parameter has a different value. ## Meter diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 2b73da4df6c..f1c33c38fbb 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -128,10 +128,6 @@ 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 -that the emitted data format is capable of representing such association. - **Status**: [Development](../document-status.md) - The `MeterProvider` MUST compute the relevant [MeterConfig](#meterconfig) using the configured [MeterConfigurator](#meterconfigurator), and create diff --git a/specification/trace/api.md b/specification/trace/api.md index 564c39c10f5..aed0176c429 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -138,15 +138,9 @@ This API MUST accept the following parameters: - [since 1.13.0] `attributes` (optional): Specifies the instrumentation scope attributes to associate with emitted telemetry. -Tracers are identified by `name`, `version`, and `schema_url` fields. When more -than one `Tracer` of the same `name`, `version`, and `schema_url` is created, it -is unspecified whether or under which conditions the same or different `Tracer` -instances are returned. It is a user error to create Tracers with different -attributes but the same identity. - -The term *identical* applied to Tracers describes instances where all -identifying fields are equal. The term *distinct* applied to Tracers describes -instances where at least one identifying field has a different value. +The term *identical* applied to Tracers describes instances where all parameters +are equal. The term *distinct* applied to Tracers describes instances where at +least one parameter has a different value. Implementations MUST NOT require users to repeatedly obtain a `Tracer` again with the same identity to pick up configuration changes. This can be @@ -161,11 +155,6 @@ 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. - ## Context Interaction This section defines all operations within the Tracing API that interact with the