first attempt at a language neutral explanation of the Tracer API

specification/api-tracing.md

@@ -72,55 +72,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.
-
-`Tracer`s are generally expected to be used as singletons. Implementations
-SHOULD provide a single global default `Tracer`.
-
-Some applications may require multiple `Tracer` instances, e.g. to create
-`Span`s on behalf of other applications. Implementations MAY provide a global
-registry of `Tracer`s for such applications.
-
-### Obtaining a Tracer
-
-New `Tracer` instances can be created via a `TracerFactory` and its `getTracer`
-method. This method expects two string arguments:
-
-- `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