From 5f720d1f40788b4137665fba0a476698effe20b7 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Fri, 20 Dec 2019 07:06:14 -0500 Subject: [PATCH 01/13] Update named tracers --- text/0016-named-tracers.md | 64 ++++++++++++++++++++++++++++---------- 1 file changed, 48 insertions(+), 16 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index c0fb908a3..fe5a72a53 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -2,7 +2,7 @@ **Status:** `approved` -_Creating Tracers and Meters using a factory mechanism and naming those Tracers / Meters in accordance with the library that provides the instrumentation for those components._ +_Creating Tracers and Meters using a Registry mechanism and naming those Tracers / Meters in accordance with the library that provides the instrumentation for those components._ ## Suggested reading @@ -14,19 +14,27 @@ _Creating Tracers and Meters using a factory mechanism and naming those Tracers The mechanism of "Named Tracers and Meters" proposed here is motivated by following scenarios: -* For a consumer of OpenTelemetry instrumentation libraries, there is currently no possibility of influencing the amount of the data produced by such libraries. Instrumentation libraries can easily "spam" backend systems, deliver bogus data or - in the worst case - crash or slow down applications. These problems might even occur suddenly in production environments caused by external factors such as increasing load or unexpected input data. +**Expensive instrumentation** -* If a library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize these data selectively. The produced Spans or Metrics cannot be associated with those instrumentation libraries later. +For an operator of OpenTelemetry, there is currently no possibility of influencing the amount of the data produced by reporting libraries. Reporting libraries can easily "spam" backend systems, deliver bogus data, or - in the worst case - crash or slow down applications. These problems might even occur suddenly in production environments caused by external factors such as increasing load or unexpected input data. + +**Reporting library identification** + +If a reporting library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize these data selectively. The produced Spans or Metrics cannot be associated with the library which reported them later. + +**Conflicting instrumentation libraries** + +It is the eventual goal of OpenTelemetry that library vendors implement the OpenTelemetry API, obviating the need to auto-instrument their library. An operator should be able to disable built-in instrumentation even if the library does not provide an explicit configuration to disable instrumentation. This proposal attempts to solve the stated problems by introducing the concept of: * _Named Tracers and Meters_ identified via a **name** (e.g. _"io.opentelemetry.contrib.mongodb"_) and a **version** (e.g._"semver:1.0.0"_) which is associated with the Tracer / Meter and the Spans / Metrics it produces. - * A `TracerFactory` / `MeterFactory` as the only means of creating a Tracer or Meter. + * A `TracerRegistry` / `MeterRegistry` as the only means of creating a Tracer or Meter which stores references to all `Tracers` and `Meters` it has created. -Based on such an identifier, a Sampler could be implemented that discards Spans or Metrics from certain libraries. Also, by providing custom Exporters, Span or Metric data could be sanitized before it gets processed in a back-end system. However, this is beyond the scope of this proposal, which only provides the fundamental mechanisms. +Based on such an identifier, a Registry could provide a no-op Tracer or Meter to specific instrumentation libraries, or a Sampler could be implemented that discards Spans or Metrics from certain libraries. Also, by providing custom Exporters, Span or Metric data could be sanitized before it gets processed in a back-end system. However, this is beyond the scope of this proposal, which only provides the fundamental mechanisms. ## Explanation -From a user perspective, working with *Named Tracers / Meters* and `TracerFactory` / `MeterFactory` is conceptually similar to how e.g. the [Java logging API](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)) and logging frameworks like [log4j](https://www.slf4j.org/apidocs/org/slf4j/LoggerFactory.html) work. In analogy to requesting Logger objects through LoggerFactories, a tracing library would create specific Tracer / Meter objects through a TracerFactory / MeterFactory. +From a user perspective, working with *Named Tracers / Meters* and `TracerRegistry` / `MeterRegistry` is conceptually similar to how e.g. the [Java logging API](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)) and logging frameworks like [log4j](https://www.slf4j.org/apidocs/org/slf4j/LoggerRegistry.html) work. In analogy to requesting Logger objects through LoggerFactories, a trace reporting would create specific Tracer / Meter objects through a TracerRegistry / MeterRegistry. New Tracers or Meters can be created by providing the name and version of an instrumentation library. The version (following the convention proposed in https://github.com/open-telemetry/oteps/pull/38) is basically optional but *should* be supplied since only this information enables following scenarios: * Only a specific range of versions of a given instrumentation library need to be suppressed, while other versions are allowed (e.g. due to a bug in those specific versions). @@ -34,21 +42,21 @@ New Tracers or Meters can be created by providing the name and version of an ins ```java // Create a tracer/meter for a given instrumentation library in a specific version. -Tracer tracer = OpenTelemetry.getTracerFactory().getTracer("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); -Meter meter = OpenTelemetry.getMeterFactory().getMeter("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); +Tracer tracer = OpenTelemetry.getTracerRegistry().getTracer("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); +Meter meter = OpenTelemetry.getMeterRegistry().getMeter("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); ``` -These factories (`TracerFactory` and `MeterFactory`) replace the global `Tracer` / `Meter` singleton objects as ubiquitous points to request Tracer and Meter instances. +These factories (`TracerRegistry` and `MeterRegistry`) replace the global `Tracer` / `Meter` singleton objects as ubiquitous points to request Tracer and Meter instances. - The *name* used to create a Tracer or Meter must identify the *instrumentation* libraries (also referred to as *integrations*) and not the instrumented libraries. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation or even auto-injected code (see [Open Telemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end. -If a library (or application) has instrumentation built-in, it is both the instrumenting and instrumented library and should pass its own name here. In all other cases (and to distinguish them from that case), the distinction between instrumenting and instrumented library is very important. For example, if an HTTP library `com.example.http` is instrumented by either `io.opentelemetry.contrib.examplehttp` or `com.example.company.examplehttpintegration`, then it is important that the Tracer is not named `com.example.http` but after the actual instrumentation library. + The *name* used to create a Tracer or Meter must identify the *instrumentation* libraries (also referred to as *integrations* or *trace/meter reporting library*) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation, or even auto-injected code (see [Open Telemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end. +If a library (or application) has instrumentation built-in, it is both the instrumenting and instrumented library and should pass its own name here. In all other cases (and to distinguish them from that case), the distinction between instrumenting and instrumented library is very important. For example, if an HTTP library `com.example.http` is instrumented by either `io.opentelemetry.contrib.examplehttp`, then it is important that the Tracer is not named `com.example.http`, but `io.opentelemetry.contrib.examplehttp` after the actual instrumentation library. If no name (null or empty string) is specified, following the suggestions in ["error handling proposal"](https://github.com/open-telemetry/opentelemetry-specification/pull/153), a "smart default" will be applied and a default Tracer / Meter implementation is returned. ### Examples (of Tracer and Meter names) Since Tracer and Meter names describe the libraries which use those Tracers and Meters, their names should be defined in a way that makes them as unique as possible. -The name of the Tracer / Meter should represent the identity of the library, class or package that provides the instrumentation. +The name of the Tracer / Meter should represent the identity of the library, class or package that provides the instrumentation. Examples (based on existing contribution libraries from OpenTracing and OpenCensus): @@ -66,22 +74,46 @@ Examples (based on existing contribution libraries from OpenTracing and OpenCens ## Internal details -By providing a `TracerFactory` / `MeterFactory` and *Named Tracers / Meters*, a vendor or OpenTelemetry implementation gains more flexibility in providing Tracers and Meters and which attributes they set in the resulting Spans and Metrics that are produced. +By providing a `TracerRegistry` / `MeterRegistry` and *Named Tracers / Meters*, a vendor or OpenTelemetry implementation gains more flexibility in providing Tracers and Meters and which attributes they set in the resulting Spans and Metrics that are produced. On an SDK level, the SpanData class and its Metrics counterpart are extended with a `getLibraryResource` function that returns the resource associated with the Tracer / Meter that created it. +## Glossary of Terms + +#### Reporting library +Also known as the instrumentation library or the trace/metrics reporter, this may be either a library/module/plugin provided by OpenTelemetry that instruments an existing library, a third party integration which instruments some library, or a library that has implemented the OpenTelemetry API in order to instrument itself. In any case, the reporting library is the library which provides tracing and metrics data to OpenTelemetry. + +examples: +* `@opentelemetry/plugin-http` +* `io.opentelemetry.redis` +* `redis-client` (in this case, `redis-client` has instrumented itself with the OpenTelemetry API) + +#### Tracer name / Meter name +When it is acquired from the tracer/meter registry, the tracer/meter is assigned a name and a version which is the name and version of the reporting library that acquired the tracer. In cases where a library has instrumented itself using the OpenTelemetry API, they may be the same. + +example: If the `http` library is being instrumented by a library with the name `io.opentelemetry.contrib.http`, then the tracer name is also `io.opentelemetry.contrib.http`. If that same `http` library has built-in instrumentation through use of the OpenTelemetry API, then the tracer name would be `http`. + +### Disambiguation with related terms + +#### Meter namespace +This is included here because it is often confused with the meter name. + +This describes the component which is being instrumented. For instance, `latency` could be collected from a number of different things (http latency, disk latency, event loop latency) and a namespace ties the `latency` metric to the entity being metered. + +example: `bytes_transmitted` may be overall network bytes transmitted, or bytes transmitted specifically over `http`. In this case, it may be desirable to disambiguate these metrics by applying the `http` or `network` namespaces to the `bytes_transmitted` metric. + ## Prior art and alternatives This proposal originates from an `opentelemetry-specification` proposal on [components](https://github.com/open-telemetry/opentelemetry-specification/issues/10) since having a concept of named Tracers would automatically enable determining this semantic `component` property. -Alternatively, instead of having a `TracerFactory`, existing (global) Tracers could return additional indirection objects (called e.g. `TraceComponent`), which would be able to produce spans for specifically named traced components. +Alternatively, instead of having a `TracerRegistry`, existing (global) Tracers could return additional indirection objects (called e.g. `TraceComponent`), which would be able to produce spans for specifically named traced components. ```java TraceComponent traceComponent = OpenTelemetry.Tracing.getTracer().componentBuilder("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); Span span = traceComponent.spanBuilder("someMethod").startSpan(); ``` -Overall, this would not change a lot compared to the `TracerFactory` since the levels of indirection until producing an actual span are the same. +Overall, this would not change a lot compared to the `TracerRegistry` since the levels of indirection until producing an actual span are the same. Instead of setting the `component` property based on the given Tracer names, those names could also be used as *prefixes* for produced span names (e.g. ``). However, with regard to data quality and semantic conventions, a dedicated `component` set on spans is probably preferred. @@ -94,7 +126,7 @@ libraryLabels.put("name", "io.opentelemetry.contrib.mongodb"); libraryLabels.put("version", "1.0.0"); Resource libraryResource = Resource.create(libraryLabels); // Create tracer for given instrumentation library. -Tracer tracer = OpenTelemetry.getTracerFactory().getTracer(libraryResource); +Tracer tracer = OpenTelemetry.getTracerRegistry().getTracer(libraryResource); ``` Those given alternatives could be applied to Meters and Metrics in the same way. From 3ed14b3e862b82792ffc223dec9c24b4ae8298cd Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 7 Jan 2020 10:25:53 -0500 Subject: [PATCH 02/13] Apply suggestions from code review MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Christian Neumüller --- text/0016-named-tracers.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index fe5a72a53..ba1ccc605 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -12,15 +12,15 @@ _Creating Tracers and Meters using a Registry mechanism and naming those Tracers ## Motivation -The mechanism of "Named Tracers and Meters" proposed here is motivated by following scenarios: +The mechanism of "Named Tracers and Meters" proposed here is motivated by the following scenarios: **Expensive instrumentation** -For an operator of OpenTelemetry, there is currently no possibility of influencing the amount of the data produced by reporting libraries. Reporting libraries can easily "spam" backend systems, deliver bogus data, or - in the worst case - crash or slow down applications. These problems might even occur suddenly in production environments caused by external factors such as increasing load or unexpected input data. +For an operator of an application using OpenTelemetry, there is currently no way to influence the amount of data produced by reporting libraries. Reporting libraries can easily "spam" backend systems, deliver bogus data, or -- in the worst case -- crash or slow down applications. These problems might even occur suddenly in production environments because of external factors such as increasing load or unexpected input data. **Reporting library identification** -If a reporting library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize these data selectively. The produced Spans or Metrics cannot be associated with the library which reported them later. +If a reporting library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize data produced by it selectively. The produced Spans or Metrics cannot be associated with the library which reported them later. **Conflicting instrumentation libraries** @@ -136,4 +136,3 @@ Those given alternatives could be applied to Meters and Metrics in the same way. Based on the Resource information identifying a Tracer or Meter these could be configured (enabled / disabled) programmatically or via external configuration sources (e.g. environment). Based on this proposal, future "signal producers" (i.e. logs) can use the same or a similar creation approach. - From 8289f3b9247504be6b90682cde51b4a84e8cb83e Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 7 Jan 2020 16:01:01 -0500 Subject: [PATCH 03/13] clarify wording --- text/0016-named-tracers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index ba1ccc605..9d62cd154 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -2,7 +2,7 @@ **Status:** `approved` -_Creating Tracers and Meters using a Registry mechanism and naming those Tracers / Meters in accordance with the library that provides the instrumentation for those components._ +_Associate Tracers and Meters with the name and version of the library which reports telemetry data by parameterizing the API which the library uses to acquire the Tracer or Meter._ ## Suggested reading @@ -14,13 +14,13 @@ _Creating Tracers and Meters using a Registry mechanism and naming those Tracers The mechanism of "Named Tracers and Meters" proposed here is motivated by the following scenarios: -**Expensive instrumentation** +**Faulty or expensive instrumentation** For an operator of an application using OpenTelemetry, there is currently no way to influence the amount of data produced by reporting libraries. Reporting libraries can easily "spam" backend systems, deliver bogus data, or -- in the worst case -- crash or slow down applications. These problems might even occur suddenly in production environments because of external factors such as increasing load or unexpected input data. **Reporting library identification** -If a reporting library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize data produced by it selectively. The produced Spans or Metrics cannot be associated with the library which reported them later. +If a reporting library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize data produced by it selectively. The produced Spans or Metrics cannot later be associated with the library which reported them, either in the processing pipeline or the backend. **Conflicting instrumentation libraries** From 81987e0f581bb8e8190e05d7c714d63e350e95b3 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 8 Jan 2020 09:10:59 -0500 Subject: [PATCH 04/13] review comments --- text/0016-named-tracers.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index 9d62cd154..2f5e9205f 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -14,21 +14,23 @@ _Associate Tracers and Meters with the name and version of the library which rep The mechanism of "Named Tracers and Meters" proposed here is motivated by the following scenarios: -**Faulty or expensive instrumentation** +### Faulty or expensive instrumentation For an operator of an application using OpenTelemetry, there is currently no way to influence the amount of data produced by reporting libraries. Reporting libraries can easily "spam" backend systems, deliver bogus data, or -- in the worst case -- crash or slow down applications. These problems might even occur suddenly in production environments because of external factors such as increasing load or unexpected input data. -**Reporting library identification** +### Reporting library identification If a reporting library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize data produced by it selectively. The produced Spans or Metrics cannot later be associated with the library which reported them, either in the processing pipeline or the backend. -**Conflicting instrumentation libraries** +### Disable instrumentation of pre-instrumented libraries -It is the eventual goal of OpenTelemetry that library vendors implement the OpenTelemetry API, obviating the need to auto-instrument their library. An operator should be able to disable built-in instrumentation even if the library does not provide an explicit configuration to disable instrumentation. +It is the eventual goal of OpenTelemetry that library vendors implement the OpenTelemetry API, obviating the need to auto-instrument their library. An operator should be able to disable the telemetry that is built into some database driver or other library and provide their own integration if the built-in telemetry is lacking in some way. This should be possible even if the developer of that database driver has not provided a configuration to disable telemetry. + +## Solution This proposal attempts to solve the stated problems by introducing the concept of: - * _Named Tracers and Meters_ identified via a **name** (e.g. _"io.opentelemetry.contrib.mongodb"_) and a **version** (e.g._"semver:1.0.0"_) which is associated with the Tracer / Meter and the Spans / Metrics it produces. - * A `TracerRegistry` / `MeterRegistry` as the only means of creating a Tracer or Meter which stores references to all `Tracers` and `Meters` it has created. + * _Named Tracers and Meters_ which are associated with the **name** (e.g. _"io.opentelemetry.contrib.mongodb"_) and **version** (e.g._"semver:1.0.0"_) of the library which acquired them. + * A `TracerRegistry` / `MeterRegistry` as the only means of creating a Tracer or Meter. Based on such an identifier, a Registry could provide a no-op Tracer or Meter to specific instrumentation libraries, or a Sampler could be implemented that discards Spans or Metrics from certain libraries. Also, by providing custom Exporters, Span or Metric data could be sanitized before it gets processed in a back-end system. However, this is beyond the scope of this proposal, which only provides the fundamental mechanisms. @@ -98,7 +100,7 @@ example: If the `http` library is being instrumented by a library with the name #### Meter namespace This is included here because it is often confused with the meter name. -This describes the component which is being instrumented. For instance, `latency` could be collected from a number of different things (http latency, disk latency, event loop latency) and a namespace ties the `latency` metric to the entity being metered. +A Meter namespace describes the component which is being monitored. For instance, `latency` could be collected from a number of different things (http latency, disk latency, event loop latency) and a namespace ties the `latency` metric to the entity being metered. example: `bytes_transmitted` may be overall network bytes transmitted, or bytes transmitted specifically over `http`. In this case, it may be desirable to disambiguate these metrics by applying the `http` or `network` namespaces to the `bytes_transmitted` metric. From be7f538be2ab4eaf9a4886385fa7b85b06376bb1 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 8 Jan 2020 09:28:43 -0500 Subject: [PATCH 05/13] wording nitpicks --- text/0016-named-tracers.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index 2f5e9205f..680a40cbd 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -30,9 +30,9 @@ It is the eventual goal of OpenTelemetry that library vendors implement the Open This proposal attempts to solve the stated problems by introducing the concept of: * _Named Tracers and Meters_ which are associated with the **name** (e.g. _"io.opentelemetry.contrib.mongodb"_) and **version** (e.g._"semver:1.0.0"_) of the library which acquired them. - * A `TracerRegistry` / `MeterRegistry` as the only means of creating a Tracer or Meter. + * A `TracerRegistry` / `MeterRegistry` as the only means of acquiring a Tracer or Meter. -Based on such an identifier, a Registry could provide a no-op Tracer or Meter to specific instrumentation libraries, or a Sampler could be implemented that discards Spans or Metrics from certain libraries. Also, by providing custom Exporters, Span or Metric data could be sanitized before it gets processed in a back-end system. However, this is beyond the scope of this proposal, which only provides the fundamental mechanisms. +Based on the name and version, a Registry could provide a no-op Tracer or Meter to specific instrumentation libraries, or a Sampler could be implemented that discards Spans or Metrics from certain libraries. Also, by providing custom Exporters, Span or Metric data could be sanitized before it gets processed in a back-end system. However, this is beyond the scope of this proposal, which only provides the fundamental mechanisms. ## Explanation From c6033b03a51d9875dcee4debb80ad1cc11a84700 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 8 Jan 2020 11:56:33 -0500 Subject: [PATCH 06/13] Fix broken link --- text/0016-named-tracers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index 680a40cbd..b9627940b 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -36,7 +36,7 @@ Based on the name and version, a Registry could provide a no-op Tracer or Meter ## Explanation -From a user perspective, working with *Named Tracers / Meters* and `TracerRegistry` / `MeterRegistry` is conceptually similar to how e.g. the [Java logging API](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)) and logging frameworks like [log4j](https://www.slf4j.org/apidocs/org/slf4j/LoggerRegistry.html) work. In analogy to requesting Logger objects through LoggerFactories, a trace reporting would create specific Tracer / Meter objects through a TracerRegistry / MeterRegistry. +From a user perspective, working with *Named Tracers / Meters* and `TracerRegistry` / `MeterRegistry` is conceptually similar to how e.g. the [Java logging API](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)) and logging frameworks like [log4j](https://www.slf4j.org/apidocs/org/slf4j/LoggerFactory.html) work. In analogy to requesting Logger objects through LoggerFactories, a trace reporting would create specific Tracer / Meter objects through a TracerRegistry / MeterRegistry. New Tracers or Meters can be created by providing the name and version of an instrumentation library. The version (following the convention proposed in https://github.com/open-telemetry/oteps/pull/38) is basically optional but *should* be supplied since only this information enables following scenarios: * Only a specific range of versions of a given instrumentation library need to be suppressed, while other versions are allowed (e.g. due to a bug in those specific versions). From 7e08322d912670f9d74afc6189a6f7fe7db632c0 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 8 Jan 2020 13:15:51 -0500 Subject: [PATCH 07/13] rename registry to provider --- text/0016-named-tracers.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index b9627940b..7771b6dda 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -30,13 +30,13 @@ It is the eventual goal of OpenTelemetry that library vendors implement the Open This proposal attempts to solve the stated problems by introducing the concept of: * _Named Tracers and Meters_ which are associated with the **name** (e.g. _"io.opentelemetry.contrib.mongodb"_) and **version** (e.g._"semver:1.0.0"_) of the library which acquired them. - * A `TracerRegistry` / `MeterRegistry` as the only means of acquiring a Tracer or Meter. + * A `TracerProvider` / `MeterProvider` as the only means of acquiring a Tracer or Meter. -Based on the name and version, a Registry could provide a no-op Tracer or Meter to specific instrumentation libraries, or a Sampler could be implemented that discards Spans or Metrics from certain libraries. Also, by providing custom Exporters, Span or Metric data could be sanitized before it gets processed in a back-end system. However, this is beyond the scope of this proposal, which only provides the fundamental mechanisms. +Based on the name and version, a Provider could provide a no-op Tracer or Meter to specific instrumentation libraries, or a Sampler could be implemented that discards Spans or Metrics from certain libraries. Also, by providing custom Exporters, Span or Metric data could be sanitized before it gets processed in a back-end system. However, this is beyond the scope of this proposal, which only provides the fundamental mechanisms. ## Explanation -From a user perspective, working with *Named Tracers / Meters* and `TracerRegistry` / `MeterRegistry` is conceptually similar to how e.g. the [Java logging API](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)) and logging frameworks like [log4j](https://www.slf4j.org/apidocs/org/slf4j/LoggerFactory.html) work. In analogy to requesting Logger objects through LoggerFactories, a trace reporting would create specific Tracer / Meter objects through a TracerRegistry / MeterRegistry. +From a user perspective, working with *Named Tracers / Meters* and `TracerProvider` / `MeterProvider` is conceptually similar to how e.g. the [Java logging API](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)) and logging frameworks like [log4j](https://www.slf4j.org/apidocs/org/slf4j/LoggerFactory.html) work. In analogy to requesting Logger objects through LoggerFactories, a trace reporting would create specific Tracer / Meter objects through a TracerProvider / MeterProvider. New Tracers or Meters can be created by providing the name and version of an instrumentation library. The version (following the convention proposed in https://github.com/open-telemetry/oteps/pull/38) is basically optional but *should* be supplied since only this information enables following scenarios: * Only a specific range of versions of a given instrumentation library need to be suppressed, while other versions are allowed (e.g. due to a bug in those specific versions). @@ -44,11 +44,11 @@ New Tracers or Meters can be created by providing the name and version of an ins ```java // Create a tracer/meter for a given instrumentation library in a specific version. -Tracer tracer = OpenTelemetry.getTracerRegistry().getTracer("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); -Meter meter = OpenTelemetry.getMeterRegistry().getMeter("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); +Tracer tracer = OpenTelemetry.getTracerProvider().getTracer("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); +Meter meter = OpenTelemetry.getMeterProvider().getMeter("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); ``` -These factories (`TracerRegistry` and `MeterRegistry`) replace the global `Tracer` / `Meter` singleton objects as ubiquitous points to request Tracer and Meter instances. +These factories (`TracerProvider` and `MeterProvider`) replace the global `Tracer` / `Meter` singleton objects as ubiquitous points to request Tracer and Meter instances. The *name* used to create a Tracer or Meter must identify the *instrumentation* libraries (also referred to as *integrations* or *trace/meter reporting library*) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation, or even auto-injected code (see [Open Telemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end. If a library (or application) has instrumentation built-in, it is both the instrumenting and instrumented library and should pass its own name here. In all other cases (and to distinguish them from that case), the distinction between instrumenting and instrumented library is very important. For example, if an HTTP library `com.example.http` is instrumented by either `io.opentelemetry.contrib.examplehttp`, then it is important that the Tracer is not named `com.example.http`, but `io.opentelemetry.contrib.examplehttp` after the actual instrumentation library. @@ -76,7 +76,7 @@ Examples (based on existing contribution libraries from OpenTracing and OpenCens ## Internal details -By providing a `TracerRegistry` / `MeterRegistry` and *Named Tracers / Meters*, a vendor or OpenTelemetry implementation gains more flexibility in providing Tracers and Meters and which attributes they set in the resulting Spans and Metrics that are produced. +By providing a `TracerProvider` / `MeterProvider` and *Named Tracers / Meters*, a vendor or OpenTelemetry implementation gains more flexibility in providing Tracers and Meters and which attributes they set in the resulting Spans and Metrics that are produced. On an SDK level, the SpanData class and its Metrics counterpart are extended with a `getLibraryResource` function that returns the resource associated with the Tracer / Meter that created it. @@ -91,7 +91,7 @@ examples: * `redis-client` (in this case, `redis-client` has instrumented itself with the OpenTelemetry API) #### Tracer name / Meter name -When it is acquired from the tracer/meter registry, the tracer/meter is assigned a name and a version which is the name and version of the reporting library that acquired the tracer. In cases where a library has instrumented itself using the OpenTelemetry API, they may be the same. +When it is acquired from the tracer/meter Provider, the tracer/meter is assigned a name and a version which is the name and version of the reporting library that acquired the tracer. In cases where a library has instrumented itself using the OpenTelemetry API, they may be the same. example: If the `http` library is being instrumented by a library with the name `io.opentelemetry.contrib.http`, then the tracer name is also `io.opentelemetry.contrib.http`. If that same `http` library has built-in instrumentation through use of the OpenTelemetry API, then the tracer name would be `http`. @@ -108,14 +108,14 @@ example: `bytes_transmitted` may be overall network bytes transmitted, or bytes This proposal originates from an `opentelemetry-specification` proposal on [components](https://github.com/open-telemetry/opentelemetry-specification/issues/10) since having a concept of named Tracers would automatically enable determining this semantic `component` property. -Alternatively, instead of having a `TracerRegistry`, existing (global) Tracers could return additional indirection objects (called e.g. `TraceComponent`), which would be able to produce spans for specifically named traced components. +Alternatively, instead of having a `TracerProvider`, existing (global) Tracers could return additional indirection objects (called e.g. `TraceComponent`), which would be able to produce spans for specifically named traced components. ```java TraceComponent traceComponent = OpenTelemetry.Tracing.getTracer().componentBuilder("io.opentelemetry.contrib.mongodb", "semver:1.0.0"); Span span = traceComponent.spanBuilder("someMethod").startSpan(); ``` -Overall, this would not change a lot compared to the `TracerRegistry` since the levels of indirection until producing an actual span are the same. +Overall, this would not change a lot compared to the `TracerProvider` since the levels of indirection until producing an actual span are the same. Instead of setting the `component` property based on the given Tracer names, those names could also be used as *prefixes* for produced span names (e.g. ``). However, with regard to data quality and semantic conventions, a dedicated `component` set on spans is probably preferred. @@ -128,7 +128,7 @@ libraryLabels.put("name", "io.opentelemetry.contrib.mongodb"); libraryLabels.put("version", "1.0.0"); Resource libraryResource = Resource.create(libraryLabels); // Create tracer for given instrumentation library. -Tracer tracer = OpenTelemetry.getTracerRegistry().getTracer(libraryResource); +Tracer tracer = OpenTelemetry.getTracerProvider().getTracer(libraryResource); ``` Those given alternatives could be applied to Meters and Metrics in the same way. From 276e4573b06fe8103f780e87c02efc7b12da141c Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 8 Jan 2020 13:25:04 -0500 Subject: [PATCH 08/13] Remove reporting library terminology --- text/0016-named-tracers.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index 7771b6dda..eaa41789b 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -2,7 +2,7 @@ **Status:** `approved` -_Associate Tracers and Meters with the name and version of the library which reports telemetry data by parameterizing the API which the library uses to acquire the Tracer or Meter._ +_Associate Tracers and Meters with the name and version of the instrumentation library which reports telemetry data by parameterizing the API which the library uses to acquire the Tracer or Meter._ ## Suggested reading @@ -16,11 +16,11 @@ The mechanism of "Named Tracers and Meters" proposed here is motivated by the fo ### Faulty or expensive instrumentation -For an operator of an application using OpenTelemetry, there is currently no way to influence the amount of data produced by reporting libraries. Reporting libraries can easily "spam" backend systems, deliver bogus data, or -- in the worst case -- crash or slow down applications. These problems might even occur suddenly in production environments because of external factors such as increasing load or unexpected input data. +For an operator of an application using OpenTelemetry, there is currently no way to influence the amount of data produced by instrumentation libraries. Instrumentation libraries can easily "spam" backend systems, deliver bogus data, or -- in the worst case -- crash or slow down applications. These problems might even occur suddenly in production environments because of external factors such as increasing load or unexpected input data. -### Reporting library identification +### Instrumentation library identification -If a reporting library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize data produced by it selectively. The produced Spans or Metrics cannot later be associated with the library which reported them, either in the processing pipeline or the backend. +If an instrumentation library hasn't implemented [semantic conventions](https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/data-semantic-conventions.md) correctly or those conventions change over time, it's currently hard to interpret and sanitize data produced by it selectively. The produced Spans or Metrics cannot later be associated with the library which reported them, either in the processing pipeline or the backend. ### Disable instrumentation of pre-instrumented libraries @@ -36,7 +36,7 @@ Based on the name and version, a Provider could provide a no-op Tracer or Meter ## Explanation -From a user perspective, working with *Named Tracers / Meters* and `TracerProvider` / `MeterProvider` is conceptually similar to how e.g. the [Java logging API](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)) and logging frameworks like [log4j](https://www.slf4j.org/apidocs/org/slf4j/LoggerFactory.html) work. In analogy to requesting Logger objects through LoggerFactories, a trace reporting would create specific Tracer / Meter objects through a TracerProvider / MeterProvider. +From a user perspective, working with *Named Tracers / Meters* and `TracerProvider` / `MeterProvider` is conceptually similar to how e.g. the [Java logging API](https://docs.oracle.com/javase/7/docs/api/java/util/logging/Logger.html#getLogger(java.lang.String)) and logging frameworks like [log4j](https://www.slf4j.org/apidocs/org/slf4j/LoggerFactory.html) work. In analogy to requesting Logger objects through LoggerFactories, an instrumentation library would create specific Tracer / Meter objects through a TracerProvider / MeterProvider. New Tracers or Meters can be created by providing the name and version of an instrumentation library. The version (following the convention proposed in https://github.com/open-telemetry/oteps/pull/38) is basically optional but *should* be supplied since only this information enables following scenarios: * Only a specific range of versions of a given instrumentation library need to be suppressed, while other versions are allowed (e.g. due to a bug in those specific versions). @@ -50,7 +50,7 @@ Meter meter = OpenTelemetry.getMeterProvider().getMeter("io.opentelemetry.contri These factories (`TracerProvider` and `MeterProvider`) replace the global `Tracer` / `Meter` singleton objects as ubiquitous points to request Tracer and Meter instances. - The *name* used to create a Tracer or Meter must identify the *instrumentation* libraries (also referred to as *integrations* or *trace/meter reporting library*) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation, or even auto-injected code (see [Open Telemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end. + The *name* used to create a Tracer or Meter must identify the *instrumentation* libraries (also referred to as *integrations*) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation, or even auto-injected code (see [Open Telemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end. If a library (or application) has instrumentation built-in, it is both the instrumenting and instrumented library and should pass its own name here. In all other cases (and to distinguish them from that case), the distinction between instrumenting and instrumented library is very important. For example, if an HTTP library `com.example.http` is instrumented by either `io.opentelemetry.contrib.examplehttp`, then it is important that the Tracer is not named `com.example.http`, but `io.opentelemetry.contrib.examplehttp` after the actual instrumentation library. If no name (null or empty string) is specified, following the suggestions in ["error handling proposal"](https://github.com/open-telemetry/opentelemetry-specification/pull/153), a "smart default" will be applied and a default Tracer / Meter implementation is returned. @@ -82,8 +82,8 @@ On an SDK level, the SpanData class and its Metrics counterpart are extended wit ## Glossary of Terms -#### Reporting library -Also known as the instrumentation library or the trace/metrics reporter, this may be either a library/module/plugin provided by OpenTelemetry that instruments an existing library, a third party integration which instruments some library, or a library that has implemented the OpenTelemetry API in order to instrument itself. In any case, the reporting library is the library which provides tracing and metrics data to OpenTelemetry. +#### Instrumentation library +Also known as the trace/metrics reporter, this may be either a library/module/plugin provided by OpenTelemetry that instruments an existing library, a third party integration which instruments some library, or a library that has implemented the OpenTelemetry API in order to instrument itself. In any case, the instrumentation library is the library which provides tracing and metrics data to OpenTelemetry. examples: * `@opentelemetry/plugin-http` From fc457f761dad8dd5cd3d728621642eb0fdba2aee Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Tue, 14 Jan 2020 05:35:42 -0700 Subject: [PATCH 09/13] remove errant word Co-Authored-By: Tyler Yahn --- text/0016-named-tracers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index 7771b6dda..00a0853ee 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -51,7 +51,7 @@ Meter meter = OpenTelemetry.getMeterProvider().getMeter("io.opentelemetry.contri These factories (`TracerProvider` and `MeterProvider`) replace the global `Tracer` / `Meter` singleton objects as ubiquitous points to request Tracer and Meter instances. The *name* used to create a Tracer or Meter must identify the *instrumentation* libraries (also referred to as *integrations* or *trace/meter reporting library*) and not the library being instrumented. These instrumentation libraries could be libraries developed in an OpenTelemetry repository, a 3rd party implementation, or even auto-injected code (see [Open Telemetry Without Manual Instrumentation OTEP](https://github.com/open-telemetry/oteps/blob/master/text/0001-telemetry-without-manual-instrumentation.md)). See also the examples for identifiers at the end. -If a library (or application) has instrumentation built-in, it is both the instrumenting and instrumented library and should pass its own name here. In all other cases (and to distinguish them from that case), the distinction between instrumenting and instrumented library is very important. For example, if an HTTP library `com.example.http` is instrumented by either `io.opentelemetry.contrib.examplehttp`, then it is important that the Tracer is not named `com.example.http`, but `io.opentelemetry.contrib.examplehttp` after the actual instrumentation library. +If a library (or application) has instrumentation built-in, it is both the instrumenting and instrumented library and should pass its own name here. In all other cases (and to distinguish them from that case), the distinction between instrumenting and instrumented library is very important. For example, if an HTTP library `com.example.http` is instrumented by `io.opentelemetry.contrib.examplehttp`, then it is important that the Tracer is not named `com.example.http`, but `io.opentelemetry.contrib.examplehttp` after the actual instrumentation library. If no name (null or empty string) is specified, following the suggestions in ["error handling proposal"](https://github.com/open-telemetry/opentelemetry-specification/pull/153), a "smart default" will be applied and a default Tracer / Meter implementation is returned. From 63a2c438fd083cae370f5ae53fed0666ec62f6ff Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 15 Jan 2020 15:38:36 -0500 Subject: [PATCH 10/13] meter name is being used as meter namespace --- text/0016-named-tracers.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index eaa41789b..429e1d7ec 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -91,18 +91,14 @@ examples: * `redis-client` (in this case, `redis-client` has instrumented itself with the OpenTelemetry API) #### Tracer name / Meter name -When it is acquired from the tracer/meter Provider, the tracer/meter is assigned a name and a version which is the name and version of the reporting library that acquired the tracer. In cases where a library has instrumented itself using the OpenTelemetry API, they may be the same. +When an instrumentation library acquires a Tracer/Meter, it provides its own name and version to the Tracer/Meter Provider. This name/version two-tuple is said to be the Tracer/Meter's _name_. Note that this is the name and version of the library which acquires the Tracer/Meter, and not the library it is monitoring. In cases where the library is instrumenting itself using the OpenTelemetry API, they may be the same. example: If the `http` library is being instrumented by a library with the name `io.opentelemetry.contrib.http`, then the tracer name is also `io.opentelemetry.contrib.http`. If that same `http` library has built-in instrumentation through use of the OpenTelemetry API, then the tracer name would be `http`. -### Disambiguation with related terms - #### Meter namespace -This is included here because it is often confused with the meter name. - -A Meter namespace describes the component which is being monitored. For instance, `latency` could be collected from a number of different things (http latency, disk latency, event loop latency) and a namespace ties the `latency` metric to the entity being metered. +Meter name is used as a namespace for all metrics created by it. This allows a telemetry library to register a metric using any name, such as `latency`, without worrying about collisions with a metric registered under the same name by a different library. -example: `bytes_transmitted` may be overall network bytes transmitted, or bytes transmitted specifically over `http`. In this case, it may be desirable to disambiguate these metrics by applying the `http` or `network` namespaces to the `bytes_transmitted` metric. +example: The libraries `mongodb` and `postgresql` may both register metrics with the name `latency`. These metrics can still be uniquely identified even though they have the same name because they are registered under different namespaces (`mongodb` and `postgresql` respectively). ## Prior art and alternatives From 312a65f055ce48cf6b21b8084c0ea9979bda3a69 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Fri, 17 Jan 2020 09:52:44 -0500 Subject: [PATCH 11/13] disambiguate name vs name/version 2-tuple --- text/0016-named-tracers.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index 429e1d7ec..eaa6fe117 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -90,10 +90,10 @@ examples: * `io.opentelemetry.redis` * `redis-client` (in this case, `redis-client` has instrumented itself with the OpenTelemetry API) -#### Tracer name / Meter name -When an instrumentation library acquires a Tracer/Meter, it provides its own name and version to the Tracer/Meter Provider. This name/version two-tuple is said to be the Tracer/Meter's _name_. Note that this is the name and version of the library which acquires the Tracer/Meter, and not the library it is monitoring. In cases where the library is instrumenting itself using the OpenTelemetry API, they may be the same. +#### Tracer name / Meter name and version +When an instrumentation library acquires a Tracer/Meter, it provides its own name and version to the Tracer/Meter Provider. This name/version two-tuple is said to be the Tracer/Meter's _name_ and _version_. Note that this is the name and version of the library which acquires the Tracer/Meter, and not the library it is monitoring. In cases where the library is instrumenting itself using the OpenTelemetry API, they may be the same. -example: If the `http` library is being instrumented by a library with the name `io.opentelemetry.contrib.http`, then the tracer name is also `io.opentelemetry.contrib.http`. If that same `http` library has built-in instrumentation through use of the OpenTelemetry API, then the tracer name would be `http`. +example: If the `http` version `semver:3.0.0` library is being instrumented by a library with the name `io.opentelemetry.contrib.http` and version `semver:1.3.2`, then the tracer name and version are also `io.opentelemetry.contrib.http` and `semver:1.3.2`. If that same `http` library has built-in instrumentation through use of the OpenTelemetry API, then the tracer name and version would be `http` and `semver:3.0.0`. #### Meter namespace Meter name is used as a namespace for all metrics created by it. This allows a telemetry library to register a metric using any name, such as `latency`, without worrying about collisions with a metric registered under the same name by a different library. From 4d04fe014e4dc3383f8b90a353adfcb76efc6e1c Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Mon, 20 Jan 2020 07:46:29 -0500 Subject: [PATCH 12/13] header clarification --- text/0016-named-tracers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index eaa6fe117..3158ef044 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -90,7 +90,7 @@ examples: * `io.opentelemetry.redis` * `redis-client` (in this case, `redis-client` has instrumented itself with the OpenTelemetry API) -#### Tracer name / Meter name and version +#### Tracer / Meter name and version When an instrumentation library acquires a Tracer/Meter, it provides its own name and version to the Tracer/Meter Provider. This name/version two-tuple is said to be the Tracer/Meter's _name_ and _version_. Note that this is the name and version of the library which acquires the Tracer/Meter, and not the library it is monitoring. In cases where the library is instrumenting itself using the OpenTelemetry API, they may be the same. example: If the `http` version `semver:3.0.0` library is being instrumented by a library with the name `io.opentelemetry.contrib.http` and version `semver:1.3.2`, then the tracer name and version are also `io.opentelemetry.contrib.http` and `semver:1.3.2`. If that same `http` library has built-in instrumentation through use of the OpenTelemetry API, then the tracer name and version would be `http` and `semver:3.0.0`. From 6eca459fec6ccfb512d1d841df449e9687ee3727 Mon Sep 17 00:00:00 2001 From: Daniel Dyla Date: Wed, 22 Jan 2020 08:26:01 -0500 Subject: [PATCH 13/13] suggestion from @jmacd --- text/0016-named-tracers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/text/0016-named-tracers.md b/text/0016-named-tracers.md index 3158ef044..1268da44a 100644 --- a/text/0016-named-tracers.md +++ b/text/0016-named-tracers.md @@ -98,7 +98,7 @@ example: If the `http` version `semver:3.0.0` library is being instrumented by a #### Meter namespace Meter name is used as a namespace for all metrics created by it. This allows a telemetry library to register a metric using any name, such as `latency`, without worrying about collisions with a metric registered under the same name by a different library. -example: The libraries `mongodb` and `postgresql` may both register metrics with the name `latency`. These metrics can still be uniquely identified even though they have the same name because they are registered under different namespaces (`mongodb` and `postgresql` respectively). +example: The libraries `redis` and `io.opentelemetry.redis` may both register metrics with the name `latency`. These metrics can still be uniquely identified even though they have the same name because they are registered under different namespaces (`redis` and `io.opentelemetry.redis` respectively). In this case, the operator may disable one of these metrics because they are measuring the same thing. ## Prior art and alternatives