This document defines some terms that are used across this specification.
Some other fundamental terms are documented in the overview document.
Table of Contents
- User Roles
- Common
- Signals
- Packages
- ABI Compatibility
- In-band and Out-of-band Data
- Manual Instrumentation
- Automatic Instrumentation
- Natively Instrumented
- Telemetry SDK
- Constructors
- SDK Plugins
- Exporter Library
- Instrumented Library
- Instrumentation Library
- Instrumentation Scope
- Tracer Name / Meter Name / Logger Name
- Execution Unit
- Logs
The maintainer of an application or service, responsible for configuring and managing the lifecycle of the OpenTelemetry SDK.
The maintainer of a shared library which is depended upon by many applications, and targeted by OpenTelemetry instrumentation.
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.
The maintainer of an OpenTelemetry SDK Plugin, written against OpenTelemetry SDK plugin interfaces.
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.
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.
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 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.
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.).
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.
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.
Denotes the library that implements the OpenTelemetry API.
See Library Guidelines and Library resource semantic conventions.
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.
Plugins are libraries which extend the OpenTelemetry SDK. Examples of plugin interfaces are the SpanProcessor, Exporter, and Sampler interfaces.
Exporters are SDK Plugins which implement the Exporter interface, and emit telemetry to consumers.
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.
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.
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.
If the unit of code has a version then the instrumentation scope is defined by the (name,version) pair otherwise the version is omitted and only the name is used. The name or (name,version) pair uniquely identify the logical unit of the code that emits the telemetry. A typical approach to ensure uniqueness is to use 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 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.
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.
An umbrella term for the smallest unit of sequential code execution, used in different concepts of multitasking. Examples are threads, coroutines or fibers.
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.
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).
Log Records embedded inside a Span
object, in the Events list.
Log Records that are not embedded inside a Span and are recorded elsewhere.
Key/value pairs contained in a Log Record.
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.
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.
A log appender or bridge is a component which bridges logs from an existing log API into OpenTelemetry using the Log Bridge 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.