diff --git a/CHANGELOG.md b/CHANGELOG.md index eae6f5a..223b2a5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -95,6 +95,8 @@ release. - Introduce Instrumentation Scope Attributes ([#2579](https://github.com/open-telemetry/opentelemetry-specification/pull/2579)) + - Define Instrumentation Scope Attributes as non identifiers + ([#2789](https://github.com/open-telemetry/opentelemetry-specification/pull/2789)) ## v1.12.0 (2022-06-10) diff --git a/specification/logs/api.md b/specification/logs/api.md index df08edc..a3cde59 100644 --- a/specification/logs/api.md +++ b/specification/logs/api.md @@ -99,11 +99,15 @@ SHOULD be true by default. - `attributes` (optional): Specifies the instrumentation scope attributes to associate with emitted telemetry. -Implementations MUST return different `Logger` instances when called repeatedly -with different values of parameters. Note that always returning a new `Logger` -instance is a valid implementation. The only exception to this rule is the no-op -`Logger`: implementations MAY return the same instance regardless of parameter -values. +Loggers 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 Loggers describes instances where all +identifying fields are equal. The term *distinct* applied to Loggers describes +instances where at least one identifying field has a different value. Implementations MUST NOT require users to repeatedly obtain a Logger again with the same name+version+schema_url+event_domain+include_trace_context+attributes diff --git a/specification/metrics/api.md b/specification/metrics/api.md index af32b8f..fb79119 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -147,20 +147,15 @@ This API MUST accept the following parameters: * [since 1.13.0] `attributes` (optional): Specifies the instrumentation scope attributes to associate with emitted telemetry. -Meters are identified by all of these parameters. - -Implementations MUST return different `Meter` instances when called repeatedly -with different values of parameters. Note that always returning a new `Meter` instance -is a valid implementation. The only exception to this rule is the no-op `Meter`: -implementations MAY return the same instance regardless of parameter values. - -It is unspecified whether or under which conditions the same or different -`Meter` instances are returned from this function when the same -(name,version,schema_url,attributes) parameters are used. - -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. +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. Implementations MUST NOT require users to repeatedly obtain a `Meter` with the same identity to pick up configuration changes. This can be diff --git a/specification/trace/api.md b/specification/trace/api.md index 6ef8795..1688daf 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -131,23 +131,28 @@ This API MUST accept the following parameters: - [since 1.13.0] `attributes` (optional): Specifies the instrumentation scope attributes to associate with emitted telemetry. -Implementations MUST return different `Tracer` instances when called repeatedly -with different values of parameters. Note that always returning a new `Tracer` instance -is a valid implementation. The only exception to this rule is the no-op `Tracer`: -implementations MAY return the same instance regardless of parameter values. +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. Implementations MUST NOT require users to repeatedly obtain a `Tracer` again -with the same name+version+schema_url+attributes to pick up configuration changes. -This can be achieved either by allowing to work with an outdated configuration or -by ensuring that new configuration applies also to previously returned `Tracer`s. +with the same identity to pick up configuration changes. This can be +achieved either by allowing to work with an outdated configuration or by +ensuring that new configuration applies also to previously returned `Tracer`s. Note: This could, for example, be implemented by storing any mutable configuration in the `TracerProvider` and having `Tracer` implementation objects have a reference to the `TracerProvider` from which they were obtained. If configuration must be stored per-tracer (such as disabling a certain tracer), -the tracer could, for example, do a look-up with its name+version+schema_url+attributes 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 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,