Have InstrumentationScope use normative language (#4488)

Fixes #4450 

Moved the `InstrumentationScope` definition from glossary into
common/instrumentation-scope.md, and massaged it using normative
language, including some examples. Also removed the compile-time concept
restriction (as clarified in the related issue, this limitation does not
exist in a few SIGs).

---------

Co-authored-by: Liudmila Molkova <limolkova@microsoft.com>
Co-authored-by: Jade Guiton <jade.guiton@datadoghq.com>
Co-authored-by: Robert Pająk <pellared@hotmail.com>
Co-authored-by: Nathan L Smith <nathan.smith@elastic.co>
Co-authored-by: Tyler Yahn <MrAlias@users.noreply.github.com>

Author: 6 people

CHANGELOG.md

@@ -38,6 +38,9 @@ release.
 
 ### Common
 
+- Move Instrumentation Scope definition from glossary to a dedicated document and use normative language.
+  ([#4488](https://github.com/open-telemetry/opentelemetry-specification/pull/4488))
+
 ### Supplementary Guidelines
 
 ### OTEPs

specification/common/README.md

@@ -158,7 +158,7 @@ at this time, as discussed in
 ## Attribute Collections
 
 [Resources](../resource/sdk.md),
-[Instrumentation Scopes](../glossary.md#instrumentation-scope),
+[Instrumentation Scopes](instrumentation-scope.md),
 [Metric points](../metrics/data-model.md#metric-points),
 [Spans](../trace/api.md#set-attributes), Span
 [Events](../trace/api.md#add-events), Span

specification/common/instrumentation-scope.md

@@ -0,0 +1,52 @@
+<!--- Hugo front matter used to generate the website version of this page:
+linkTitle: Instrumentation Scope
+--->
+
+# Instrumentation Scope
+
+**Status**: [Stable](../document-status.md)
+
+A logical unit of software with which the emitted telemetry can be
+associated. It is typically the developer's choice to decide what denotes a
+reasonable instrumentation scope. The most common approach is to use
+the name and version of the [instrumentation library](../glossary.md#instrumentation-library),
+with any additional identifying information as part of the scope's attributes.
+Other software components can be used too to get name, version and additional attributes, e.g.
+a module, a package, a class or a plugin.
+
+The instrumentation scope is defined by the
+(name,version,schema_url,attributes) tuple where version, schema_url, and
+attributes are optional. This tuple SHOULD uniquely identify the logical unit of
+software that emits the telemetry. A typical approach to ensure uniqueness is to
+use the fully qualified name of the emitting software unit (e.g. fully qualified library
+name or fully qualified class name).
+
+The instrumentation scope is used to obtain a
+[Tracer, Meter, or Logger](../glossary.md#tracer-name--meter-name--logger-name).
+
+The instrumentation scope's name SHOULD be specified to identify the `InstrumentationScope`
+name.
+
+The instrumentation scope's optional Schema URL SHOULD identify the [Telemetry
+Schema](../schemas/README.md) that the instrumentation's emitted
+telemetry conforms to.
+
+The instrumentation scope's optional attributes provide additional information about
+the scope. For example for a scope that specifies an
+instrumentation library an additional attribute may be recorded to denote the URL of the
+repository URL the library's source code is stored.
+
+## Examples
+
+Here is a non comprehensive list of usage scenarios:
+
+* Generic instrumentation library with its name, version and attributes containing
+  additional library information.
+* Database access instrumented with its own name and version (e.g. `db.system.name`).
+  This can be leveraged by APIs abstracting access to different underlying databases,
+  such as JDBC or SqlAlchemy.
+* Client consuming or producing information, using its name, version and `id` to set
+  `InstrumentationScope`.
+* Internal application components emitting their own telemetry, relying on
+  `InstrumentationScope` attributes to differentiate themselves in case multiple
+  instances of the same type exist.

specification/glossary.md

@@ -28,7 +28,6 @@ Some other fundamental terms are documented in the [overview document](overview.
   * [Exporter Library](#exporter-library)
   * [Instrumented Library](#instrumented-library)
   * [Instrumentation Library](#instrumentation-library)
-  * [Instrumentation Scope](#instrumentation-scope)
   * [Tracer Name / Meter Name / Logger Name](#tracer-name--meter-name--logger-name)
   * [Execution Unit](#execution-unit)
 - [Logs](#logs)
@@ -163,42 +162,13 @@ Example: `io.opentelemetry.contrib.mongodb`.
 
 Synonyms: *Instrumenting Library*.
 
-### Instrumentation Scope
-
-A logical unit of the application code with which the emitted telemetry can be
-associated. It is typically the developer's choice to decide what denotes a
-reasonable instrumentation scope. The most common approach is to use the
-[instrumentation library](#instrumentation-library) as the scope, however other
-scopes are also common, e.g. a module, a package, or a class can be chosen as
-the instrumentation scope.
-
-The instrumentation scope is defined by the
-(name,version,schema_url,attributes) tuple where version, schema_url, and
-attributes are optional. This tuple uniquely identifies the logical unit of the
-code that emits the telemetry. A typical approach to ensure uniqueness is to
-use the fully qualified name of the emitting code (e.g. fully qualified library
-name or fully qualified class name).
-
-The instrumentation scope is used to obtain a
-[Tracer, Meter, or Logger](#tracer-name--meter-name--logger-name).
-
-The instrumentation scope's optional Schema URL identifies the [Telemetry
-Schema](schemas/README.md) that the instrumentation's emitted
-telemetry conforms to.
-
-The instrumentation scope may have zero or more additional attributes that provide
-additional information about the scope. For example for a scope that specifies an
-instrumentation library an additional attribute may be recorded to denote the URL of the
-repository URL the library's source code is stored. Since the scope is a build-time
-concept the attributes of the scope cannot change at runtime.
-
 ### Tracer Name / Meter Name / Logger Name
 
 This refers to the `name` and (optional) `version` arguments specified when
 creating a new `Tracer` or `Meter` (see
 [Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider))/[Obtaining a Logger](logs/api.md#loggerprovider).
 The name/version pair identifies the
-[Instrumentation Scope](#instrumentation-scope), for example the
+[Instrumentation Scope](common/instrumentation-scope.md), for example the
 [Instrumentation Library](#instrumentation-library) or another unit of
 application in the scope of which the telemetry is emitted.
 

specification/logs/api.md

@@ -67,7 +67,7 @@ The `LoggerProvider` MUST provide the following functions:
 This API MUST accept the following [instrumentation scope](data-model.md#field-instrumentationscope)
 parameters:
 
-* `name`: Specifies the name of the [instrumentation scope](../glossary.md#instrumentation-scope),
+* `name`: Specifies the name of the [instrumentation scope](../common/instrumentation-scope.md),
   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

specification/logs/data-model.md

@@ -450,9 +450,9 @@ This field is optional.
 
 ### Field: `InstrumentationScope`
 
-Type: [Instrumentation Scope](../glossary.md#instrumentation-scope).
+Type: [Instrumentation Scope](../common/instrumentation-scope.md).
 
-Description: the [instrumentation scope](../glossary.md#instrumentation-scope).
+Description: the [instrumentation scope](../common/instrumentation-scope.md).
 Multiple occurrences of events coming from the same scope can happen across time and
 they all have the same value of `InstrumentationScope`. This field is optional.
 

specification/logs/sdk.md

@@ -66,7 +66,7 @@ It SHOULD only be possible to create `Logger` instances through a `LoggerProvide
 The `LoggerProvider` MUST implement the [Get a Logger API](api.md#get-a-logger).
 
 The input provided by the user MUST be used to create
-an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which
+an [`InstrumentationScope`](../common/instrumentation-scope.md) instance which
 is stored on the created `Logger`.
 
 In the case where an invalid `name` (null or empty string) is specified, a
@@ -104,7 +104,7 @@ the [LoggerConfig](#loggerconfig) for a [Logger](#logger).
 The function MUST accept the following parameter:
 
 * `logger_scope`:
-  The [`InstrumentationScope`](../glossary.md#instrumentation-scope) of
+  The [`InstrumentationScope`](../common/instrumentation-scope.md) of
   the `Logger`.
 
 The function MUST return the relevant `LoggerConfig`, or some signal indicating

specification/logs/supplementary-guidelines.md

@@ -66,7 +66,7 @@ popular logging library.
 ### Logger Name
 
 If the logging library has a concept that is similar to OpenTelemetry's
-definition of the [Instrumentation Scope's](../glossary.md#instrumentation-scope)
+definition of the [Instrumentation Scope's](../common/instrumentation-scope.md)
 name, then the appender's implementation should use that value as the
 name parameter when [obtaining the Logger](./api.md#get-a-logger).
 

specification/metrics/api.md

@@ -121,7 +121,7 @@ The `MeterProvider` MUST provide the following functions:
 This API MUST accept the following parameters:
 
 * `name`: Specifies the name of the [instrumentation
-  scope](../glossary.md#instrumentation-scope), such as the
+  scope](../common/instrumentation-scope.md), 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

specification/metrics/sdk.md

@@ -122,7 +122,7 @@ It SHOULD only be possible to create `Meter` instances through a `MeterProvider`
 The `MeterProvider` MUST implement the [Get a Meter API](api.md#get-a-meter).
 
 The input provided by the user MUST be used to create
-an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which
+an [`InstrumentationScope`](../common/instrumentation-scope.md) instance which
 is stored on the created `Meter`.
 
 In the case where an invalid `name` (null or empty string) is specified, a
@@ -161,7 +161,7 @@ the [MeterConfig](#meterconfig) for a [Meter](#meter).
 The function MUST accept the following parameter:
 
 * `meter_scope`:
-  The [`InstrumentationScope`](../glossary.md#instrumentation-scope) of
+  The [`InstrumentationScope`](../common/instrumentation-scope.md) of
   the `Meter`.
 
 The function MUST return the relevant `MeterConfig`, or some signal indicating
@@ -1717,7 +1717,7 @@ MAY return successfully collected results and a failed reasons list to the
 caller.
 
 If a batch of [Metric Points](./data-model.md#metric-points) can include
-[`InstrumentationScope`](../glossary.md#instrumentation-scope) information,
+[`InstrumentationScope`](../common/instrumentation-scope.md) information,
 `Produce` SHOULD include a single InstrumentationScope which identifies the
 `MetricProducer`.