diff --git a/CHANGELOG.md b/CHANGELOG.md index 45a5efb9b52..5cb6cba41d2 100644 --- a/CHANGELOG.md +++ b/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 diff --git a/specification/common/README.md b/specification/common/README.md index 93fb345ab99..4b95d8b8508 100644 --- a/specification/common/README.md +++ b/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 diff --git a/specification/common/instrumentation-scope.md b/specification/common/instrumentation-scope.md new file mode 100644 index 00000000000..6427e70fe73 --- /dev/null +++ b/specification/common/instrumentation-scope.md @@ -0,0 +1,52 @@ + + +# 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. diff --git a/specification/glossary.md b/specification/glossary.md index 3a59616470c..b29b6f67e35 100644 --- a/specification/glossary.md +++ b/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. diff --git a/specification/logs/api.md b/specification/logs/api.md index 06240b1b210..6bfe532b648 100644 --- a/specification/logs/api.md +++ b/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 diff --git a/specification/logs/data-model.md b/specification/logs/data-model.md index f0db90e8c41..72bdb55c7f1 100644 --- a/specification/logs/data-model.md +++ b/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. diff --git a/specification/logs/sdk.md b/specification/logs/sdk.md index 79bd3351a39..8ad3cf28fab 100644 --- a/specification/logs/sdk.md +++ b/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 diff --git a/specification/logs/supplementary-guidelines.md b/specification/logs/supplementary-guidelines.md index 67346488ad6..22bd232513a 100644 --- a/specification/logs/supplementary-guidelines.md +++ b/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). diff --git a/specification/metrics/api.md b/specification/metrics/api.md index ed29c40deb3..257be9b508e 100644 --- a/specification/metrics/api.md +++ b/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 diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 16955778346..ee4ed2fd12e 100644 --- a/specification/metrics/sdk.md +++ b/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`. diff --git a/specification/trace/api.md b/specification/trace/api.md index db047f62e83..29593591492 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -114,7 +114,7 @@ The `TracerProvider` MUST provide the following functions: This API MUST accept the following parameters: - `name` (required): This name SHOULD uniquely identify the - [instrumentation scope](../glossary.md#instrumentation-scope), such as 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 diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 9d4435369c1..eae637117a1 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -82,7 +82,7 @@ It SHOULD only be possible to create `Tracer` instances through a `TracerProvide The `TracerProvider` MUST implement the [Get a Tracer API](api.md#get-a-tracer). 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 `Tracer`. **Status**: [Development](../document-status.md) - The `TracerProvider` MUST @@ -117,7 +117,7 @@ the [TracerConfig](#tracerconfig) for a [Tracer](#tracer). The function MUST accept the following parameter: * `tracer_scope`: - The [`InstrumentationScope`](../glossary.md#instrumentation-scope) of + The [`InstrumentationScope`](../common/instrumentation-scope.md) of the `Tracer`. The function MUST return the relevant `TracerConfig`, or some signal indicating