Introduce Schema URL in Tracer and Meter API (#1666)

This adds to the API 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
open-telemetry · May 18, 2021 · 31122cd · 31122cd
1 parent d001d5d
commit 31122cd
Show file tree

Hide file tree

Showing 5 changed files with 48 additions and 12 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -43,6 +43,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
 
@@ -52,6 +53,7 @@ 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
 

diff --git a/spec-compliance-matrix.md b/spec-compliance-matrix.md
@@ -19,6 +19,7 @@ formats is required. Implementing more than one format is optional.
 | [TracerProvider](specification/trace/api.md#tracerprovider-operations)                           |          |    |      |    |        |      |        |     |      |     |      |       |
 | Create TracerProvider                                                                            |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
 | Get a Tracer                                                                                     |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
+| Get a Tracer with schema_url                                                                     |          |    |      |    |        |      |        |     |      |     |      |       |
 | Safe for concurrent calls                                                                        |          | +  | +    | +  | +      | +    | +      | +   | +    | +   | +    | +     |
 | Shutdown (SDK only required)                                                                     |          | +  | +    | +  | +      | +    | -      |     | +    | +   | +    | +     |
 | ForceFlush (SDK only required)                                                                   |          | [-][go1606]  | +    | -  | +      | +    | -      |     | +    | -   | +    | +     |

diff --git a/specification/metrics/api.md b/specification/metrics/api.md
@@ -133,23 +133,29 @@ 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.
 
 Implementations MUST NOT require users to repeatedly obtain a `Meter` again with
-the same name+version 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 `Meter`s.
+the same name+version+schema_url 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 `Meter`s.
 
 Note: This could, for example, be implemented by storing any mutable
 configuration in the `MeterProvider` and having `Meter` implementation objects
 have a reference to the `MeterProvider` from which they were obtained. If
 configuration must be stored per-meter (such as disabling a certain meter), the
-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
+meter could, for example, do a look-up with its name+version+schema_url 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` MUST be that the telemetry
+emitted using the `Meter` will be associated with the Schema URL, provided that
+the emitted data format is capable of representing such association.
+
 ## Meter
 
 The meter is responsible for creating [Instruments](#instrument).

diff --git a/specification/trace/api.md b/specification/trace/api.md
@@ -118,22 +118,29 @@ 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.
 
 Implementations MUST NOT require users to repeatedly obtain a `Tracer` again
-with the same name+version to pick up configuration changes.
+with the same name+version+schema_url 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 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.
+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
+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` MUST be that the
+telemetry emitted using the `Tracer` will be associated with the Schema URL,
+provided that the emitted data format is capable of representing such
+association.
 
 ## Context Interaction
 

diff --git 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.