diff --git a/specification/error-handling.md b/specification/error-handling.md index a134e256c9d..666fb60c57c 100644 --- a/specification/error-handling.md +++ b/specification/error-handling.md @@ -44,7 +44,7 @@ And make a reasonable trade off of the SDK performance and fullness of type chec ## Self-diagnostics -All OpenTelemetry libraries -- the API, SDK, exporters, instrumentation adapters, etc. -- are encouraged to expose self-troubleshooting metrics, spans, and other telemetry that can be easily enabled and filtered out by default. +All OpenTelemetry libraries -- the API, SDK, exporters, instrumentations, etc. -- are encouraged to expose self-troubleshooting metrics, spans, and other telemetry that can be easily enabled and filtered out by default. One good example of such telemetry is a `Span` exporter that indicates how much time exporters spend uploading telemetry. Another example may be a metric exposed by a `SpanProcessor` that describes the current queue size of telemetry data to be uploaded. diff --git a/specification/glossary.md b/specification/glossary.md index f8a53aa2fd7..d7330da4d2d 100644 --- a/specification/glossary.md +++ b/specification/glossary.md @@ -25,15 +25,15 @@ Example: `org.mongodb.client`. -### Instrumenting Library +### Instrumentation Library Denotes the library that provides the instrumentation for a given [Instrumented Library](#instrumented_library). -*Instrumented Library* and *Instrumenting Library* may be the same library +*Instrumented Library* and *Instrumentation Library* may be the same library if it has built-in OpenTelemetry instrumentation. Example: `io.opentelemetry.contrib.mongodb`. -Synonyms: *Instrumentation Library*, *Integration*. +Synonyms: *Instrumentation Library* diff --git a/specification/overview.md b/specification/overview.md index 3b8d8af320a..7f96cb69150 100644 --- a/specification/overview.md +++ b/specification/overview.md @@ -261,22 +261,29 @@ service). Read more at OpenTelemetry Service [Long-term Vision](https://github.com/open-telemetry/opentelemetry-collector/blob/master/docs/vision.md). -## Instrumentation adapters +## Instrumentation Libraries + +See [Instrumentation Library](glossary.md#instrumentation_library) The inspiration of the project is to make every library and application -manageable out of the box by instrumenting it with OpenTelemetry. However on the -way to this goal there will be a need to enable instrumentation by plugging -instrumentation adapters into the library of choice. These adapters can be -wrapping library APIs, subscribing to the library-specific callbacks or -translating telemetry exposed in other formats into OpenTelemetry model. - -Instrumentation adapters may be called different names. It is often referred as -plugin, collector or auto-collector, telemetry module, bridge, etc. It is always -recommended to follow the library and language standards. For instance, if -instrumentation adapter is implemented as "log appender" - it will probably be -called an `appender`, not an instrumentation adapter. However if there is no -established name - the recommendation is to call packages "Instrumentation -Adapter" or simply "Adapter". +observable out of the box by having them call OpenTelemetry API directly. However, +many libraries will not have such integration, and as such there is a need for +a separate library which would inject such calls, using mechanisms such as +wrapping interfaces, subscribing to library-specific callbacks, or translating +existing telemetry into the OpenTelemetry model. + +A library that enables OpenTelemetry observability for another library is called +an [Instrumentation Library](glossary.md#instrumentation_library). + +An instrumentation library should be named to follow any naming conventions of +the instrumented library (e.g. 'middleware' for a web framework). + +If there is no established name, the recommendation is to prefix packages +with "opentelemetry-instrumentation", followed by the instrumented library +name itself. Examples include: + +* opentelemetry-instrumentation-flask (Python) +* @opentelemetry/instrumentation-grpc (Javascript) ## Code injecting adapters diff --git a/specification/trace/api.md b/specification/trace/api.md index c55143973e0..b61d1d5782d 100644 --- a/specification/trace/api.md +++ b/specification/trace/api.md @@ -88,8 +88,7 @@ Some applications may use multiple `TracerProvider` 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. -- `name` (required): This name must identify the instrumentation library (also - referred to as integration, e.g. `io.opentelemetry.contrib.mongodb`) and *not* +- `name` (required): This name must identify the instrumentation library (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