From 13fae7cdbd38262ca95b4a7bfcd06329d0324877 Mon Sep 17 00:00:00 2001 From: Wolfgang Ziegler Date: Thu, 3 Oct 2019 06:22:57 +0200 Subject: [PATCH] Named Tracers and Meters (#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 | 18 ++++++++-- specification/api-tracing.md | 41 ++++++++++++++-------- specification/data-semantic-conventions.md | 2 +- specification/sdk-tracing.md | 10 ++++++ 4 files changed, 54 insertions(+), 17 deletions(-) diff --git a/specification/api-metrics.md b/specification/api-metrics.md index ae8d79bce95..da722069bd2 100644 --- a/specification/api-metrics.md +++ b/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 diff --git a/specification/api-tracing.md b/specification/api-tracing.md index 2246c3bc240..9ec6efb7e9f 100644 --- a/specification/api-tracing.md +++ b/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 diff --git a/specification/data-semantic-conventions.md b/specification/data-semantic-conventions.md index fcadf754a95..75d3b9cbe16 100644 --- a/specification/data-semantic-conventions.md +++ b/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 diff --git a/specification/sdk-tracing.md b/specification/sdk-tracing.md index 85010741505..36cae3e1450 100644 --- a/specification/sdk-tracing.md +++ b/specification/sdk-tracing.md @@ -2,11 +2,21 @@
Table of Contents +* [Tracer Creation](#tracer-creation) * [Span Processor](#span-processor) * [Span Exporter](#span-exporter)
+# 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