Named Tracers and Meters (open-telemetry#264)

* Extended spec with "Named Tracers/Meters" concept.

* Implement feedback about wording.

* Restore the "runtimes with multiple deployments paragraph"

* Update documentation about the "name" argument in Tracer/Meter creation.

* Implement PR feedback

specification/api-metrics.md

@@ -37,8 +37,22 @@ aggregation](overview.md#recording-metrics-with-predefined-aggregation).
 
 ### Meter creation
 
-TODO: follow the spec for the Tracer. See work in progress:
-https://github.com/open-telemetry/opentelemetry-specification/issues/39
+New `Meter` instances can be created via a `MeterFactory` and its `getMeter`
+method. This method expects two string arguments:
+
+- `name` (required): 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 Meter 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 MeterFactory could also return a no-op Meter 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`).
 
 ### Create Metric
 

specification/api-tracing.md

@@ -81,27 +81,40 @@ 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
-
-`Tracer` object construction and registration will vary by implementation.
-`Tracer`s may be explicitly created and registered from user code, or resolved
-from linked dependencies using the provider pattern.
+### 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
+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
-`Tracer` creation time, or rely on external configuration, e.g. when using the
+`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 `Tracer` instance to each deployment. To support this,
-
-the global `Tracer` registry may delegate calls to create new `Tracer`s to a
-separate `Provider` component, and the runtime may include its own `Provider`
-implementation which returns a different `Tracer` for each deployment.
-
-`Provider`s are registered with the API via some language-specific mechanism,
-for instance the `ServiceLoader` class in Java.
+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.
 
 ### Tracer operations
 

specification/data-semantic-conventions.md

@@ -11,7 +11,7 @@ Depending on the protocol and the type of operation, additional information
 is needed to represent and analyze a span correctly in monitoring systems. It is
 also important to unify how this attribution is made in different languages.
 This way, the operator will not need to learn specifics of a language and
-telemetry collected from multi-language micro-services can still be easily
+telemetry collected from multi-language micro-service can still be easily
 correlated and cross-analyzed.
 
 ## HTTP client

specification/sdk-tracing.md

@@ -2,11 +2,21 @@
 
 <details><summary>Table of Contents</summary>
 
+* [Tracer Creation](#tracer-creation)
 * [Span Processor](#span-processor)
 * [Span Exporter](#span-exporter)
 
 </details>
 
+# Tracer Creation
+
+New `Tracer` instances are always created through a `TracerFactory` (see [API](api-tracing.md#obtaining-a-tracer)).
+The `name` and `version` arguments supplied to the `TracerFactory` must be used
+to create a `Resource` instance which is stored on the created `Tracer`.
+The readable representations of all `Span` instances created by a `Tracer` must
+provide a `getLibraryResource` method that returns this `Resource` information
+held by the `Tracer`.
+
 ## Span processor
 
 Span processor is an interface which allows hooks for span start and end method