Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Introduce Instrumentation Scope Attributes #2579

Merged
merged 9 commits into from
Jun 11, 2022
Merged

Introduce Instrumentation Scope Attributes #2579

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
c9b44ad
Introduce Instrumentation Scope Attributes
tigrannajaryan May 24, 2022
9653473
Add appropriate lines to the compliance matrix
tigrannajaryan May 24, 2022
47001c9
Reword uniqueness paragraph
tigrannajaryan May 25, 2022
2b65a3e
Fix typo
tigrannajaryan May 30, 2022
f7be792
Fix notes about Tracer/Meter identification
tigrannajaryan May 31, 2022
be5b25d
Fixes based on review comments
tigrannajaryan Jun 6, 2022
526bdcf
Make behavior with simultaneous scope and span attrs unspecified
tigrannajaryan Jun 6, 2022
9a8b91c
Update the text to say "since 1.13.0"
tigrannajaryan Jun 7, 2022
8e344d0
Merge branch 'main' into feature/tigran/scope-attr
reyang Jun 11, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,9 @@ release.

### Common

- Introduce Instrumentation Scope Attributes
([#2579](https://github.com/open-telemetry/opentelemetry-specification/pull/2579))

## v1.12.0 (2022-06-10)

### Context
Expand Down
3 changes: 3 additions & 0 deletions spec-compliance-matrix.md
View file
Open in desktop
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 | | + | + | | | | | + | | + | | |
| Get a Tracer with scope attributes | | | | | | | | | | | | |
| Associate Tracer with InstrumentationScope | | | | | | | | + | | | | |
| Safe for concurrent calls | | + | + | + | + | + | + | + | + | + | + | + |
| Shutdown (SDK only required) | | + | + | + | + | + | + | + | + | + | + | + |
Expand Down Expand Up @@ -99,6 +100,7 @@ formats is required. Implementing more than one format is optional.
| It is possible to create any number of `MeterProvider`s. | X | + | + | | + | | | | | | + | |
| `MeterProvider` provides a way to get a `Meter`. | | + | + | | + | | | | | + | - | |
| `get_meter` accepts name, `version` and `schema_url`. | | + | + | | + | | | | | + | - | |
| `get_meter` accepts `attributes`. | | | | | | | | | | | | |
| 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`. | | | + | | | | | | | | | |
Expand Down Expand Up @@ -212,6 +214,7 @@ Disclaimer: this list of features is still a work in progress, please refer to t
|--------------------------------------------------------------|----------|-----|------|-----|--------|------|--------|-----|------|-----|------|-------|
| **[Logging SDK](specification/logs/logging-library-sdk.md)** | Optional | Go | Java | JS | Python | Ruby | Erlang | PHP | Rust | C++ | .NET | Swift |
| LogEmitterProvider.Get LogEmitter | | | + | | + | | | | | | - | |
| LogEmitterProvider.Get LogEmitter accepts attributes | | | | | | | | | | | | |
| LogEmitterProvider.Shutdown | | | + | | + | | | | | | - | |
| LogEmitterProvider.ForceFlush | | | + | | + | | | | | | - | |
| LogEmitter.Emit(LogRecord) | | | + | | + | | | | | | - | |
Expand Down
6 changes: 6 additions & 0 deletions specification/common/mapping-to-non-otlp.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -74,3 +74,9 @@ OpenTelemetry Span's dropped links count MUST be reported as a key-value pair
associated with the Span. The key name MUST be `otel.dropped_links_count`.

This key-value pair should only be recorded when it contains a non-zero value.

### Instrumentation Scope Attributes

Exporters to formats that don't have a concept that is equivalent to the Scope
SHOULD record the attributes at the most suitable place in their corresponding format,
typically at the Span, Metric or LogRecord equivalent.
25 changes: 21 additions & 4 deletions specification/logs/logging-library-sdk.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,27 @@ Logging Library SDK contains the following components:

Methods:

- Get LogEmitter. Accepts the instrumentation scope name and version and returns
a LogEmitter associated with the instrumentation scope.
- Shutdown.
- ForceFlush.
#### Get LogEmitter

Accepts the following parameters: instrumentation scope name, optional version and
tigrannajaryan marked this conversation as resolved.
Show resolved Hide resolved
attributes. Returns a LogEmitter associated with the parameters.

Implementations MUST return different `LogEmitter` instances when called repeatedly
with different values of parameters. Note that always returning a new `LogEmitter` instance
is a valid implementation. The only exception to this rule is the no-op `LogEmitter`:
implementations MAY return the same instance regardless of parameter values.

It is unspecified whether or under which conditions the same or different
`LogEmitter` instances are returned from this functions when the same
(name,version,attributes) parameters are used.

#### Shutdown

TBD

#### ForceFlush

TBD

LogEmitterProvider can be configured at startup time, to be associated with a
Resource and with LogProcessor/LogExporter pipeline.
Expand Down
21 changes: 15 additions & 6 deletions specification/metrics/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -140,13 +140,22 @@ This API MUST accept the following parameters:
has a version (e.g. a library version). Example value: `1.0.0`.
* [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be
recorded in the emitted telemetry.
* [since 1.13.0] `attributes` (optional): Specifies the instrumentation scope attributes
to associate with emitted telemetry.

Meters are identified by all of these fields. When more than one
Meter of the same `name`, `version`, and `schema_url` is created, it
is unspecified whether or under which conditions the same or different
`Meter` instances are returned. The term *identical* applied to
Meters describes instances where all identifying fields are equal.
The term *distinct* applied to Meters describes instances where at
Meters are identified by all of these parameters.

Implementations MUST return different `Meter` instances when called repeatedly
with different values of parameters. Note that always returning a new `Meter` instance
is a valid implementation. The only exception to this rule is the no-op `Meter`:
implementations MAY return the same instance regardless of parameter values.

It is unspecified whether or under which conditions the same or different
`Meter` instances are returned from this function when the same
(name,version,schema_url,attributes) parameters are used.

The term *identical* applied to Meters describes instances where all identifying fields
are equal. The term *distinct* applied to Meters describes instances where at
least one identifying field has a different value.

Implementations MUST NOT require users to repeatedly obtain a `Meter` with
Expand Down
12 changes: 8 additions & 4 deletions specification/trace/api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -128,20 +128,24 @@ This API MUST accept the following parameters:
has a version (e.g. a library version). Example value: `1.0.0`.
- [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be
recorded in the emitted telemetry.
- [since 1.13.0] `attributes` (optional): Specifies the instrumentation scope attributes
reyang marked this conversation as resolved.
Show resolved Hide resolved
to associate with emitted telemetry.

It is unspecified whether or under which conditions the same or different
`Tracer` instances are returned from this functions.
Implementations MUST return different `Tracer` instances when called repeatedly
with different values of parameters. Note that always returning a new `Tracer` instance
is a valid implementation. The only exception to this rule is the no-op `Tracer`:
implementations MAY return the same instance regardless of parameter values.

Implementations MUST NOT require users to repeatedly obtain a `Tracer` again
with the same name+version+schema_url to pick up configuration changes.
with the same name+version+schema_url+attributes to pick up configuration changes.
This can be achieved either by allowing to work with an outdated configuration or
by ensuring that new configuration applies also to previously returned `Tracer`s.

Note: This could, for example, be implemented by storing any mutable
configuration in the `TracerProvider` and having `Tracer` implementation objects
have a reference to the `TracerProvider` from which they were obtained. If
configuration must be stored per-tracer (such as disabling a certain tracer),
the tracer could, for example, do a look-up with its name+version+schema_url in
the tracer could, for example, do a look-up with its name+version+schema_url+attributes in
a map in the `TracerProvider`, or the `TracerProvider` could maintain a registry
of all returned `Tracer`s and actively update their configuration if it changes.

Expand Down