Skip to content

Commit

Permalink
Clarify that Trace/Meter are associated with Instrumentation Scope (#…
Browse files Browse the repository at this point in the history 
…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
  • Loading branch information
@tigrannajaryan
tigrannajaryan authored Feb 15, 2022
1 parent 645397b commit 46972af
Show file tree
Hide file tree
Showing 9 changed files with 92 additions and 40 deletions.
8 changes: 8 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 6 additions & 0 deletions spec-compliance-matrix.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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) | | + | + | - | + | + | + | + | + | + | + | + |
Expand Down Expand Up @@ -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

Expand All @@ -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`. | | + | + | | + | | | | | | + | |
Expand Down Expand Up @@ -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 | - | - | | - | | | | | | + | |
Expand Down Expand Up @@ -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 | | + | + | + | + | + | + | + | + | + | + | + |
Expand All @@ -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 | | + | + | | + | + | - | | + | - | + | + |
Expand Down
4 changes: 2 additions & 2 deletions specification/common/attribute-naming.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
28 changes: 26 additions & 2 deletions specification/glossary.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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

Expand Down
10 changes: 6 additions & 4 deletions specification/metrics/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 1 addition & 2 deletions specification/metrics/sdk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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),
Expand Down
32 changes: 17 additions & 15 deletions specification/trace/api.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
21 changes: 12 additions & 9 deletions specification/trace/sdk.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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).
Expand Down
20 changes: 14 additions & 6 deletions specification/trace/sdk_exporters/non-otlp.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down

0 comments on commit 46972af

Please sign in to comment.