diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 9e3a5567a12..6a3eec74dd0 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -73,26 +73,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 @@ -108,7 +108,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: