Status: Mixed This document defines standard attributes for resources. These attributes are typically used in the Resource and are also recommended to be used anywhere else where there is a need to describe a resource in a consistent manner. The majority of these attributes are inherited from OpenCensus Resource standard. TODOs Add more compute units: AppEngine unit, etc. Add Web Browser. Decide if lower case strings only. Consider to add optional/required for each attribute and combination o...| OpenTelemetry
Status: Alpha Overview Environment variables provide a mechanism to propagate context and baggage information across process boundaries when network protocols are not applicable. This specification extends the API Propagators to define how the TextMapPropagator can be used with environment variables. Common systems where context propagation via environment variables is useful include: Batch processing systems CI/CD environments Command-line tools Propagator Mechanisms Propagating context via ...| OpenTelemetry
Status: Stable Overview Cross-cutting concerns send their state to the next process using Propagators, which are defined as objects used to read and write context data to and from messages exchanged by the applications. Each concern creates a set of Propagators for every supported Propagator type. Propagators leverage the Context to inject and extract data for each cross-cutting concern, such as traces and Baggage. Propagation is usually implemented via a cooperation of library-specific reque...| OpenTelemetry
Status: Stable. Overview A Context is a propagation mechanism which carries execution-scoped values across API boundaries and between logically associated execution units. Cross-cutting concerns access their data in-process using the same shared Context object. A Context MUST be immutable, and its write operations MUST result in the creation of a new Context containing the original values and the specified values updated. Languages are expected to use the single, widely used Context implement...| OpenTelemetry
Status: Development Overview The OpenTelemetry configuration data model is part of the declarative configuration interface. The data model defines data structures which allow users to specify an intended configuration of OpenTelemetry SDK components and instrumentation. The data model is defined in opentelemetry-configuration using JSON Schema. The data model itself is an abstraction with multiple built-in representations: File-based configuration model SDK in-memory configuration model Stabi...| OpenTelemetry
Status: Stable, except where otherwise specified The Logs API is provided for logging library authors to build log appenders, which use this API to bridge between existing logging libraries and the OpenTelemetry log data model. The Logs API can also be directly called by instrumentation libraries as well as instrumented libraries or applications. The Logs API consist of these main components: LoggerProvider is the entry point of the API. It provides access to Loggers. Logger is responsible fo...| OpenTelemetry
Status: Development Overview The instrumentation configuration API is part of the declarative configuration interface. The API allows instrumentation libraries to consume configuration by reading relevant configuration during initialization. For example, an instrumentation library for an HTTP client can read the set of HTTP request and response headers to capture. It consists of the following main components: ConfigProvider is the entry point of the API. ConfigProperties is a programmatic rep...| OpenTelemetry
Status: Stable Overview Baggage is a set of application-defined properties contextually associated with a distributed request or workflow execution (see also the W3C Baggage Specification). Baggage can be used, among other things, to annotate telemetry, adding contextual information to metrics, traces, and logs. In OpenTelemetry Baggage is represented as a set of name/value pairs describing user-defined properties. Each name in Baggage MUST be associated with exactly one value. This is more r...| OpenTelemetry
Status: Development A Schema File is a YAML file that describes the schema of a particular version. It defines the transformations that can be used to convert the telemetry data represented in any other older compatible version of the same schema family to this schema version. File Structure Here is the structure of the Schema File: # Defines the file format. MUST be set to 1.1.0. file_format: 1.1.0 # The Schema URL that this file is published at. The version number in the URL # MUST match th...| OpenTelemetry
Status: Development A Schema File is a YAML file that describes the schema of a particular version. It defines the transformations that can be used to convert the telemetry data represented in any other older compatible version of the same schema family to this schema version. File Structure Here is the structure of the Schema File: # Defines the file format. MUST be set to 1.0.0. file_format: 1.0.0 # The Schema URL that this file is published at. The version number in the URL # MUST match th...| OpenTelemetry
Contents Overview Glossary Principles and Guidelines Core Principles Versioning and stability for OpenTelemetry clients Library Guidelines Package/Library Layout General error handling guidelines Performance API Specification Context Propagators Environment Variable Carriers Baggage Tracing Metrics Logs API SDK Specification Tracing Metrics Logs Resource Configuration Data Specification Semantic Conventions Protocol Metrics Logs Profiles Compatibility OpenCensus OpenTracing Prometheus and Ope...| OpenTelemetry
Status: Stable, except where otherwise specified Tracer Provider Tracer Creation It SHOULD only be possible to create Tracer instances through a TracerProvider (see API). The TracerProvider MUST implement the Get a Tracer API. The input provided by the user MUST be used to create an InstrumentationScope instance which is stored on the created Tracer. Status: Development - The TracerProvider MUST compute the relevant TracerConfig using the configured TracerConfigurator, and create a Tracer who...| OpenTelemetry
Status: Stable This document defines the stability guarantees offered by the OpenTelemetry clients, along with the rules and procedures for meeting those guarantees. In this document, the terms “OpenTelemetry” and “language implementations” both specifically refer to the OpenTelemetry clients. These terms do not refer to the specification or the Collector in this document. Each language implementation MUST take these versioning and stability requirements, and produce a language-specif...| OpenTelemetry
Status: Stable Motivation Telemetry sources such as instrumented applications and consumers of telemetry such as observability backends sometimes make implicit assumptions about the emitted telemetry. They assume that the telemetry will contain certain attributes or otherwise have a certain shape and composition of data (this is referred to as “telemetry schema” throughout this document). This makes it difficult or impossible to change the composition of the emitted telemetry data without...| OpenTelemetry
Status: Stable, except where otherwise specified Overview The Metrics API consists of these main components: MeterProvider is the entry point of the API. It provides access to Meters. Meter is responsible for creating Instruments. Instrument is responsible for reporting Measurements. Here is an example of the object hierarchy inside a process instrumented with the metrics API: +-- MeterProvider(default) | +-- Meter(name='io.opentelemetry.runtime', version='1.0.0') | | | +-- Instrument(name='c...| OpenTelemetry
Status: Stable except where otherwise specified A Resource is an immutable representation of the entity producing telemetry as Attributes. For example, a process producing telemetry that is running in a container on Kubernetes has a Pod name, it is in a namespace and possibly is part of a Deployment which also has a name. All three of these attributes can be included in the Resource. Note that there are certain “standard attributes” that have prescribed meanings.| OpenTelemetry
Specification documents (files) may explicitly define a “Status”, typically shown immediately after the document title. When present, the “Status” applies to the individual document only and not to the entire specification or any other documents. The following table describes what the statuses mean. Maturity levels The support guarantees and allowed changes are governed by the maturity level of the document. Maturity levels are defined in OTEP 0232 and follow the OpenTelemetry project...| OpenTelemetry
The OpenTelemetry protocol (OTLP) design goals, requirements, and specification have moved to github.com/open-telemetry/opentelemetry-proto/docs. You can also view the specification from the OpenTelemetry website, see OTLP. For additional OTLP implementation requirements in the OpenTelemetry SDKs, see SDK Exporter.| OpenTelemetry
Status: Mixed Users of OpenTelemetry need a way for instrumentation interactions with the OpenTelemetry API to actually produce telemetry. The OpenTelemetry SDK (henceforth referred to as the SDK) is an implementation of the OpenTelemetry API that provides users with this functionally. All language implementations of OpenTelemetry MUST provide an SDK. MeterProvider Status: Stable A MeterProvider MUST provide a way to allow a Resource to be specified. If a Resource is specified, it SHOULD be a...| OpenTelemetry
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 i...| OpenTelemetry
Status: Mixed The following semantic conventions surrounding metrics are defined: General Guidelines: General metrics guidelines. Database: For SQL and NoSQL client metrics. FaaS: For Function as a Service metrics. GenAI: For Generative AI metrics. HTTP: For HTTP client and server metrics. Messaging: For messaging systems (queues, publish/subscribe, etc.) metrics. RPC: For RPC client and server metrics. .NET: For network-related metrics emitted by .NET runtime components. System metrics Syste...| OpenTelemetry
Status: Stable, except where otherwise specified The Tracing API consists of these main components: TracerProvider is the entry point of the API. It provides access to Tracers. Tracer is responsible for creating Spans. Span is the API to trace an operation. Data types While languages and platforms have different ways of representing data, this section defines some generic requirements for this API. Time OpenTelemetry can operate on time values up to nanosecond (ns) precision. The representati...| OpenTelemetry
Status: Stable This section applies to Resource, Span, Log, and Metric attribute names (also known as the “attribute keys”). For brevity within this section when we use the term “name” without an adjective it is implied to mean “attribute name”. Every name MUST be a valid Unicode sequence. Note: we merely require that the names are represented as Unicode sequences. This specification does not define how exactly the Unicode sequences are encoded. The encoding can vary from one prog...| OpenTelemetry
Status: Mixed Overview Status: Stable The OpenTelemetry data model for metrics consists of a protocol specification and semantic conventions for delivery of pre-aggregated metric timeseries data. The data model is designed for importing data from existing systems and exporting data into existing systems, as well as to support internal OpenTelemetry use-cases for generating Metrics from streams of Spans or Logs. Popular existing metrics data formats can be unambiguously translated into the Ope...| OpenTelemetry
Status: Mixed The conventions described in this section are HTTP specific. When HTTP operations occur, metric events about those operations will be generated and reported to provide insight into the operations. By adding HTTP attributes to metric events it allows for finely tuned filtering. Disclaimer: These are initial HTTP metric instruments and attributes but more may be added in the future. Warning Existing HTTP instrumentations that are using v1.20.0 of this document (or prior):| OpenTelemetry
Status: Stable Attribute An Attribute is a key-value pair, which MUST have the following properties: The attribute key MUST be a non-null and non-empty string. Case sensitivity of keys is preserved. Keys that differ in casing are treated as distinct keys. The attribute value is either: A primitive type: string, boolean, double precision floating point (IEEE 754-1985) or signed 64 bit integer. An array of primitive type values. The array MUST be homogeneous, i.| OpenTelemetry
Status: Stable, except where otherwise specified This is a data model and semantic conventions that allow to represent logs from various sources: application log files, machine generated events, system logs, etc. Existing log formats can be unambiguously mapped to this data model. Reverse mapping from this data model is also possible to the extent that the target log format has equivalent capabilities. The purpose of the data model is to have a common understanding of what a log record is, wh...| OpenTelemetry
Status: Stable for the trace, metric and log signals. Development for the profiles signal. The OpenTelemetry Protocol (OTLP) specification describes the encoding, transport, and delivery mechanism of telemetry data between telemetry sources, intermediate nodes such as collectors and telemetry backends. OTLP is a general-purpose telemetry data delivery protocol designed in the scope of the OpenTelemetry project. Protocol Details OTLP defines the encoding of telemetry data and the protocol used...| OpenTelemetry
Status: Stable except where otherwise specified The goal of this specification is to unify the environment variable names between different OpenTelemetry implementations. Implementations MAY choose to allow configuration via the environment variables in this specification, but are not required to. If they do, they SHOULD use the names listed in this document. Implementation guidelines Environment variables MAY be handled (implemented) directly by a component, in the SDK, or in a separate comp...| OpenTelemetry
OpenTelemetry is developed on a signal by signal basis. Tracing, metrics, baggage, and logging are examples of signals. Signals are built on top of context propagation, a shared mechanism for correlating data across distributed systems. Each signal consists of four core components: APIs SDKs OpenTelemetry Protocol (OTLP) Collector Signals also have contrib components, an ecosystem of plugins and instrumentation. All instrumentation shares the same semantic conventions, to ensure that they pro...| OpenTelemetry
This document provides an overview of the OpenTelemetry project and defines important fundamental terms. Additional term definitions can be found in the glossary. OpenTelemetry Client Architecture At the highest architectural level, OpenTelemetry clients are organized into signals. Each signal provides a specialized form of observability. For example, tracing, metrics, and baggage are three separate signals. Signals share a common subsystem – context propagation – but they function indepe...| OpenTelemetry