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

I will submit corresponding changes to the proto repository separately.

CHANGELOG.md

@@ -15,12 +15,14 @@ release.
 ### Traces
 
 - `Get Tracer` should use an empty string if the specified `name` is null. ([#1654](https://github.com/open-telemetry/opentelemetry-specification/pull/1654))
+- Add schema_url support to `Get Tracer`. ([#1666](https://github.com/open-telemetry/opentelemetry-specification/pull/1666))
 
 ### Metrics
 
 - Expand description of Event Model and Instruments. ([#1614](https://github.com/open-telemetry/opentelemetry-specification/pull/1614))
 - Flesh out metric identity and single-write principle. ([#1574](https://github.com/open-telemetry/opentelemetry-specification/pull/1574))
 - Expand `Sum` metric description in the data model and delta-to-cumulative handling. ([#1618](https://github.com/open-telemetry/opentelemetry-specification/pull/1618))
+- Add schema_url support to `Get Meter`. ([#1666](https://github.com/open-telemetry/opentelemetry-specification/pull/1666))
 
 ### Logs
 

specification/metrics/api.md

@@ -367,6 +367,8 @@ arguments:
   rather than returning null or throwing an exception.
   A `MeterProvider` could also return a no-op `Meter` 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.3.0] `schema_url` (optional): Specifies the Schema URL that should be
+  recorded in the emitted telemetry (`schema_url` field OTLP messages).
 
 Each distinctly named `Meter` establishes a separate namespace for its
 metric instruments, making it possible for multiple instrumentation
@@ -375,6 +377,39 @@ other libraries.  The name of the `Meter` is explicitly not intended
 to be used as part of the instrument name, as that would prevent
 instrumentation libraries from capturing metrics by the same name.
 
+Note: `schema_url` optional parameter is added since spec 1.3.0. This change in
+the spec implementations needs to be done such that we do not break the Get
+Meter API stability guarantee.
+
+Depending on the language several approaches are possible:
+
+- Add a third, optional parameter `schema_url` to existing Get Meter methods of
+  corresponding providers. 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 3 parameters (instrumentation
+  library name, version and schema url) to obtain a `Meter`.
+  This is likely the preferred approach for languages where method overloads are
+  possible.
+
+- If neither of the above 2 approaches are possible to do in non-breaking manner
+  then the API may introduce a `SetSchema(schema_url)` method to `Meter`
+  instance. The method MUST be called only once and MUST be called before any
+  telemetry is emitted using the instance.
+
+There may be other ways to modify the Get Meter API to allow the association
+with a Schema URL. Language maintainers SHOULD choose the idiomatic way for
+their language.
+
+The effect of associating a Schema URL with a `Meter` SHOULD be that the
+`schema_url` in the `InstrumentationLibraryMetrics` message for all the
+telemetry emitted with the associated `Meter` is populated with the provided
+Schema URL value (when using OTLP exporter).
+
+If the `Meter` is not associated with a Schema URL then the exporter MUST leave
+the `schema_url` field in OTLP messages unset, in which case the
+application-wide Schema URL will apply (link to SDK TBD).
+
 ### Global Meter provider
 
 Use of a global instance may be seen as an anti-pattern in many

specification/metrics/new_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.3.0] `schema_url` (optional): Specifies the Schema URL that should be
+  recorded in the emitted telemetry (`schema_url` field OTLP messages).
 
 It is unspecified whether or under which conditions the same or different
 `Meter` instances are returned from this functions.
@@ -150,6 +152,39 @@ 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.
 
+Note: `schema_url` optional parameter is added since spec 1.3.0. This change in
+the spec implementations needs to be done such that we do not break the Get
+Meter API stability guarantee.
+
+Depending on the language several approaches are possible:
+
+- Add a third, optional parameter `schema_url` to existing Get Meter methods of
+  corresponding providers. 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 3 parameters (instrumentation
+  library name, version and schema url) to obtain a `Meter`.
+  This is likely the preferred approach for languages where method overloads are
+  possible.
+
+- If neither of the above 2 approaches are possible to do in non-breaking manner
+  then the API may introduce a `SetSchema(schema_url)` method to `Meter`
+  instance. The method MUST be called only once and MUST be called before any
+  telemetry is emitted using the instance.
+
+There may be other ways to modify the Get Meter API to allow the association
+with a Schema URL. Language maintainers SHOULD choose the idiomatic way for
+their language.
+
+The effect of associating a Schema URL with a `Meter` SHOULD be that the
+`schema_url` in the `InstrumentationLibraryMetrics` message for all the
+telemetry emitted with the associated `Meter` is populated with the provided
+Schema URL value (when using OTLP exporter).
+
+If the `Meter` is not associated with a Schema URL then the exporter MUST leave
+the `schema_url` field in OTLP messages unset, in which case the
+application-wide Schema URL will apply (link to SDK TBD).
+
 ## Meter
 
 The meter is responsible for creating [Instruments](#instrument).

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.3.0] `schema_url` (optional): Specifies the Schema URL that should be
+  recorded in the emitted telemetry (`schema_url` field OTLP messages).
+
 It is unspecified whether or under which conditions the same or different
 `Tracer` instances are returned from this functions.
 
@@ -135,6 +137,39 @@ 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.
 
+Note: `schema_url` optional parameter is added since spec 1.3.0. This change in
+the spec implementations needs to be done such that we do not break the Get
+Tracer API stability guarantee.
+
+Depending on the language several approaches are possible:
+
+- Add a third, optional parameter `schema_url` to existing Get Tracer methods of
+  corresponding providers. 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 3 parameters (instrumentation
+  library name, version and schema url) to obtain a `Tracer`.
+  This is likely the preferred approach for languages where method overloads are
+  possible.
+
+- If neither of the above 2 approaches are possible to do in non-breaking manner
+  then the API may introduce a `SetSchema(schema_url)` method to `Tracer`
+  instance. The method MUST be called only once and MUST be called before any
+  telemetry is emitted using the instance.
+
+There may be other ways to modify the Get Tracer API to allow the association
+with a Schema URL. Language maintainers SHOULD choose the idiomatic way for
+their language.
+
+The effect of associating a Schema URL with a `Tracer` SHOULD be that the
+`schema_url` in the `InstrumentationLibrarySpans` message for all the telemetry
+emitted with the associated `Tracer` is populated with the provided Schema URL
+value (when using OTLP exporter).
+
+If the `Tracer` is not associated with a Schema URL then the exporter MUST leave
+the `schema_url` field in OTLP messages unset, in which case the
+application-wide Schema URL [will apply](sdk.md#application-wide-schema-url).
+
 ## Context Interaction
 
 This section defines all operations within the Tracing API that interact with the

specification/trace/sdk.md

@@ -674,3 +674,17 @@ public interface SpanExporter {
 
 [trace-flags]: https://www.w3.org/TR/trace-context/#trace-flags
 [otep-83]: https://github.com/open-telemetry/oteps/blob/main/text/0083-component.md
+
+## Application-wide Schema URL
+
+The SDK interface MUST provide a way for the user to optionally set an
+application-wide Schema URL. This Schema URL will be populated in all
+ResourceSpans messages emitted by OTLP Exporter.
+
+If the user does not set an application-wide Schema URL then the current Schema
+URL MUST be populated by OTLP Exporter in the messages, where "current" means
+the version of OpenTelemetry Schema against which the SDK is coded.
+
+Note that if there is a schema url associated with instrumentation library it
+overrides the application-wide schema url as described here (link to proto
+repo TBD).