From fc491f32836035c49360589d89b9033f60e16baa Mon Sep 17 00:00:00 2001 From: Tigran Najaryan Date: Fri, 7 May 2021 11:26:30 -0400 Subject: [PATCH] Introduce Schema URL in Tracer and Meter API and SDK 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: https://github.com/open-telemetry/opentelemetry-proto/pull/298 --- CHANGELOG.md | 6 ++++++ specification/metrics/api.md | 5 +++++ specification/resource/sdk.md | 6 ++++++ specification/trace/api.md | 14 +++++++++++++- specification/versioning-and-stability.md | 20 ++++++++++++++++++++ 5 files changed, 50 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cc07f514d57..a8d28509821 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -33,6 +33,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 @@ -42,11 +43,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/)) diff --git a/specification/metrics/api.md b/specification/metrics/api.md index 04414636671..a9b34ac08b0 100644 --- a/specification/metrics/api.md +++ b/specification/metrics/api.md @@ -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. @@ -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). diff --git a/specification/resource/sdk.md b/specification/resource/sdk.md index b74e4b6fe97..ad28187672c 100644 --- a/specification/resource/sdk.md +++ b/specification/resource/sdk.md @@ -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 @@ -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 diff --git a/specification/trace/api.md b/specification/trace/api.md index 942f808956f..cc56b7692e8 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -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. @@ -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 @@ -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 diff --git a/specification/versioning-and-stability.md b/specification/versioning-and-stability.md index 6b0ae2218d4..043eb0b5506 100644 --- a/specification/versioning-and-stability.md +++ b/specification/versioning-and-stability.md @@ -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.