Skip to content

Commit

Permalink
Introduce Schema URL in Tracer and Meter API and SDK
Browse files Browse the repository at this point in the history
This adds to the API and SDK the changes proposed in OTEP 0152:
https://github.com/open-telemetry/oteps/blob/main/text/0152-telemetry-schemas.md

Corresponding changes to the proto repository are here:
open-telemetry/opentelemetry-proto#298
  • Loading branch information
tigrannajaryan committed May 11, 2021
1 parent f1a2eb4 commit efe2749
Show file tree
Hide file tree
Showing 5 changed files with 50 additions and 1 deletion.
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,6 +35,7 @@ release.

- `Get Tracer` should use an empty string if the specified `name` is null. ([#1654](https://github.com/open-telemetry/opentelemetry-specification/pull/1654))
- Clarify how to record dropped attribute count in non-OTLP formats. ([#1662](https://github.com/open-telemetry/opentelemetry-specification/pull/1662))
- Add schema_url support to `Tracer`. ([#1666](https://github.com/open-telemetry/opentelemetry-specification/pull/1666))

### Metrics

Expand All @@ -44,11 +45,16 @@ release.
- Remove the "Func" name, use "Asynchronous" and "Observable". ([#1645](https://github.com/open-telemetry/opentelemetry-specification/pull/1645))
- Add details to UpDownCounter API. ([#1665](https://github.com/open-telemetry/opentelemetry-specification/pull/1665))
- Add details to Histogram API. ([#1657](https://github.com/open-telemetry/opentelemetry-specification/pull/1657))
- Add schema_url support to `Meter`. ([#1666](https://github.com/open-telemetry/opentelemetry-specification/pull/1666))

### Logs

- Clarify "key/value pair list" vs "map" in Log Data Model. ([#1604](https://github.com/open-telemetry/opentelemetry-specification/pull/1604))

### Resource

- Add schema_url support to `Resource`. ([#1666](https://github.com/open-telemetry/opentelemetry-specification/pull/1666))

### Semantic Conventions

- Fix the inconsistent formatting of semantic convention enums. ([#1598](https://github.com/open-telemetry/opentelemetry-specification/pull/1598/))
Expand Down
5 changes: 5 additions & 0 deletions specification/metrics/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -133,6 +133,8 @@ This API MUST accept the following parameters:
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.

It is unspecified whether or under which conditions the same or different
`Meter` instances are returned from this functions.
Expand All @@ -150,6 +152,9 @@ meter could, for example, do a look-up with its name+version in a map in the
`MeterProvider`, or the `MeterProvider` could maintain a registry of all
returned `Meter`s and actively update their configuration if it changes.

The effect of associating a Schema URL with a `Meter` SHOULD be that the the
telemetry emitted using the `Meter` will be associated with the Schema URL.

## Meter

The meter is responsible for creating [Instruments](#instrument).
Expand Down
6 changes: 6 additions & 0 deletions specification/resource/sdk.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,10 @@ object. A factory method is recommended to enable support for cached objects.
Required parameters:

- [`Attributes`](../common/common.md#attributes)
- [since 1.4.0] `schema_url` (optional): Specifies the Schema URL that should be
recorded in the emitted resource. If the `schema_url` parameter is unspecified
then the emitted resource will have the Schema URL that matches the
specification version that the SDK implements.

### Merge

Expand All @@ -70,6 +74,8 @@ The resulting resource MUST have all attributes that are on any of the two input
If a key exists on both the old and updating resource, the value of the updating
resource MUST be picked (even if the updated value is empty).

The resulting resource will have the `schema_url` of the updating resource.

Required parameters:

- the old resource
Expand Down
14 changes: 13 additions & 1 deletion specification/trace/api.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,9 @@ This API MUST accept the following parameters:
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.

It is unspecified whether or under which conditions the same or different
`Tracer` instances are returned from this functions.

Expand All @@ -135,6 +137,9 @@ the tracer could, for example, do a look-up with its name+version 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.

The effect of associating a Schema URL with a `Tracer` SHOULD be that the the
telemetry emitted using the `Tracer` will be associated with the Schema URL.

## Context Interaction

This section defines all operations within the Tracing API that interact with the
Expand Down Expand Up @@ -173,6 +178,13 @@ The `Tracer` MUST provide functions to:

- [Create a new `Span`](#span-creation) (see the section on `Span`)

The `Tracer` MAY provide a function to:

- `SetSchema(schema_url)`. This is an optional method that may exist in
languages where `schema_url` cannot be passed to `Get Tracer` call.
`SetSchema` method MUST be called only once and MUST be called before any
telemetry is emitted using the `Tracer` instance.

## SpanContext

A `SpanContext` represents the portion of a `Span` which must be serialized and
Expand Down
20 changes: 20 additions & 0 deletions specification/versioning-and-stability.md
Original file line number Diff line number Diff line change
Expand Up @@ -99,6 +99,26 @@ All existing API calls MUST continue to compile and function against all future

Languages which ship binary artifacts SHOULD offer [ABI compatibility](glossary.md#abi-compatibility) for API packages.

##### Extending Existing API Calls

An existing API call MAY be extended without incrementing the major version
number if the particular language allows to do it in a backward-compatible
manner.

To add a new parameter to an existing API call depending on the language several
approaches are possible:

- Add a new optional parameter to existing methods. This may not be the right
approach for languages where ABI stability is part of our guarantees since it
likely breaks the ABI.

- Add a method overload that allows passing a different set of parameters, that
include the new parameter. This is likely the preferred approach for languages
where method overloads are possible.

There may be other ways to extend existing APIs in non-breaking manner. Language
maintainers SHOULD choose the idiomatic way for their language.

#### SDK Stability

Public portions of SDK packages MUST remain backwards compatible.
Expand Down

0 comments on commit efe2749

Please sign in to comment.