diff --git a/CHANGELOG.md b/CHANGELOG.md index 8d80aeb58db..e0361cb287b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,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 @@ -50,6 +51,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 index ee90e5ef2aa..8e5b91b6a5c 100644 --- 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 index 04414636671..608638dd880 100644 --- 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 index 942f808956f..f46ff135504 100644 --- 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 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.