From 46972afd465d24b6dd16d0ac996da6bdc14e2dc5 Mon Sep 17 00:00:00 2001 From: Tigran Najaryan <4194920+tigrannajaryan@users.noreply.github.com> Date: Tue, 15 Feb 2022 11:34:11 -0500 Subject: [PATCH] Clarify that Trace/Meter are associated with Instrumentation Scope (#2276) * 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 | 8 +++++ spec-compliance-matrix.md | 6 ++++ specification/common/attribute-naming.md | 4 +-- specification/glossary.md | 28 ++++++++++++++-- specification/metrics/api.md | 10 +++--- specification/metrics/sdk.md | 3 +- specification/trace/api.md | 32 ++++++++++--------- specification/trace/sdk.md | 21 ++++++------ specification/trace/sdk_exporters/non-otlp.md | 20 ++++++++---- 9 files changed, 92 insertions(+), 40 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 8c6a631b7b..ada57d9b75 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,8 +11,16 @@ release. ### Traces +- Introduce the concept of Instrumentation Scope to replace/extend Instrumentation + Library. The Tracer is now associated with Instrumentation Scope + ([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)). + ### Metrics +- Introduce the concept of Instrumentation Scope to replace/extend Instrumentation + Library. The Meter is now associated with Instrumentation Scope + ([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)). + ### Logs ### Resource diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md index e7ceb38b49..2539686b93 100644 --- a/spec-compliance-matrix.md +++ b/spec-compliance-matrix.md @@ -20,6 +20,7 @@ formats is required. Implementing more than one format is optional. | Create TracerProvider | | + | + | + | + | + | + | + | + | + | + | + | | Get a Tracer | | + | + | + | + | + | + | + | + | + | + | + | | Get a Tracer with schema_url | | + | + | | | | | | | + | | | +| Associate Tracer with InstrumentationScope | | | | | | | | | | | | | | Safe for concurrent calls | | + | + | + | + | + | + | + | + | + | + | + | | Shutdown (SDK only required) | | + | + | + | + | + | + | + | + | + | + | + | | ForceFlush (SDK only required) | | + | + | - | + | + | + | + | + | + | + | + | @@ -80,6 +81,7 @@ formats is required. Implementing more than one format is optional. | [SpanLimits](specification/trace/sdk.md#span-limits) | X | + | + | | + | + | + | + | | - | | + | | [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) | | | + | | + | + | + | + | + | + | | | | [Attribute Limits](specification/common/common.md#attribute-limits) | X | | + | | | | + | + | | | | | +| Fetch InstrumentationScope from ReadableSpan | | | | | | | | | | | | | ## Baggage @@ -102,6 +104,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t | `get_meter` accepts name, `version` and `schema_url`. | | + | + | | + | | | | | | - | | | When an invalid `name` is specified a working `Meter` implementation is returned as a fallback. | | + | + | | - | | | | | | - | | | The fallback `Meter` `name` property keeps its original invalid value. | X | - | - | | - | | | | | | - | | +| Associate `Meter` with `InstrumentationScope`. | | | | | | | | | | | | | | The meter provides functions to create a new `Counter`. | | + | + | | + | | | | | | + | | | The meter provides functions to create a new `AsynchronousCounter`. | | + | + | | + | | | | | | + | | | The meter provides functions to create a new `Histogram`. | | + | + | | + | | | | | | + | | @@ -155,6 +158,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t | `MeterProvider` allows a `Resource` to be specified. | | + | + | | + | | | | | | + | | | A specified `Resource` can be associated with all the produced metrics from any `Meter` from the `MeterProvider`. | | + | + | | + | | | | | | + | | | The supplied `name`, `version` and `schema_url` arguments passed to the `MeterProvider` are used to create an `InstrumentationLibrary` instance stored in the `Meter`. | | + | + | | + | | | | | | - | | +| The supplied `name`, `version` and `schema_url` arguments passed to the `MeterProvider` are used to create an `InstrumentationScope` instance stored in the `Meter`. | | | | | | | | | | | | | | Configuration is managed solely by the `MeterProvider`. | | + | + | | + | | | | | | + | | | The `MeterProvider` provides methods to update the configuration | X | - | - | | + | | | | | | + | | | The updated configuration applies to all already returned `Meter`s. | if above | - | - | | - | | | | | | + | | @@ -289,6 +293,7 @@ Note: Support for environment variables is optional. | Service name mapping | | + | + | + | + | + | + | + | + | + | + | + | | SpanKind mapping | | + | + | + | + | + | + | + | + | + | + | + | | InstrumentationLibrary mapping | | + | + | - | + | + | - | + | + | + | + | + | +| InstrumentationScope mapping | | | | | | | | | | | | | | Boolean attributes | | + | + | + | + | + | + | + | + | + | + | + | | Array attributes | | + | + | + | + | + | + | + | + | + | + | + | | Status mapping | | + | + | + | + | + | + | + | + | + | + | + | @@ -302,6 +307,7 @@ Note: Support for environment variables is optional. | Service name mapping | | + | + | | + | + | - | | | + | + | + | | Resource to Process mapping | | + | + | | + | + | - | | + | - | + | - | | InstrumentationLibrary mapping | | + | + | | + | + | - | | + | - | + | - | +| InstrumentationScope mapping | | | | | | | | | | | | | | Status mapping | | + | + | | + | + | - | | + | + | + | + | | Error Status mapping | | + | + | | + | + | - | | + | + | + | - | | Events converted to Logs | | + | + | | + | + | - | | + | - | + | + | diff --git a/specification/common/attribute-naming.md b/specification/common/attribute-naming.md index 9cd2f187b5..fecbf3b21b 100644 --- a/specification/common/attribute-naming.md +++ b/specification/common/attribute-naming.md @@ -148,8 +148,8 @@ Attribute names that start with `otel.` are reserved to be defined by OpenTelemetry specification. These are typically used to express OpenTelemetry concepts in formats that don't have a corresponding concept. -For example, the `otel.library.name` attribute is used to record the -instrumentation library name, which is an OpenTelemetry concept that is natively +For example, the `otel.scope.name` attribute is used to record the +instrumentation scope name, which is an OpenTelemetry concept that is natively represented in OTLP, but does not have an equivalent in other telemetry formats and protocols. diff --git a/specification/glossary.md b/specification/glossary.md index d0fab454b1..c530ab9987 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,34 @@ 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. + +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 name or (name,version) pair uniquely identify the logical unit of the +code that emits the telemetry. A typical approach to ensure uniqueness is to use +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 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 705aed6406..6c45505176 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -107,10 +107,12 @@ 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 - OpenTelemetry instrumentation, both [Instrumented +* `name` (required): This name SHOULD uniquely identify 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 [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 diff --git a/specification/metrics/sdk.md b/specification/metrics/sdk.md index 31fb65771f..a38cfced95 100644 --- a/specification/metrics/sdk.md +++ b/specification/metrics/sdk.md @@ -58,8 +58,7 @@ suggestions regarding how to implement this efficiently. New `Meter` instances are always created through a `MeterProvider` (see [API](./api.md#meterprovider)). The `name`, `version` (optional), and `schema_url` (optional) arguments supplied to the `MeterProvider` MUST be used -to create an -[`InstrumentationLibrary`](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md) +to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is stored on the created `Meter`. Configuration (i.e., [MetricExporters](#metricexporter), diff --git a/specification/trace/api.md b/specification/trace/api.md index 246da6b125..2339c08b2f 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 SHOULD uniquely identify 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 [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. diff --git a/specification/trace/sdk.md b/specification/trace/sdk.md index 0bd6aa3c9b..a9a0953469 100644 --- a/specification/trace/sdk.md +++ b/specification/trace/sdk.md @@ -55,10 +55,10 @@ ### Tracer Creation New `Tracer` instances are always created through a `TracerProvider` (see -[API](api.md#tracerprovider)). The `name` and `version` arguments -supplied to the `TracerProvider` must be used to create an -[`InstrumentationLibrary`][otep-83] instance which is stored on the created -`Tracer`. +[API](api.md#tracerprovider)). The `name` and `version` arguments supplied to +the `TracerProvider` must be used to create an +[`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is +stored on the created `Tracer`. Configuration (i.e., [SpanProcessors](#span-processor), [IdGenerator](#id-generators), [SpanLimits](#span-limits) and [`Sampler`](#sampling)) MUST be managed solely by @@ -117,11 +117,14 @@ Thus, the SDK specification defines sets of possible requirements for `Span`-like parameters: * **Readable span**: A function receiving this as argument MUST be able to - access all information that was added to the span, - as listed [in the API spec](api.md#span-data-members). - In particular, it MUST also be able to access - the `InstrumentationLibrary` and `Resource` information (implicitly) - associated with the span. + access all information that was added to the span, as listed + [in the API spec](api.md#span-data-members). In particular, it MUST also be + able to access the `InstrumentationScope` [since 1.10.0] and `Resource` + information (implicitly) associated with the span. For backwards compatibility + it MUST also be able to access the `InstrumentationLibrary` + [deprecated since 1.10.0] having the same name and version values as the + `InstrumentationScope`. + It must also be able to reliably determine whether the Span has ended (some languages might implement this by having an end timestamp of `null`, others might have an explicit `hasEnded` boolean). diff --git a/specification/trace/sdk_exporters/non-otlp.md b/specification/trace/sdk_exporters/non-otlp.md index 71ace57c2e..bdfc981017 100644 --- a/specification/trace/sdk_exporters/non-otlp.md +++ b/specification/trace/sdk_exporters/non-otlp.md @@ -21,15 +21,23 @@ over the generic rules defined in this document. ## Mappings -### InstrumentationLibrary +### InstrumentationScope -OpenTelemetry `InstrumentationLibrary`'s fields MUST be reported as key-value +OpenTelemetry `InstrumentationScope`'s fields MUST be reported as key-value pairs associated with the Span using the following mapping: -| OpenTelemetry InstrumentationLibrary Field | non-OTLP Key | -| ------------------- | --- | -| `InstrumentationLibrary.name`|`otel.library.name`| -| `InstrumentationLibrary.version`|`otel.library.version`| +| OpenTelemetry InstrumentationScope Field | non-OTLP Key | Notes | +| ------------------- | --- | --- | +| `InstrumentationScope.name`|`otel.scope.name`|since 1.10.0| +| `InstrumentationScope.version`|`otel.scope.version`|since 1.10.0| + +The following deprecated aliases MUST also be reported with exact same values for +backward compatibility reasons: + +| non-OTLP Key | Alias for | Notes | +| --- | --- | --- | +|`otel.library.name`|`otel.scope.name`|deprecated since 1.10.0| +|`otel.library.version`|`otel.scope.version`|deprecated since 1.10.0| ### Span Status