From eb0ac7312cd371555206c8e5023737c6c1388eb5 Mon Sep 17 00:00:00 2001 From: Tristan Sloughter Date: Fri, 3 Jan 2020 08:40:55 -0700 Subject: [PATCH] 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 ba1f3ec2ade..5f8d557b372 100644 --- a/specification/api-tracing.md +++ b/specification/api-tracing.md @@ -74,19 +74,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. @@ -95,16 +96,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.