Skip to content

Commit e26bb4f

Browse files
ChengJinbaoChengJinbao
authored
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 open-telemetry/opentelemetry-specification#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 open-telemetry/opentelemetry-specification#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
1 parent de5b119 commit e26bb4f

9 files changed

Lines changed: 92 additions & 40 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,16 @@ release.
1111

1212
### Traces
1313

14+
- Introduce the concept of Instrumentation Scope to replace/extend Instrumentation
15+
Library. The Tracer is now associated with Instrumentation Scope
16+
([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)).
17+
1418
### Metrics
1519

20+
- Introduce the concept of Instrumentation Scope to replace/extend Instrumentation
21+
Library. The Meter is now associated with Instrumentation Scope
22+
([#2276](https://github.com/open-telemetry/opentelemetry-specification/pull/2276)).
23+
1624
### Logs
1725

1826
### Resource

‎spec-compliance-matrix.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ formats is required. Implementing more than one format is optional.
2020
| Create TracerProvider | | + | + | + | + | + | + | + | + | + | + | + |
2121
| Get a Tracer | | + | + | + | + | + | + | + | + | + | + | + |
2222
| Get a Tracer with schema_url | | + | + | | | | | | | + | | |
23+
| Associate Tracer with InstrumentationScope | | | | | | | | | | | | |
2324
| Safe for concurrent calls | | + | + | + | + | + | + | + | + | + | + | + |
2425
| Shutdown (SDK only required) | | + | + | + | + | + | + | + | + | + | + | + |
2526
| ForceFlush (SDK only required) | | + | + | - | + | + | + | + | + | + | + | + |
@@ -80,6 +81,7 @@ formats is required. Implementing more than one format is optional.
8081
| [SpanLimits](specification/trace/sdk.md#span-limits) | X | + | + | | + | + | + | + | | - | | + |
8182
| [Built-in `SpanProcessor`s implement `ForceFlush` spec](specification/trace/sdk.md#forceflush-1) | | | + | | + | + | + | + | + | + | | |
8283
| [Attribute Limits](specification/common/common.md#attribute-limits) | X | | + | | | | + | + | | | | |
84+
| Fetch InstrumentationScope from ReadableSpan | | | | | | | | | | | | |
8385

8486
## Baggage
8587

@@ -102,6 +104,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
102104
| `get_meter` accepts name, `version` and `schema_url`. | | + | + | | + | | | | | | - | |
103105
| When an invalid `name` is specified a working `Meter` implementation is returned as a fallback. | | + | + | | - | | | | | | - | |
104106
| The fallback `Meter` `name` property keeps its original invalid value. | X | - | - | | - | | | | | | - | |
107+
| Associate `Meter` with `InstrumentationScope`. | | | | | | | | | | | | |
105108
| The meter provides functions to create a new `Counter`. | | + | + | | + | | | | | | + | |
106109
| The meter provides functions to create a new `AsynchronousCounter`. | | + | + | | + | | | | | | + | |
107110
| 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
155158
| `MeterProvider` allows a `Resource` to be specified. | | + | + | | + | | | | | | + | |
156159
| A specified `Resource` can be associated with all the produced metrics from any `Meter` from the `MeterProvider`. | | + | + | | + | | | | | | + | |
157160
| The supplied `name`, `version` and `schema_url` arguments passed to the `MeterProvider` are used to create an `InstrumentationLibrary` instance stored in the `Meter`. | | + | + | | + | | | | | | - | |
161+
| The supplied `name`, `version` and `schema_url` arguments passed to the `MeterProvider` are used to create an `InstrumentationScope` instance stored in the `Meter`. | | | | | | | | | | | | |
158162
| Configuration is managed solely by the `MeterProvider`. | | + | + | | + | | | | | | + | |
159163
| The `MeterProvider` provides methods to update the configuration | X | - | - | | + | | | | | | + | |
160164
| The updated configuration applies to all already returned `Meter`s. | if above | - | - | | - | | | | | | + | |
@@ -289,6 +293,7 @@ Note: Support for environment variables is optional.
289293
| Service name mapping | | + | + | + | + | + | + | + | + | + | + | + |
290294
| SpanKind mapping | | + | + | + | + | + | + | + | + | + | + | + |
291295
| InstrumentationLibrary mapping | | + | + | - | + | + | - | + | + | + | + | + |
296+
| InstrumentationScope mapping | | | | | | | | | | | | |
292297
| Boolean attributes | | + | + | + | + | + | + | + | + | + | + | + |
293298
| Array attributes | | + | + | + | + | + | + | + | + | + | + | + |
294299
| Status mapping | | + | + | + | + | + | + | + | + | + | + | + |
@@ -302,6 +307,7 @@ Note: Support for environment variables is optional.
302307
| Service name mapping | | + | + | | + | + | - | | | + | + | + |
303308
| Resource to Process mapping | | + | + | | + | + | - | | + | - | + | - |
304309
| InstrumentationLibrary mapping | | + | + | | + | + | - | | + | - | + | - |
310+
| InstrumentationScope mapping | | | | | | | | | | | | |
305311
| Status mapping | | + | + | | + | + | - | | + | + | + | + |
306312
| Error Status mapping | | + | + | | + | + | - | | + | + | + | - |
307313
| Events converted to Logs | | + | + | | + | + | - | | + | - | + | + |

‎specification/common/attribute-naming.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -148,8 +148,8 @@ Attribute names that start with `otel.` are reserved to be defined by
148148
OpenTelemetry specification. These are typically used to express OpenTelemetry
149149
concepts in formats that don't have a corresponding concept.
150150

151-
For example, the `otel.library.name` attribute is used to record the
152-
instrumentation library name, which is an OpenTelemetry concept that is natively
151+
For example, the `otel.scope.name` attribute is used to record the
152+
instrumentation scope name, which is an OpenTelemetry concept that is natively
153153
represented in OTLP, but does not have an equivalent in other telemetry formats
154154
and protocols.
155155

‎specification/glossary.md‎

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,7 @@ Some other fundamental terms are documented in the [overview document](overview.
2727
* [Exporter Library](#exporter-library)
2828
* [Instrumented Library](#instrumented-library)
2929
* [Instrumentation Library](#instrumentation-library)
30+
* [Instrumentation Scope](#instrumentation-scope)
3031
* [Tracer Name / Meter Name](#tracer-name--meter-name)
3132
* [Execution Unit](#execution-unit)
3233
- [Logs](#logs)
@@ -151,11 +152,34 @@ Example: `io.opentelemetry.contrib.mongodb`.
151152

152153
Synonyms: *Instrumenting Library*.
153154

155+
### Instrumentation Scope
156+
157+
A logical unit of the application code with which the emitted telemetry can be
158+
associated. It is typically the developer's choice to decide what denotes a
159+
reasonable instrumentation scope. The most common approach is to use the
160+
[instrumentation library](#instrumentation-library) as the scope, however other
161+
scopes are also common, e.g. a module, a package, or a class can be chosen as
162+
the instrumentation scope.
163+
164+
If the unit of code has a version then the instrumentation scope is defined by
165+
the (name,version) pair otherwise the version is omitted and only the name is
166+
used. The name or (name,version) pair uniquely identify the logical unit of the
167+
code that emits the telemetry. A typical approach to ensure uniqueness is to use
168+
fully qualified name of the emitting code (e.g. fully qualified library name or
169+
fully qualified class name).
170+
171+
The instrumentation scope is used to obtain a
172+
[Tracer or Meter](#tracer-name--meter-name).
173+
154174
### Tracer Name / Meter Name
155175

156176
This refers to the `name` and (optional) `version` arguments specified when
157-
creating a new `Tracer` or `Meter` (see [Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider)).
158-
The name/version pair identifies the [Instrumentation Library](#instrumentation-library).
177+
creating a new `Tracer` or `Meter` (see
178+
[Obtaining a Tracer](trace/api.md#tracerprovider)/[Obtaining a Meter](metrics/api.md#meterprovider)).
179+
The name/version pair identifies the
180+
[Instrumentation Scope](#instrumentation-scope), for example the
181+
[Instrumentation Library](#instrumentation-library) or another unit of
182+
application in the scope of which the telemetry is emitted.
159183

160184
### Execution Unit
161185

‎specification/metrics/api.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -107,10 +107,12 @@ The `MeterProvider` MUST provide the following functions:
107107

108108
This API MUST accept the following parameters:
109109

110-
* `name` (required): This name must identify the [instrumentation
111-
library](../overview.md#instrumentation-libraries) (e.g.
112-
`io.opentelemetry.contrib.mongodb`). If an application or library has built-in
113-
OpenTelemetry instrumentation, both [Instrumented
110+
* `name` (required): This name SHOULD uniquely identify the [instrumentation
111+
scope](../glossary.md#instrumentation-scope), such as the
112+
[instrumentation library](../glossary.md#instrumentation-library) (e.g.
113+
`io.opentelemetry.contrib.mongodb`), package,
114+
module or class name. If an application or library has built-in OpenTelemetry
115+
instrumentation, both [Instrumented
114116
library](../glossary.md#instrumented-library) and [Instrumentation
115117
library](../glossary.md#instrumentation-library) may refer to the same
116118
library. In that scenario, the `name` denotes a module name or component name

‎specification/metrics/sdk.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -58,8 +58,7 @@ suggestions regarding how to implement this efficiently.
5858
New `Meter` instances are always created through a `MeterProvider` (see
5959
[API](./api.md#meterprovider)). The `name`, `version` (optional), and
6060
`schema_url` (optional) arguments supplied to the `MeterProvider` MUST be used
61-
to create an
62-
[`InstrumentationLibrary`](https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md)
61+
to create an [`InstrumentationScope`](../glossary.md#instrumentation-scope)
6362
instance which is stored on the created `Meter`.
6463

6564
Configuration (i.e., [MetricExporters](#metricexporter),

‎specification/trace/api.md‎

Lines changed: 17 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -106,22 +106,24 @@ The `TracerProvider` MUST provide the following functions:
106106

107107
This API MUST accept the following parameters:
108108

109-
- `name` (required): This name must identify the [instrumentation library](../overview.md#instrumentation-libraries)
110-
(e.g. `io.opentelemetry.contrib.mongodb`).
111-
If an application or library has built-in OpenTelemetry instrumentation, both
109+
- `name` (required): This name SHOULD uniquely identify the
110+
[instrumentation scope](../glossary.md#instrumentation-scope), such as the
111+
[instrumentation library](../glossary.md#instrumentation-library) (e.g.
112+
`io.opentelemetry.contrib.mongodb`), package, module or class name. If an
113+
application or library has built-in OpenTelemetry instrumentation, both
112114
[Instrumented library](../glossary.md#instrumented-library) and
113-
[Instrumentation library](../glossary.md#instrumentation-library) may refer to the same library.
114-
In that scenario, the `name` denotes a module name or component name within that library
115-
or application.
116-
In case an invalid name (null or empty string) is specified, a working
117-
Tracer implementation MUST be returned as a fallback rather than returning
118-
null or throwing an exception, its `name` property SHOULD be set to an **empty** string,
119-
and a message reporting that the specified value is invalid SHOULD be logged.
120-
A library, implementing the OpenTelemetry API *may* also ignore this name and
121-
return a default instance for all calls, if it does not support "named"
122-
functionality (e.g. an implementation which is not even observability-related).
123-
A TracerProvider could also return a no-op Tracer here if application owners configure
124-
the SDK to suppress telemetry produced by this library.
115+
[Instrumentation library](../glossary.md#instrumentation-library) may refer to
116+
the same library. In that scenario, the `name` denotes a module name or
117+
component name within that library or application. In case an invalid name
118+
(null or empty string) is specified, a working Tracer implementation MUST be
119+
returned as a fallback rather than returning null or throwing an exception,
120+
its `name` property SHOULD be set to an **empty** string, and a message
121+
reporting that the specified value is invalid SHOULD be logged. A library,
122+
implementing the OpenTelemetry API *may* also ignore this name and return a
123+
default instance for all calls, if it does not support "named" functionality
124+
(e.g. an implementation which is not even observability-related). A
125+
TracerProvider could also return a no-op Tracer here if application owners
126+
configure the SDK to suppress telemetry produced by this library.
125127
- `version` (optional): Specifies the version of the instrumentation library (e.g. `1.0.0`).
126128
- [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be
127129
recorded in the emitted telemetry.

‎specification/trace/sdk.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -55,10 +55,10 @@
5555
### Tracer Creation
5656

5757
New `Tracer` instances are always created through a `TracerProvider` (see
58-
[API](api.md#tracerprovider)). The `name` and `version` arguments
59-
supplied to the `TracerProvider` must be used to create an
60-
[`InstrumentationLibrary`][otep-83] instance which is stored on the created
61-
`Tracer`.
58+
[API](api.md#tracerprovider)). The `name` and `version` arguments supplied to
59+
the `TracerProvider` must be used to create an
60+
[`InstrumentationScope`](../glossary.md#instrumentation-scope) instance which is
61+
stored on the created `Tracer`.
6262

6363
Configuration (i.e., [SpanProcessors](#span-processor), [IdGenerator](#id-generators),
6464
[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
117117
`Span`-like parameters:
118118

119119
* **Readable span**: A function receiving this as argument MUST be able to
120-
access all information that was added to the span,
121-
as listed [in the API spec](api.md#span-data-members).
122-
In particular, it MUST also be able to access
123-
the `InstrumentationLibrary` and `Resource` information (implicitly)
124-
associated with the span.
120+
access all information that was added to the span, as listed
121+
[in the API spec](api.md#span-data-members). In particular, it MUST also be
122+
able to access the `InstrumentationScope` [since 1.10.0] and `Resource`
123+
information (implicitly) associated with the span. For backwards compatibility
124+
it MUST also be able to access the `InstrumentationLibrary`
125+
[deprecated since 1.10.0] having the same name and version values as the
126+
`InstrumentationScope`.
127+
125128
It must also be able to reliably determine whether the Span has ended
126129
(some languages might implement this by having an end timestamp of `null`,
127130
others might have an explicit `hasEnded` boolean).

‎specification/trace/sdk_exporters/non-otlp.md‎

Lines changed: 14 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,15 +21,23 @@ over the generic rules defined in this document.
2121

2222
## Mappings
2323

24-
### InstrumentationLibrary
24+
### InstrumentationScope
2525

26-
OpenTelemetry `InstrumentationLibrary`'s fields MUST be reported as key-value
26+
OpenTelemetry `InstrumentationScope`'s fields MUST be reported as key-value
2727
pairs associated with the Span using the following mapping:
2828

29-
| OpenTelemetry InstrumentationLibrary Field | non-OTLP Key |
30-
| ------------------- | --- |
31-
| `InstrumentationLibrary.name`|`otel.library.name`|
32-
| `InstrumentationLibrary.version`|`otel.library.version`|
29+
| OpenTelemetry InstrumentationScope Field | non-OTLP Key | Notes |
30+
| ------------------- | --- | --- |
31+
| `InstrumentationScope.name`|`otel.scope.name`|since 1.10.0|
32+
| `InstrumentationScope.version`|`otel.scope.version`|since 1.10.0|
33+
34+
The following deprecated aliases MUST also be reported with exact same values for
35+
backward compatibility reasons:
36+
37+
| non-OTLP Key | Alias for | Notes |
38+
| --- | --- | --- |
39+
|`otel.library.name`|`otel.scope.name`|deprecated since 1.10.0|
40+
|`otel.library.version`|`otel.scope.version`|deprecated since 1.10.0|
3341

3442
### Span Status
3543

0 commit comments

Comments
 (0)
⚡