[language-agnostic-wg] first attempt at a language neutral explanation of the Tracer API

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)
@@ -73,69 +68,51 @@ 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`.
+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.
 
-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.
+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 component to
+access a `Tracer` with a specific name and version. We'll call that
+component the `TracerProvider`.
 
-### Obtaining a Tracer
+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.
 
-New `Tracer` instances can be created via a `TracerFactory` and its `getTracer`
-method. This method expects two string arguments:
+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.
 
-`TracerFactory`s are generally expected to be used as singletons. Implementations
-SHOULD provide a single global default `TracerFactory`.
+### Named Tracers
 
-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.
+[library developers][] can, and should, give the `Tracer` a name and version:
 
-- `name` (required): This name must identify the instrumentation library (also
-  referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and *not*
+- `name`: 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): Specifies the
+  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`.
 
 ### 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`
 - 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`.
-
 When getting the current span, the `Tracer` MUST return a placeholder `Span`
 with an invalid `SpanContext` if there is no currently active `Span`.
 
@@ -146,7 +123,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
@@ -337,7 +314,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
@@ -452,10 +429,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
@@ -633,3 +610,6 @@ To summarize the interpretation of these kinds:
 | `PRODUCER` | | yes | | maybe |
 | `CONSUMER` | | yes | maybe | |
 | `INTERNAL` | | | | |
+
+[library developers]: glossary.md#library-developer
+[application developers]: glossary.md#app-developer

specification/glossary.md

@@ -0,0 +1,28 @@
+# Glossary
+
+## User Definitions
+
+- <a name="app-developer"></a>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 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
+  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.
+- <a name="library-developer"></a>Library Developer: This is a developer working
+  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
+  library with any other purpose that has observability built in (e.g., a
+  database client library that creates Spans itself when making database calls).
+- <a name="api-developer"></a>API Developer: A developer working on the
+  OpenTelemetry API library for a particular language.
+- <a name="sdk-developer"></a>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.
+- <a name="operator"></a>Operator: The person deploying and maintaining the
+  deployable artifact.