From 79f45e65bb3d358f747ca6b92c5e83128e4b9d3d Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Thu, 14 Nov 2019 08:22:56 -0700 Subject: [PATCH 01/25] first attempt at a language neutral explanation of the Tracer API --- specification/api-tracing.md | 84 ++++++++++++++++-------------------- 1 file changed, 37 insertions(+), 47 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 85dd23b36fa..92ae1a196bd 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -73,55 +73,45 @@ A duration is the elapsed time between two events. ## Tracer -The OpenTelemetry library achieves in-process context propagation of `Span`s by -way of the `Tracer`. - -The `Tracer` is responsible for tracking the currently active `Span`, and -exposes methods for creating and activating new `Span`s. The `Tracer` is -configured with `Propagator`s which support transferring span context across -process boundaries. - -### Obtaining a Tracer - -New `Tracer` instances can be created via a `TracerFactory` and its `getTracer` -method. This method expects two string arguments: - -`TracerFactory`s are generally expected to be used as singletons. Implementations -SHOULD provide a single global default `TracerFactory`. - -Some applications may use multiple `TracerFactory` instances, e.g. to provide -different settings (e.g. `SpanProcessor`s) to each of those instances and - -in further consequence - to the `Tracer` instances created by them. - -- `name` (required): This name must identify the instrumentation library (also +A `Tracer` is the code responsible for how `Spans`s are started and ended, and +it exposes the API which [library developers](#library-developer) use when +instrumenting their code. The API MUST allow the [end user](#end-user) to +configure or specify at runtime the implementation, the default full +implementation is referred to as the SDK in this spec, which is used by all +instrumented code within the program. + +If the [end user](#end-user) does not set a `Tracer` to be used and does not +include the library which implements the `Tracer`, like the OpenTelemetry SDK, +the API must include a default minimal implementation which acts as a no-op +`Tracer`. The [library developers](#library-developer) *must* be able to depend +on the API and instrument their code without thought to whether or not the final +deployable application includes the SDK or any other implementation. + +To facilitate this, the [library developer](#library-developer) can *not* +specify a `Tracer` implementation to use. The API *must* provide a way for the +developer to access a `Tracer`, which at runtime may be the default minimal +implementation from the API, the default full implementation known as the SDK or +a third party implementation. + +However, even though the [library developer](#library-developer) cannot define +an implementation to use, they can, and should, give the `Tracer` a name and version: + +- `name` (optional): This name must identify the instrumentation library (also referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and *not* the instrumented library. - In case an invalid name (null or empty string) is specified, a working - default Tracer implementation as a fallback is returned rather than returning - null or throwing an exception. - A library, implementing the OpenTelemetry API *may* also ignore this name and - return a default instance for all calls, if it does not support "named" - functionality (e.g. an implementation which is not even observability-related). - A TracerFactory 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. `semver:1.0.0`). - -Implementations might require the user to specify configuration properties at -`TracerFactory` creation time, or rely on external configuration, e.g. when using the -provider pattern. - -#### Runtimes with multiple deployments/applications - -Runtimes that support multiple deployments or applications might need to -provide a different `TracerFactory` instance to each deployment. To support this, -the global `TracerFactory` registry may delegate calls to create new instances of -`TracerFactory` to a separate `Provider` component, and the runtime may include -its own `Provider` implementation which returns a different `TracerFactory` for -each deployment. - -`Provider` instances are registered with the API via some language-specific -mechanism, for instance the `ServiceLoader` class in Java. +- `version` (optional and only allowed if a `name` is given): Specifies the + version of the instrumentation library (e.g. `semver:1.0.0`). + +Because the `Tracer` can have a separate `name` and `version`, but shares +everything else with all other `Tracer` references used by the other libraries +within an application, the implementations can include a cache of the `Tracer`s +that have been created. + +Since whether there is a cache that acts as a registry of name's to `Tracer`s is +outside the scope of the API, the API *must* provide only one function for the +[library developer](#library-developer) to access a `Tracer`. Meaning, there +can not be `GetTracer` and `NewTracer` functions becuase the API is oblivious to +the underlying implementation. ### Tracer operations From a763ef98da23e719231972015a8b821aafe645d1 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Thu, 14 Nov 2019 13:09:44 -0700 Subject: [PATCH 02/25] add separate glossary file --- specification/api-tracing.md | 14 +++++++------- specification/glossary.md | 17 +++++++++++++++++ 2 files changed, 24 insertions(+), 7 deletions(-) create mode 100644 specification/glossary.md diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 92ae1a196bd..a191c8649e5 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -74,26 +74,26 @@ A duration is the elapsed time between two events. ## Tracer A `Tracer` is the code responsible for how `Spans`s are started and ended, and -it exposes the API which [library developers](#library-developer) use when -instrumenting their code. The API MUST allow the [end user](#end-user) to +it exposes the API which [library developers](glossary.md#library-developer) use when +instrumenting their code. The API MUST allow the [end user](glossary.md#end-user) to configure or specify at runtime the implementation, the default full implementation is referred to as the SDK in this spec, which is used by all instrumented code within the program. -If the [end user](#end-user) does not set a `Tracer` to be used and does not +If the [end user](glossary.md#end-user) does not set a `Tracer` to be used and does not include the library which implements the `Tracer`, like the OpenTelemetry SDK, the API must include a default minimal implementation which acts as a no-op -`Tracer`. The [library developers](#library-developer) *must* be able to depend +`Tracer`. The [library developers](glossary.md#library-developer) *must* be able to depend on the API and instrument their code without thought to whether or not the final deployable application includes the SDK or any other implementation. -To facilitate this, the [library developer](#library-developer) can *not* +To facilitate this, the [library developer](glossary.md#library-developer) can *not* specify a `Tracer` implementation to use. The API *must* provide a way for the developer to access a `Tracer`, which at runtime may be the default minimal implementation from the API, the default full implementation known as the SDK or a third party implementation. -However, even though the [library developer](#library-developer) cannot define +However, even though the [library developer](glossary.md#library-developer) cannot define an implementation to use, they can, and should, give the `Tracer` a name and version: - `name` (optional): This name must identify the instrumentation library (also @@ -109,7 +109,7 @@ that have been created. Since whether there is a cache that acts as a registry of name's to `Tracer`s is outside the scope of the API, the API *must* provide only one function for the -[library developer](#library-developer) to access a `Tracer`. Meaning, there +[library developer](glossary.md#library-developer) to access a `Tracer`. Meaning, there can not be `GetTracer` and `NewTracer` functions becuase the API is oblivious to the underlying implementation. diff --git a/specification/glossary.md b/specification/glossary.md new file mode 100644 index 00000000000..2a0d7389ad6 --- /dev/null +++ b/specification/glossary.md @@ -0,0 +1,17 @@ +# Glossary + +## User Definitions + +- Library Developer: This is a developer working + on code that will be used by others. They are not creating a final + deployable artifact and must only rely on the OpenTelemetry API as a + dependency of their library. +- End User: An end user is responsible for code that + becomes a deployable artifact to run with some configuration by + an operator. The end user's project may depend on third party libraries that + have been instrumented and may include its own libraries, making the end + user potentially a library developer as well. But only the end user, or + operator, may include an OpenTelemetry SDK implementation as a dependency and + configure, either through code or configuration files loaded by the program, + the `Tracer` used by all libraries within the final program. +- Operator: From 3f475fb3671313d363465fdf9f9731c7928f7127 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Thu, 14 Nov 2019 15:29:26 -0700 Subject: [PATCH 03/25] remove "span ending" from what the Tracer is responsible for --- specification/api-tracing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index a191c8649e5..70584f16a15 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -73,7 +73,7 @@ A duration is the elapsed time between two events. ## Tracer -A `Tracer` is the code responsible for how `Spans`s are started and ended, and +A `Tracer` is the code responsible for how `Spans`s are started and it exposes the API which [library developers](glossary.md#library-developer) use when instrumenting their code. The API MUST allow the [end user](glossary.md#end-user) to configure or specify at runtime the implementation, the default full From 9b208dbc5d1b4d05cc27671a12a22da54b58086b Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Thu, 14 Nov 2019 15:51:55 -0700 Subject: [PATCH 04/25] explain need for passing name/version at tracer retrieval time --- specification/api-tracing.md | 15 +++++---------- 1 file changed, 5 insertions(+), 10 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 70584f16a15..99e60a64be5 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -102,16 +102,11 @@ an implementation to use, they can, and should, give the `Tracer` a name and ver - `version` (optional and only allowed if a `name` is given): Specifies the version of the instrumentation library (e.g. `semver:1.0.0`). -Because the `Tracer` can have a separate `name` and `version`, but shares -everything else with all other `Tracer` references used by the other libraries -within an application, the implementations can include a cache of the `Tracer`s -that have been created. - -Since whether there is a cache that acts as a registry of name's to `Tracer`s is -outside the scope of the API, the API *must* provide only one function for the -[library developer](glossary.md#library-developer) to access a `Tracer`. Meaning, there -can not be `GetTracer` and `NewTracer` functions becuase the API is oblivious to -the underlying implementation. +So the API *must* offer functionality for the library developer to pass the +`name` and `version` to the implementation when retrieving the `Tracer`. The +`name` and `version` are not attributes to be added to a retreived `Tracer`, +they must be able to be passed at the time of retrieval to allow implementations +to base the returned `Tracer` on that information. ### Tracer operations From d891d8f6fa7fb581cd1af28f00f199ac852cabdc Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 15 Nov 2019 08:01:53 -0700 Subject: [PATCH 05/25] add user definitions for api and sdk developer --- specification/glossary.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/specification/glossary.md b/specification/glossary.md index 2a0d7389ad6..c4e0458f46a 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -2,6 +2,12 @@ ## User Definitions +- API Developer: A developer working on the API + library for a particular language. +- SDK Developer: A developer working on implementing + the logic either defined in the official SDK specification or a third party + implementation. The implementation must be used only through the API by a + library developer or end user. - Library Developer: This is a developer working on code that will be used by others. They are not creating a final deployable artifact and must only rely on the OpenTelemetry API as a From b1c3e166f481d11ce2b2f7c174c43fb14e4ad8cd Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 08:21:31 -0700 Subject: [PATCH 06/25] use markdown shortcut for common link target --- specification/api-tracing.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 99e60a64be5..72ef3b91e1d 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -74,26 +74,26 @@ A duration is the elapsed time between two events. ## Tracer A `Tracer` is the code responsible for how `Spans`s are started and -it exposes the API which [library developers](glossary.md#library-developer) use when -instrumenting their code. The API MUST allow the [end user](glossary.md#end-user) to +it exposes the API which [library developers][] use when +instrumenting their code. The API MUST allow the [end users][] to configure or specify at runtime the implementation, the default full implementation is referred to as the SDK in this spec, which is used by all instrumented code within the program. -If the [end user](glossary.md#end-user) does not set a `Tracer` to be used and does not +If the [end users][] does not set a `Tracer` to be used and does not include the library which implements the `Tracer`, like the OpenTelemetry SDK, the API must include a default minimal implementation which acts as a no-op -`Tracer`. The [library developers](glossary.md#library-developer) *must* be able to depend +`Tracer`. The [library developers][] *must* be able to depend on the API and instrument their code without thought to whether or not the final deployable application includes the SDK or any other implementation. -To facilitate this, the [library developer](glossary.md#library-developer) can *not* +To facilitate this, the [library developers][] can *not* specify a `Tracer` implementation to use. The API *must* provide a way for the developer to access a `Tracer`, which at runtime may be the default minimal implementation from the API, the default full implementation known as the SDK or a third party implementation. -However, even though the [library developer](glossary.md#library-developer) cannot define +However, even though the [library developers][] cannot define an implementation to use, they can, and should, give the `Tracer` a name and version: - `name` (optional): This name must identify the instrumentation library (also @@ -618,3 +618,6 @@ To summarize the interpretation of these kinds: | `PRODUCER` | | yes | | maybe | | `CONSUMER` | | yes | maybe | | | `INTERNAL` | | | | | + +[library developers]: glossary.md#library-developer +[end users]: glossary.md#end-user From be6bf16005a2a42f1f2dd092a2df49bcd8aeec68 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 08:25:48 -0700 Subject: [PATCH 07/25] add note about operator role --- specification/glossary.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index c4e0458f46a..ee6e0bd7f0e 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -20,4 +20,5 @@ operator, may include an OpenTelemetry SDK implementation as a dependency and configure, either through code or configuration files loaded by the program, the `Tracer` used by all libraries within the final program. -- Operator: +- Operator: The operator SHOULD be able to select a + different SDK implementation, overriding the one chosed by the end user. From 5a9977ec7c26464a48eeb7c8bf5666ffb2593a4e Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 08:29:13 -0700 Subject: [PATCH 08/25] replace 'end user' with 'application developer' --- specification/api-tracing.md | 35 +++++++++++++++++------------------ specification/glossary.md | 22 ++++++++++++---------- 2 files changed, 29 insertions(+), 28 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 72ef3b91e1d..821f156a1a8 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -73,19 +73,18 @@ A duration is the elapsed time between two events. ## Tracer -A `Tracer` is the code responsible for how `Spans`s are started and -it exposes the API which [library developers][] use when -instrumenting their code. The API MUST allow the [end users][] to -configure or specify at runtime the implementation, the default full -implementation is referred to as the SDK in this spec, which is used by all -instrumented code within the program. - -If the [end users][] does not set a `Tracer` to be used and does not -include the library which implements the `Tracer`, like the OpenTelemetry SDK, -the API must include a default minimal implementation which acts as a no-op -`Tracer`. The [library developers][] *must* be able to depend -on the API and instrument their code without thought to whether or not the final -deployable application includes the SDK or any other implementation. +A `Tracer` is the code responsible for how `Spans`s are started and it exposes +the API which [library developers][] use when instrumenting their code. The API +MUST allow the [application developers][] to configure or specify at runtime the +implementation, the default full implementation is referred to as the SDK in +this spec, which is used by all instrumented code within the program. + +If the [application developers][] does not set a `Tracer` to be used and does +not include the library which implements the `Tracer`, like the OpenTelemetry +SDK, the API must include a default minimal implementation which acts as a no-op +`Tracer`. The [library developers][] *must* be able to depend on the API and +instrument their code without thought to whether or not the final deployable +application includes the SDK or any other implementation. To facilitate this, the [library developers][] can *not* specify a `Tracer` implementation to use. The API *must* provide a way for the @@ -116,10 +115,10 @@ The `Tracer` MUST provide methods to: - Create a new `Span` - Make a given `Span` as active -The `Tracer` SHOULD allow end users to configure other tracing components that -control how `Span`s are passed across process boundaries, including the binary -and text format `Propagator`s used to serialize `Span`s created by the -`Tracer`. +The `Tracer` SHOULD allow application developer to configure other tracing +components that control how `Span`s are passed across process boundaries, +including the binary and text format `Propagator`s used to serialize `Span`s +created by the `Tracer`. When getting the current span, the `Tracer` MUST return a placeholder `Span` with an invalid `SpanContext` if there is no currently active `Span`. @@ -620,4 +619,4 @@ To summarize the interpretation of these kinds: | `INTERNAL` | | | | | [library developers]: glossary.md#library-developer -[end users]: glossary.md#end-user +[application developers]: glossary.md#app-developer diff --git a/specification/glossary.md b/specification/glossary.md index ee6e0bd7f0e..37b8a464f3f 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -7,18 +7,20 @@ - SDK Developer: A developer working on implementing the logic either defined in the official SDK specification or a third party implementation. The implementation must be used only through the API by a - library developer or end user. + library developer or application developer. - Library Developer: This is a developer working on code that will be used by others. They are not creating a final deployable artifact and must only rely on the OpenTelemetry API as a dependency of their library. -- End User: An end user is responsible for code that - becomes a deployable artifact to run with some configuration by - an operator. The end user's project may depend on third party libraries that - have been instrumented and may include its own libraries, making the end - user potentially a library developer as well. But only the end user, or - operator, may include an OpenTelemetry SDK implementation as a dependency and - configure, either through code or configuration files loaded by the program, - the `Tracer` used by all libraries within the final program. +- Application Developer: An application developer is + responsible for code that becomes a deployable artifact to run with some + configuration by an operator. The application developer's project may depend + on third party libraries that have been instrumented and may include its own + libraries, making the application developer potentially a library developer as + well. But only the end user, or operator, may include an OpenTelemetry SDK + implementation as a dependency and configure, either through code or + configuration files loaded by the program, the `Tracer` used by all libraries + within the final program. - Operator: The operator SHOULD be able to select a - different SDK implementation, overriding the one chosed by the end user. + different SDK implementation, overriding the one chosed by the application + developer. From 347f847fd8fb55cb9a30871f0b40e551e8f8c8e5 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 08:40:55 -0700 Subject: [PATCH 09/25] cleanup based on PR reviews --- specification/api-tracing.md | 21 +++++++++++---------- specification/glossary.md | 15 +++++++++------ 2 files changed, 20 insertions(+), 16 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 821f156a1a8..e7160970f47 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -75,19 +75,20 @@ A duration is the elapsed time between two events. A `Tracer` is the code responsible for how `Spans`s are started and it exposes the API which [library developers][] use when instrumenting their code. The API -MUST allow the [application developers][] to configure or specify at runtime the -implementation, the default full implementation is referred to as the SDK in -this spec, which is used by all instrumented code within the program. +MUST allow the [application developers][] to configure or specify the +implementation at runtime, the default full implementation is +referred to as the SDK in this spec, which is used by all instrumented code +within the program. If the [application developers][] does not set a `Tracer` to be used and does not include the library which implements the `Tracer`, like the OpenTelemetry SDK, the API must include a default minimal implementation which acts as a no-op -`Tracer`. The [library developers][] *must* be able to depend on the API and +`Tracer`. The [library developers][] MUST be able to depend on the API and instrument their code without thought to whether or not the final deployable application includes the SDK or any other implementation. -To facilitate this, the [library developers][] can *not* -specify a `Tracer` implementation to use. The API *must* provide a way for the +To facilitate this, the [library developers][] can NOT +specify a `Tracer` implementation to use. The API MUST provide a way for the developer to access a `Tracer`, which at runtime may be the default minimal implementation from the API, the default full implementation known as the SDK or a third party implementation. @@ -96,16 +97,16 @@ However, even though the [library developers][] cannot define an implementation to use, they can, and should, give the `Tracer` a name and version: - `name` (optional): This name must identify the instrumentation library (also - referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and *not* + referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and NOT the instrumented library. - `version` (optional and only allowed if a `name` is given): Specifies the version of the instrumentation library (e.g. `semver:1.0.0`). -So the API *must* offer functionality for the library developer to pass the +So the API MUST offer functionality for the library developer to pass the `name` and `version` to the implementation when retrieving the `Tracer`. The `name` and `version` are not attributes to be added to a retreived `Tracer`, -they must be able to be passed at the time of retrieval to allow implementations -to base the returned `Tracer` on that information. +they must be able to be passed at the time of retrieval to allow +implementations, in the SDKs, to base the returned `Tracer` on that information. ### Tracer operations diff --git a/specification/glossary.md b/specification/glossary.md index 37b8a464f3f..89f6907adce 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -2,22 +2,25 @@ ## User Definitions -- API Developer: A developer working on the API - library for a particular language. +- API Developer: A developer working on the + OpenTelemetry API library for a particular language. - SDK Developer: A developer working on implementing the logic either defined in the official SDK specification or a third party implementation. The implementation must be used only through the API by a library developer or application developer. - Library Developer: This is a developer working - on code that will be used by others. They are not creating a final - deployable artifact and must only rely on the OpenTelemetry API as a - dependency of their library. + on code that will be used by others. They are not creating a final deployable + artifact and must only rely on the OpenTelemetry API as a dependency of their + library. The library may have the express purpose of making another library + observable (such libraries are called "integrations") or they may develop a + library with any other purpose that has observability built in (e.g., a + database client library that creates Spans itself when making database calls). - Application Developer: An application developer is responsible for code that becomes a deployable artifact to run with some configuration by an operator. The application developer's project may depend on third party libraries that have been instrumented and may include its own libraries, making the application developer potentially a library developer as - well. But only the end user, or operator, may include an OpenTelemetry SDK + well. But only the end user, or operator, should include an OpenTelemetry SDK implementation as a dependency and configure, either through code or configuration files loaded by the program, the `Tracer` used by all libraries within the final program. From 8b92bb5a41b7f03e59722dfba4b12c94d322ecc1 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 08:47:55 -0700 Subject: [PATCH 10/25] remove required/optional from name for named tracer --- specification/api-tracing.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index e7160970f47..238e44fd0cf 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -96,10 +96,10 @@ a third party implementation. However, even though the [library developers][] cannot define an implementation to use, they can, and should, give the `Tracer` a name and version: -- `name` (optional): This name must identify the instrumentation library (also +- `name`: This name must identify the instrumentation library (also referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and NOT the instrumented library. -- `version` (optional and only allowed if a `name` is given): Specifies the +- `version` (optional): Specifies the version of the instrumentation library (e.g. `semver:1.0.0`). So the API MUST offer functionality for the library developer to pass the From 8ff3174e690fc53feea5315e13d32b4f5a3b8d0d Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 11:15:08 -0700 Subject: [PATCH 11/25] add TracerProvider to Tracer section of api-tracing --- specification/api-tracing.md | 26 ++++++++++++++------------ 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 238e44fd0cf..8039283f9c2 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -80,18 +80,20 @@ implementation at runtime, the default full implementation is referred to as the SDK in this spec, which is used by all instrumented code within the program. -If the [application developers][] does not set a `Tracer` to be used and does -not include the library which implements the `Tracer`, like the OpenTelemetry -SDK, the API must include a default minimal implementation which acts as a no-op -`Tracer`. The [library developers][] MUST be able to depend on the API and -instrument their code without thought to whether or not the final deployable -application includes the SDK or any other implementation. - -To facilitate this, the [library developers][] can NOT -specify a `Tracer` implementation to use. The API MUST provide a way for the -developer to access a `Tracer`, which at runtime may be the default minimal -implementation from the API, the default full implementation known as the SDK or -a third party implementation. +A `Tracer` is more than just the code though. Each `Tracer` has a name and a resource attached to it. The API must provide [library developers][] a way to access a `Tracer` with a specific name and attached resource. We'll call that component the `TracerProvider`, in an OOP language this would likely be a `Factory`. + +If the [application developers][] does not include a library which implements +the `TracerProvider`, like the OpenTelemetry SDK, the API must include a default +minimal implementation of a `TracerProvider` which returns a no-op `Tracer`. The +[library developers][] MUST be able to depend on the API and instrument their +code without thought to whether or not the final deployable application includes +the SDK or any other implementation. + +To facilitate this, the [library developers][] can NOT specify a +`TracerProvider` implementation to use. The API MUST provide a way for the +developer to access a `Tracer` from a `TracerProvider`, which at runtime may be +the default minimal implementation from the API, the default full implementation +known as the SDK or a third party implementation. However, even though the [library developers][] cannot define an implementation to use, they can, and should, give the `Tracer` a name and version: From b7cd992590f4f0fac836922ff6484584bf03c486 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 11:31:12 -0700 Subject: [PATCH 12/25] change method to function --- specification/api-tracing.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 8039283f9c2..c796e2f40c2 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -80,7 +80,11 @@ implementation at runtime, the default full implementation is referred to as the SDK in this spec, which is used by all instrumented code within the program. -A `Tracer` is more than just the code though. Each `Tracer` has a name and a resource attached to it. The API must provide [library developers][] a way to access a `Tracer` with a specific name and attached resource. We'll call that component the `TracerProvider`, in an OOP language this would likely be a `Factory`. +A `Tracer` is more than just the code though. Each `Tracer` has a name and a +resource attached to it. The API must provide [library developers][] a way to +access a `Tracer` with a specific name and attached resource. We'll call that +component the `TracerProvider`, in an OOP language this would likely be a +`Factory`. If the [application developers][] does not include a library which implements the `TracerProvider`, like the OpenTelemetry SDK, the API must include a default @@ -112,7 +116,7 @@ implementations, in the SDKs, to base the returned `Tracer` on that information. ### Tracer operations -The `Tracer` MUST provide methods to: +There MUST be functions associated with a `Tracer` to: - Get the currently active `Span` - Create a new `Span` @@ -133,7 +137,7 @@ explicit parent is provided or the option to create a span without a parent is selected, or the current active `Span` is invalid. The `Tracer` MUST provide a way to update its active `Span`, and MAY provide -convenience methods to manage a `Span`'s lifetime and the scope in which a +convenience functions to manage a `Span`'s lifetime and the scope in which a `Span` is active. When an active `Span` is made inactive, the previously-active `Span` SHOULD be made active. A `Span` maybe finished (i.e. have a non-null end time) but stil active. A `Span` may be active on one thread after it has been @@ -324,7 +328,7 @@ Links SHOULD preserve the order in which they're set. ### Span operations -With the exception of the method to retrieve the `Span`'s `SpanContext` and +With the exception of the function to retrieve the `Span`'s `SpanContext` and recording status, none of the below may be called after the `Span` is finished. #### Get Context @@ -439,10 +443,10 @@ It is highly discouraged to update the name of a `Span` after its creation. spans. And often, filtering logic will be implemented before the `Span` creation for performance reasons. Thus the name update may interfere with this logic. -The method name is called `UpdateName` to differentiate this method from the -regular property setter. It emphasizes that this operation signifies a -major change for a `Span` and may lead to re-calculation of sampling or -filtering decisions made previously depending on the implementation. +The name `UpdateName`, as opposed to `SetName`, is to emphasize that this +operation signifies a major change for a `Span` and may lead to re-calculation +of sampling or filtering decisions made previously depending on the +implementation. Alternatives for the name update may be late `Span` creation, when Span is started with the explicit timestamp from the past at the moment where the final From c3339a922c8d9fd296a29d40cbc1ac932d54aa17 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 12:04:35 -0700 Subject: [PATCH 13/25] merge of updates from Yuri and Daniel --- specification/api-tracing.md | 29 ++++++++++++++--------------- specification/glossary.md | 2 +- 2 files changed, 15 insertions(+), 16 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index c796e2f40c2..5a6adf07630 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -73,12 +73,11 @@ A duration is the elapsed time between two events. ## Tracer -A `Tracer` is the code responsible for how `Spans`s are started and it exposes -the API which [library developers][] use when instrumenting their code. The API -MUST allow the [application developers][] to configure or specify the -implementation at runtime, the default full implementation is -referred to as the SDK in this spec, which is used by all instrumented code -within the program. +A `Tracer` is the code responsible for starting `Spans`s and it exposes the API +which [library developers][] use when instrumenting their code. The API MUST +allow the [application developers][] to configure or specify the implementation +at runtime. The implementation is referred to as the SDK in this spec, which is +used by all instrumented code within the program. A `Tracer` is more than just the code though. Each `Tracer` has a name and a resource attached to it. The API must provide [library developers][] a way to @@ -86,18 +85,18 @@ access a `Tracer` with a specific name and attached resource. We'll call that component the `TracerProvider`, in an OOP language this would likely be a `Factory`. -If the [application developers][] does not include a library which implements +If [application developers][] do not specify a library which implements the `TracerProvider`, like the OpenTelemetry SDK, the API must include a default minimal implementation of a `TracerProvider` which returns a no-op `Tracer`. The [library developers][] MUST be able to depend on the API and instrument their code without thought to whether or not the final deployable application includes the SDK or any other implementation. -To facilitate this, the [library developers][] can NOT specify a +To facilitate this, the [library developers][] MUST NOT specify a `TracerProvider` implementation to use. The API MUST provide a way for the developer to access a `Tracer` from a `TracerProvider`, which at runtime may be the default minimal implementation from the API, the default full implementation -known as the SDK or a third party implementation. +known as the SDK, or a third party implementation. However, even though the [library developers][] cannot define an implementation to use, they can, and should, give the `Tracer` a name and version: @@ -108,11 +107,11 @@ an implementation to use, they can, and should, give the `Tracer` a name and ver - `version` (optional): Specifies the version of the instrumentation library (e.g. `semver:1.0.0`). -So the API MUST offer functionality for the library developer to pass the -`name` and `version` to the implementation when retrieving the `Tracer`. The -`name` and `version` are not attributes to be added to a retreived `Tracer`, -they must be able to be passed at the time of retrieval to allow -implementations, in the SDKs, to base the returned `Tracer` on that information. +The API MUST offer functionality for the library developer to pass the `name` +and `version` to `TracerProvider` when retrieving the `Tracer`. The `name` and +`version` are not attributes to be added to a retrieved `Tracer`, they must be +passed at the time of retrieval to allow implementations, in the SDKs, to base +the returned `Tracer` on that information. ### Tracer operations @@ -122,7 +121,7 @@ There MUST be functions associated with a `Tracer` to: - Create a new `Span` - Make a given `Span` as active -The `Tracer` SHOULD allow application developer to configure other tracing +The `Tracer` SHOULD allow the application developer to configure other tracing components that control how `Span`s are passed across process boundaries, including the binary and text format `Propagator`s used to serialize `Span`s created by the `Tracer`. diff --git a/specification/glossary.md b/specification/glossary.md index 89f6907adce..14823798707 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -22,7 +22,7 @@ libraries, making the application developer potentially a library developer as well. But only the end user, or operator, should include an OpenTelemetry SDK implementation as a dependency and configure, either through code or - configuration files loaded by the program, the `Tracer` used by all libraries + configuration files loaded by the program, the `TracerProvider` used by all libraries within the final program. - Operator: The operator SHOULD be able to select a different SDK implementation, overriding the one chosed by the application From 5c6707fbdd8d4583aa2574ad62a7081f248b09cc Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Sat, 18 Jan 2020 16:57:05 -0700 Subject: [PATCH 14/25] remove mention of tracer being used for context and propagation --- specification/api-tracing.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 5a6adf07630..24b26da8b04 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -98,8 +98,9 @@ developer to access a `Tracer` from a `TracerProvider`, which at runtime may be the default minimal implementation from the API, the default full implementation known as the SDK, or a third party implementation. -However, even though the [library developers][] cannot define -an implementation to use, they can, and should, give the `Tracer` a name and version: +### Named Tracers + +[library developers][] can, and should, give the `Tracer` a name and version: - `name`: This name must identify the instrumentation library (also referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and NOT @@ -121,11 +122,6 @@ There MUST be functions associated with a `Tracer` to: - Create a new `Span` - Make a given `Span` as active -The `Tracer` SHOULD allow the application developer to configure other tracing -components that control how `Span`s are passed across process boundaries, -including the binary and text format `Propagator`s used to serialize `Span`s -created by the `Tracer`. - When getting the current span, the `Tracer` MUST return a placeholder `Span` with an invalid `SpanContext` if there is no currently active `Span`. From 1bfbb2b5211defce28a4d1d05802f00cf9dec273 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Sat, 18 Jan 2020 16:57:10 -0700 Subject: [PATCH 15/25] reorder glossary --- specification/glossary.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/specification/glossary.md b/specification/glossary.md index 14823798707..69643bd5121 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -2,19 +2,6 @@ ## User Definitions -- API Developer: A developer working on the - OpenTelemetry API library for a particular language. -- SDK Developer: A developer working on implementing - the logic either defined in the official SDK specification or a third party - implementation. The implementation must be used only through the API by a - library developer or application developer. -- Library Developer: This is a developer working - on code that will be used by others. They are not creating a final deployable - artifact and must only rely on the OpenTelemetry API as a dependency of their - library. The library may have the express purpose of making another library - observable (such libraries are called "integrations") or they may develop a - library with any other purpose that has observability built in (e.g., a - database client library that creates Spans itself when making database calls). - Application Developer: An application developer is responsible for code that becomes a deployable artifact to run with some configuration by an operator. The application developer's project may depend @@ -24,6 +11,19 @@ implementation as a dependency and configure, either through code or configuration files loaded by the program, the `TracerProvider` used by all libraries within the final program. +- Library Developer: This is a developer working + on code that will be used by others. They are not creating a final deployable + artifact and must only rely on the OpenTelemetry API as a dependency of their + library. The library may have the express purpose of making another library + observable (such libraries are called "integrations") or they may develop a + library with any other purpose that has observability built in (e.g., a + database client library that creates Spans itself when making database calls). +- API Developer: A developer working on the + OpenTelemetry API library for a particular language. +- SDK Developer: A developer working on implementing + the logic either defined in the official SDK specification or a third party + implementation. The implementation must be used only through the API by a + library developer or application developer. - Operator: The operator SHOULD be able to select a different SDK implementation, overriding the one chosed by the application developer. From 313c3ddb6b4be6d39768b36f2de4ae22021ec57c Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Sat, 18 Jan 2020 17:04:27 -0700 Subject: [PATCH 16/25] remove mention of Factory --- specification/api-tracing.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 24b26da8b04..4f0a77250e5 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -82,8 +82,7 @@ used by all instrumented code within the program. A `Tracer` is more than just the code though. Each `Tracer` has a name and a resource attached to it. The API must provide [library developers][] a way to access a `Tracer` with a specific name and attached resource. We'll call that -component the `TracerProvider`, in an OOP language this would likely be a -`Factory`. +component the `TracerProvider`. If [application developers][] do not specify a library which implements the `TracerProvider`, like the OpenTelemetry SDK, the API must include a default From da415036826a756908cb3737906f20b1f8f546bb Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Sat, 18 Jan 2020 17:07:41 -0700 Subject: [PATCH 17/25] remove confusing sentences about not how tracers are named --- specification/api-tracing.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 4f0a77250e5..6b5b933764a 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -108,10 +108,7 @@ known as the SDK, or a third party implementation. version of the instrumentation library (e.g. `semver:1.0.0`). The API MUST offer functionality for the library developer to pass the `name` -and `version` to `TracerProvider` when retrieving the `Tracer`. The `name` and -`version` are not attributes to be added to a retrieved `Tracer`, they must be -passed at the time of retrieval to allow implementations, in the SDKs, to base -the returned `Tracer` on that information. +and `version` to `TracerProvider` when retrieving the `Tracer`. ### Tracer operations From fa2873c866b3d5f1c09ba9e718bd8fc4e3eb4d01 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Sat, 18 Jan 2020 17:17:10 -0700 Subject: [PATCH 18/25] remove operator restriction from glossary --- specification/glossary.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/specification/glossary.md b/specification/glossary.md index 69643bd5121..a12174af411 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -24,6 +24,5 @@ the logic either defined in the official SDK specification or a third party implementation. The implementation must be used only through the API by a library developer or application developer. -- Operator: The operator SHOULD be able to select a - different SDK implementation, overriding the one chosed by the application - developer. +- Operator: The person deploying and maintaining the + deployable artifact. From 82e6078b877ed254c78f46a150f2952b9b5aaaae Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Sun, 19 Jan 2020 07:56:39 -0700 Subject: [PATCH 19/25] fix table of contents --- specification/api-tracing.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 6b5b933764a..1ab9bc54424 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -12,11 +12,6 @@ Table of Contents * [Tracer](#tracer) * [Obtaining a tracer](#obtaining-a-tracer) * [Tracer operations](#tracer-operations) - * [GetCurrentSpan](#getcurrentspan) - * [WithSpan](#withspan) - * [SpanBuilder](#spanbuilder) - * [GetBinaryFormat](#getbinaryformat) - * [GetHttpTextFormat](#gethttptextformat) * [SpanContext](#spancontext) * [Span](#span) * [Span creation](#span-creation) From 06a3e1a30d681018f12326e11e28b994188a1727 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Wed, 5 Feb 2020 09:33:55 -0700 Subject: [PATCH 20/25] remove mention of Resource from named tracers --- specification/api-tracing.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 1ab9bc54424..cea44a494bc 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -74,9 +74,9 @@ allow the [application developers][] to configure or specify the implementation at runtime. The implementation is referred to as the SDK in this spec, which is used by all instrumented code within the program. -A `Tracer` is more than just the code though. Each `Tracer` has a name and a -resource attached to it. The API must provide [library developers][] a way to -access a `Tracer` with a specific name and attached resource. We'll call that +A `Tracer` is more than just the code though. Each `Tracer` has a name and +optionally a version. The API must provide [library developers][] a way to +access a `Tracer` with a specific name and version. We'll call that component the `TracerProvider`. If [application developers][] do not specify a library which implements From 6d32d43960994159115889f1b54d6cb99bd1a0c1 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 7 Feb 2020 11:56:40 -0700 Subject: [PATCH 21/25] Update specification/api-tracing.md Co-Authored-By: Tyler Yahn --- specification/api-tracing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index cea44a494bc..c0aaab9ad45 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -75,7 +75,7 @@ at runtime. The implementation is referred to as the SDK in this spec, which is used by all instrumented code within the program. A `Tracer` is more than just the code though. Each `Tracer` has a name and -optionally a version. The API must provide [library developers][] a way to +optionally a version. The API must provide [library developers][] a component to access a `Tracer` with a specific name and version. We'll call that component the `TracerProvider`. From 7e8fa47450c5949a4b5f5a89d096f0eaff640453 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 7 Feb 2020 11:57:15 -0700 Subject: [PATCH 22/25] Update specification/glossary.md Co-Authored-By: Tyler Yahn --- specification/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index a12174af411..0f143b7bfed 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -5,7 +5,7 @@ - Application Developer: An application developer is responsible for code that becomes a deployable artifact to run with some configuration by an operator. The application developer's project may depend - on third party libraries that have been instrumented and may include its own + on third party libraries that have been instrumented with OpenTelemetry and may include its own libraries, making the application developer potentially a library developer as well. But only the end user, or operator, should include an OpenTelemetry SDK implementation as a dependency and configure, either through code or From d4d1214a467ca0585607b16364216c011f45c0d2 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 7 Feb 2020 12:01:52 -0700 Subject: [PATCH 23/25] Update specification/glossary.md Co-Authored-By: Tyler Yahn --- specification/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index 0f143b7bfed..249d12773a0 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -12,7 +12,7 @@ configuration files loaded by the program, the `TracerProvider` used by all libraries within the final program. - Library Developer: This is a developer working - on code that will be used by others. They are not creating a final deployable + on code that will be integrated into other code. They are not creating a final deployable artifact and must only rely on the OpenTelemetry API as a dependency of their library. The library may have the express purpose of making another library observable (such libraries are called "integrations") or they may develop a From 2a4b7ef059b69c96a797fc1d4b178786e67232b9 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 7 Feb 2020 12:04:18 -0700 Subject: [PATCH 24/25] Update specification/glossary.md Co-Authored-By: Tyler Yahn --- specification/glossary.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/glossary.md b/specification/glossary.md index 249d12773a0..dd01b53584c 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -4,7 +4,7 @@ - Application Developer: An application developer is responsible for code that becomes a deployable artifact to run with some - configuration by an operator. The application developer's project may depend + configuration by an operator. The application developer's code may depend on third party libraries that have been instrumented with OpenTelemetry and may include its own libraries, making the application developer potentially a library developer as well. But only the end user, or operator, should include an OpenTelemetry SDK From efd80030e79b4fc01f5004cfc03e169ae4426057 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Sat, 8 Feb 2020 09:40:28 -0700 Subject: [PATCH 25/25] Update specification/api-tracing.md Co-Authored-By: Tyler Yahn --- specification/api-tracing.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/specification/api-tracing.md b/specification/api-tracing.md index c0aaab9ad45..acfa9d18751 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -80,7 +80,7 @@ access a `Tracer` with a specific name and version. We'll call that component the `TracerProvider`. If [application developers][] do not specify a library which implements -the `TracerProvider`, like the OpenTelemetry SDK, the API must include a default +the `TracerProvider`, like the OpenTelemetry SDK, the API MUST include a default minimal implementation of a `TracerProvider` which returns a no-op `Tracer`. The [library developers][] MUST be able to depend on the API and instrument their code without thought to whether or not the final deployable application includes