From 7fe881fab34cc737a9fb7d490c86fe1c5d6fc5a4 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Wed, 19 Jan 2022 17:30:36 -0500 Subject: [PATCH] Clarify that Trace/Meter are associated with Instrumentation Scope This is a slightly different take on https://github.com/open-telemetry/opentelemetry-specification/issues/2203 Instead of renaming instrumentation library to instrumentation scope everywhere this PR suggests targetted editing of wording of the Trace/Meter obtaining API to allow not just instrumentation library but other instrumentation scopes to be used as a parameter. This change does not force renaming of API parameters and is not a breaking change. We consider it a clarification of usage to match the intent that we had for the "name" field. If this PR is accepted there will be a follow up PR that will suggest to rename InstrumentationLibrary* messages in OTLP proto to InstrumentationScope* message. Such a change will not be a breaking change for the OTLP wire format and is acceptable. If this PR is accepted we will also close https://github.com/open-telemetry/opentelemetry-specification/pull/1236 since it will be no longer necessary. The logger name will be recorded as the instrumentation scope. This clarification will be a follow up PR that clarifies the behavior in https://github.com/open-telemetry/oteps/blob/main/text/logs/0150-logging-library-sdk.md --- CHANGELOG.md | 4 ++++ specification/glossary.md | 25 +++++++++++++++++++++++-- specification/metrics/api.md | 5 +++-- specification/trace/api.md | 32 +++++++++++++++++--------------- 4 files changed, 47 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 821833cb3ba..a1b3eff8ce6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -17,6 +17,8 @@ release. - Add support for probability sampling in the OpenTelemetry `tracestate` entry and add optional specification for consistent probability sampling. ([#2047](https://github.com/open-telemetry/opentelemetry-specification/pull/2047)) +- Clarify that Tracer is associated with Instrumentation Scope + ([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)). ### Metrics @@ -41,6 +43,8 @@ release. [#2032](https://github.com/open-telemetry/opentelemetry-specification/pull/2061) - Changed default Prometheus Exporter host from `0.0.0.0` to `localhost`. ([#2282](https://github.com/open-telemetry/opentelemetry-specification/pull/2282)) +- Clarify that Meter is associated with Instrumentation Scope + ([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)). ### Logs diff --git a/specification/glossary.md b/specification/glossary.md index d0fab454b15..eae76171929 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -27,6 +27,7 @@ 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](#tracer-name--meter-name) * [Execution Unit](#execution-unit) - [Logs](#logs) @@ -151,11 +152,31 @@ 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 with. 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. + +If the unit of code has a version then the instrumentation scope is defined by +the (name,version) pair otherwise the version is omitted and only the name is +used. + +The instrumentation scope is used to obtain a +[Tracer or Meter](#tracer-name--meter-name). + ### Tracer Name / Meter 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)). -The name/version pair identifies the [Instrumentation Library](#instrumentation-library). +creating a new `Tracer` or `Meter` (see +[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider)). +The name/version pair identifies the +[Instrumentation Scope](#instrumentation-scope), for example the +[Instrumentation Library](#instrumentation-library) or another unit of +application in the scope of which the telemetry is emitted. ### Execution Unit diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 705aed6406e..898bcdb329c 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -108,8 +108,9 @@ The `MeterProvider` MUST provide the following functions: This API MUST accept the following parameters: * `name` (required): This name must identify the [instrumentation - library](../overview.md#instrumentation-libraries) (e.g. - `io.opentelemetry.contrib.mongodb`). If an application or library has built-in + scope](../glossary.md#instrumentation-scope) (e.g. + `io.opentelemetry.contrib.mongodb`), such as the instrumentation library, + package, module or class name. If an application or library has built-in OpenTelemetry instrumentation, both [Instrumented library](../glossary.md#instrumented-library) and [Instrumentation library](../glossary.md#instrumentation-library) may refer to the same diff --git a/specification/trace/api.md b/specification/trace/api.md index 246da6b125d..7a1866527ae 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -106,22 +106,24 @@ The `TracerProvider` MUST provide the following functions: This API MUST accept the following parameters: -- `name` (required): This name must identify the [instrumentation library](../overview.md#instrumentation-libraries) - (e.g. `io.opentelemetry.contrib.mongodb`). - If an application or library has built-in OpenTelemetry instrumentation, both +- `name` (required): This name must identify the [instrumentation + scope](../glossary.md#instrumentation-scope) (e.g. + `io.opentelemetry.contrib.mongodb`), such as the instrumentation library, + package, module or class name. If an application or library has built-in + OpenTelemetry instrumentation, both [Instrumented library](../glossary.md#instrumented-library) and - [Instrumentation library](../glossary.md#instrumentation-library) may refer to the same library. - In that scenario, the `name` denotes a module name or component name within that library - or application. - In case an invalid name (null or empty string) is specified, a working - Tracer implementation MUST be returned as a fallback rather than returning - null or throwing an exception, its `name` property SHOULD be set to an **empty** string, - and a message reporting that the specified value is invalid SHOULD be logged. - A library, implementing the OpenTelemetry API *may* also ignore this name and - return a default instance for all calls, if it does not support "named" - functionality (e.g. an implementation which is not even observability-related). - A TracerProvider could also return a no-op Tracer here if application owners configure - the SDK to suppress telemetry produced by this library. + [Instrumentation library](../glossary.md#instrumentation-library) may refer to + the same library. In that scenario, the `name` denotes a module name or + component name within that library or application. In case an invalid name + (null or empty string) is specified, a working Tracer implementation MUST be + returned as a fallback rather than returning null or throwing an exception, + its `name` property SHOULD be set to an **empty** string, and a message + reporting that the specified value is invalid SHOULD be logged. A library, + implementing the OpenTelemetry API *may* also ignore this name and return a + default instance for all calls, if it does not support "named" functionality + (e.g. an implementation which is not even observability-related). A + TracerProvider could also return a no-op Tracer here if application owners + configure the SDK to suppress telemetry produced by this library. - `version` (optional): Specifies the version of the instrumentation library (e.g. `1.0.0`). - [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be recorded in the emitted telemetry.