Glossary

This document defines some terms that are used across this specification.

Some other fundamental terms are documented in the overview document.

User Roles

Application Owner

The maintainer of an application or service, responsible for configuring and managing the lifecycle of the OpenTelemetry SDK.

Library Author

The maintainer of a shared library which is depended upon by many applications, and targeted by OpenTelemetry instrumentation.

Instrumentation Author

The maintainer of OpenTelemetry instrumentation written against the OpenTelemetry API. This may be instrumentation written within application code, within a shared library, or within an instrumentation library.

Plugin Author

The maintainer of an OpenTelemetry SDK Plugin, written against OpenTelemetry SDK plugin interfaces.

Common

Signals

OpenTelemetry is structured around signals, or categories of telemetry. Metrics, logs, traces, and baggage are examples of signals. Each signal represents a coherent, stand-alone set of functionality. Each signal follows a separate lifecycle, defining its current stability level.

Packages

In this specification, the term package describes a set of code which represents a single dependency, which may be imported into a program independently from other packages. This concept may map to a different term in some languages, such as “module.” Note that in some languages, the term “package” refers to a different concept.

ABI Compatibility

An ABI (application binary interface) is an interface which defines interactions between software components at the machine code level, for example between an application executable and a compiled binary of a shared object library. ABI compatibility means that a new compiled version of a library may be correctly linked to a target executable without the need for that executable to be recompiled.

ABI compatibility is important for some languages, especially those which provide a form of machine code. For other languages, ABI compatibility may not be a relevant requirement.

In-band and Out-of-band Data

In telecommunications, in-band signaling is the sending of control information within the same band or channel used for data such as voice or video. This is in contrast to out-of-band signaling which is sent over a different channel, or even over a separate network (Wikipedia).

In OpenTelemetry we refer to in-band data as data that is passed between components of a distributed system as part of business messages, for example, when trace or baggages are included in the HTTP requests in the form of HTTP headers. Such data usually does not contain the telemetry, but is used to correlate and join the telemetry produced by various components. The telemetry itself is referred to as out-of-band data: it is transmitted from applications via dedicated messages, usually asynchronously by background routines rather than from the critical path of the business logic. Metrics, logs, and traces exported to telemetry backends are examples of out-of-band data.

Manual Instrumentation

Coding against the OpenTelemetry API such as the Tracing API, Metrics API, or others to collect telemetry from end-user code or shared frameworks (e.g. MongoDB, Redis, etc.).

Automatic Instrumentation

Refers to telemetry collection methods that do not require the end-user to modify application’s source code. Methods vary by programming language, and examples include code manipulation (during compilation or at runtime), monkey patching, or running eBPF programs.

Synonym: Auto-instrumentation.

Natively Instrumented

Denotes a library or application that uses the OpenTelemetry API directly to provide built-in instrumentation, thus instrumented library and instrumentation library are the same library.

If a separate instrumentation library or a plugin is required to instrument a library or application, that instrumented library or application must not be called natively instrumented, even if the instrumentation library or plugin is provided by the same authors or is a plugin that fits into the ecosystem of the given software.

Telemetry SDK

Denotes the library that implements the OpenTelemetry API.

See Library Guidelines and Library resource semantic conventions.

Constructors

Constructors are public code used by Application Owners to initialize and configure the OpenTelemetry SDK and contrib packages. Examples of constructors include configuration objects, environment variables, and builders.

SDK Plugins

Plugins are libraries which extend the OpenTelemetry SDK. Examples of plugin interfaces are the SpanProcessor, Exporter, and Sampler interfaces.

Exporter Library

Exporters are SDK Plugins which implement the Exporter interface, and emit telemetry to consumers.

Instrumented Library

Denotes the library for which the telemetry signals (traces, metrics, logs) are gathered.

The calls to the OpenTelemetry API can be done either by the Instrumented Library itself, or by another Instrumentation Library.

Example: org.mongodb.client.

Instrumentation Library

Denotes the library that provides the instrumentation for a given Instrumented Library. Instrumented Library and Instrumentation Library may be the same library if it has built-in OpenTelemetry instrumentation.

See Overview for a more detailed definition and naming guidelines.

Example: io.opentelemetry.contrib.mongodb.

Synonyms: Instrumenting Library.

Instrumentation Scope

A logical unit of the application code with which the emitted telemetry can be associated. It is typically the developer’s choice to decide what denotes a reasonable instrumentation scope. The most common approach is to use the instrumentation library as the scope, however other scopes are also common, e.g. a module, a package, or a class can be chosen as the instrumentation scope.

The instrumentation scope is defined by the (name,version,schema_url,attributes) tuple where version, schema_url, and attributes are optional. This tuple uniquely identifies the logical unit of the code that emits the telemetry. A typical approach to ensure uniqueness is to use the fully qualified name of the emitting code (e.g. fully qualified library name or fully qualified class name).

The instrumentation scope is used to obtain a Tracer, Meter, or Logger.

The instrumentation scope’s optional Schema URL identifies the Telemetry Schema that the instrumentation’s emitted telemetry conforms to.

The instrumentation scope may have zero or more additional attributes that provide additional information about the scope. For example for a scope that specifies an instrumentation library an additional attribute may be recorded to denote the URL of the repository URL the library’s source code is stored. Since the scope is a build-time concept the attributes of the scope cannot change at runtime.

Tracer Name / Meter Name / Logger Name

This refers to the name and (optional) version arguments specified when creating a new Tracer or Meter (see Obtaining a Tracer/Obtaining a Meter)/Obtaining a Logger. The name/version pair identifies the Instrumentation Scope, for example the Instrumentation Library or another unit of application in the scope of which the telemetry is emitted.

Execution Unit

An umbrella term for the smallest unit of sequential code execution, used in different concepts of multitasking. Examples are threads, coroutines or fibers.

Logs

Log Record

A recording of an event. Typically the record includes a timestamp indicating when the event happened as well as other data that describes what happened, where it happened, etc.

Synonyms: Log Entry.

Log

Sometimes used to refer to a collection of Log Records. May be ambiguous, since people also sometimes use Log to refer to a single Log Record, thus this term should be used carefully and in the context where ambiguity is possible additional qualifiers should be used (e.g. Log Record).

Embedded Log

Log Records embedded inside a Span object, in the Events list.

Standalone Log

Log Records that are not embedded inside a Span and are recorded elsewhere.

Log Attributes

Key/value pairs contained in a Log Record.

Structured Logs

Logs that are recorded in a format which has a well-defined structure that allows to differentiate between different elements of a Log Record (e.g. the Timestamp, the Attributes, etc). The Syslog protocol (RFC 5424), for example, defines a structured-data format.

Flat File Logs

Logs recorded in text files, often one line per log record (although multiline records are possible too). There is no common industry agreement whether logs written to text files in more structured formats (e.g. JSON files) are considered Flat File Logs or not. Where such distinction is important it is recommended to call it out specifically.

Log Appender / Bridge

A log appender or bridge is a component which bridges logs from an existing log API into OpenTelemetry using the Log API. The terms “log bridge” and “log appender” are used interchangeably, reflecting that these components bridge data into OpenTelemetry, but are often called appenders in the logging domain.