OpenTelemetry

Configure OBI export modes

Fri, 27 Feb 2026 08:18:31 -0800

In Direct mode OBI pushes metrics and traces directly to a remote endpoint using the OpenTelemetry protocol (OTLP).

OBI can also expose a Prometheus HTTP endpoint ready to scrape, for example in pull mode.

To use Direct mode requires configuration with authentication credentials. Set the OTLP endpoint authentication credentials with these environment variables:

OTEL_EXPORTER_OTLP_ENDPOINT
OTEL_EXPORTER_OTLP_HEADERS

To run in Direct mode using the Prometheus scrape endpoint, see the configuration documentation.

Configure and run OBI

This tutorial assumes OBI and OTel Collector are running natively on the same host, so there is no need to secure the traffic nor provide authentication in the OTel Collector OTLP receiver.

Quick start

Sat, 21 Feb 2026 17:26:02 -0500

The OpenTelemetry Collector receives traces, metrics, and logs, processes the telemetry, and exports it to a wide variety of observability backends using its components. For a conceptual overview of the Collector, see Collector.

You are going to learn to do the following in less than five minutes:

Set up and run the OpenTelemetry Collector.
Send telemetry and see it processed by the Collector.

Prerequisites

Make sure that your developer environment has the following. This page assumes that you’re using bash. Adapt configuration and commands as necessary for your preferred shell.

Getting started

Thu, 29 Jan 2026 05:41:57 -0500

Setup

Download opentelemetry-javaagent.jar from Releases of the opentelemetry-java-instrumentation repository and place the JAR in your preferred directory. The JAR file contains the agent and instrumentation libraries.

Add -javaagent:path/to/opentelemetry-javaagent.jar and other config to your JVM startup arguments and launch your app:

Directly on the startup command:

java -javaagent:path/to/opentelemetry-javaagent.jar -Dotel.service.name=your-service-name -jar myapp.jar

Via the JAVA_TOOL_OPTIONS and other environment variables:

export JAVA_TOOL_OPTIONS="-javaagent:path/to/opentelemetry-javaagent.jar"
export OTEL_SERVICE_NAME="your-service-name"
java -jar myapp.jar

Declarative configuration

Declarative configuration uses a YAML file instead of environment variables or system properties. This is useful when you have many configuration options to set, or if you want to use configuration options that are not available as environment variables or system properties.

Traces

Wed, 14 Jan 2026 07:44:34 -0500

Traces give us the big picture of what happens when a request is made to an application. Whether your application is a monolith with a single database or a sophisticated mesh of services, traces are essential to understanding the full “path” a request takes in your application.

Let’s explore this with three units of work, represented as Spans:

Note

The following JSON examples do not represent a specific format, and especially not OTLP/JSON, which is more verbose.

Measure traffic between Cloud availability zones

Wed, 14 Jan 2026 07:44:34 -0500

Note

This feature is currently only available in Kubernetes clusters.

Traffic between Cloud Availability Zones might incur additional costs. OBI is able to measure it either by adding src.zone and dst.zone attributes to regular network metrics, or by providing a separate obi.network.inter.zone.bytes (OTel) / obi_network_inter_zone_bytes_total (Prometheus) metric.

Add `src.zone` and `dst.zone` attributes to regular network metrics

Source and destination availability zone attributes are disabled by default in OBI. To enable it, explicitly add them to the list of included network attributes in the OBI YAML configuration:

Getting Started

Thu, 08 Jan 2026 22:37:28 +0530

This page will walk you through the fastest way to get started monitoring your Kubernetes cluster using OpenTelemetry. It will focus on collecting metrics and logs for Kubernetes clusters, nodes, pods, and containers, as well as enabling the cluster to support services emitting OTLP data.

If you’re looking to see OpenTelemetry in action with Kubernetes, the best place to start is the OpenTelemetry Demo. The demo is intended to illustrate the implementation of OpenTelemetry, but it is not intended to be an example of how to monitor Kubernetes itself. Once you finish with this walkthrough, it can be a fun experiment to install the demo and see how all the monitoring responds to an active workload.

OBI network metrics quickstart

Tue, 16 Dec 2025 14:16:09 +0100

OBI can generate network metrics in any environment (physical host, virtual host, or container). It’s recommended to use a Kubernetes environment, as OBI is able to decorate each metric with the metadata of the source and destination Kubernetes entities.

The instructions in this quickstart guide focus on deploying directly to Kubernetes with the kubectl command line utility. This tutorial describes how to deploy OBI in Kubernetes from scratch. To use Helm, consult the Deploy OBI in Kubernetes with Helm documentation.

Specification Status Summary

Sun, 19 Oct 2025 10:20:20 +0300

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 produce the same data when observing common operations, such as HTTP requests.

Prerequisites

Tue, 15 Jul 2025 10:17:31 -0300

To contribute to this repository, you need to be familiar with the following techs and tools:

git
GitHub
Markdown (CommonMark)
YAML

For technical details concerning how the documentation is built and tested locally, see Development.

Sign the CNCF CLA

All OpenTelemetry contributors must sign the Linux Foundation Contributor License Agreement (CLA).

Pull requests from contributors who haven’t signed the CLA fail the automated tests. The name and email you provide must match those found in your git config, and your git name and email must match those used for the CNCF CLA.

Metrics Data Model

Mon, 01 Jan 0001 00:00:00 +0000

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 OpenTelemetry data model for metrics, without loss of semantics or fidelity. Translation from the Prometheus and Statsd exposition formats is explicitly specified.

Logs Data Model

Mon, 01 Jan 0001 00:00:00 +0000

Status: Stable

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, what data needs to be recorded, transferred, stored and interpreted by a logging system.

Entity Data Model

Mon, 01 Jan 0001 00:00:00 +0000

Status: Development

Entity represents an object of interest associated with produced telemetry: traces, metrics, profiles, or logs.

For example, telemetry produced using an OpenTelemetry SDK is normally associated with a service entity. Similarly, OpenTelemetry defines system metrics for a host. The host is the entity we want to associate metrics with in this case.

Entities may be also associated with produced telemetry indirectly. For example a service that produces telemetry is also related to a process in which the service runs, so we say that the service entity is related to the process entity. The process normally also runs on a host, so we say that the process entity is related to the host entity.

Configuration Data Model

Mon, 01 Jan 0001 00:00:00 +0000

Status: Stable

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:

Versioning policy and stability guarantees

See opentelemetry-configuration versioning policy.

Overview

Mon, 01 Jan 0001 00:00:00 +0000

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 independently from each other.

Tracing API

Mon, 01 Jan 0001 00:00:00 +0000

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 representation of those values is language specific.

Metrics API

Mon, 01 Jan 0001 00:00:00 +0000

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<Asynchronous Gauge, int>(name='cpython.gc', attributes=['generation'], unit='kB')
 | |
 | +-- instruments...
 |
 +-- Meter(name='io.opentelemetry.contrib.mongodb.client', version='2.3.0')
 |
 +-- Instrument<Counter, int>(name='client.exception', attributes=['type'], unit='1')
 |
 +-- Instrument<Histogram, double>(name='client.duration', attributes=['server.address', 'server.port'], unit='ms')
 |
 +-- instruments...

+-- MeterProvider(custom)
 |
 +-- Meter(name='bank.payment', version='23.3.5')
 |
 +-- instruments...

MeterProvider

Meters can be accessed with a MeterProvider.

Logs API

Mon, 01 Jan 0001 00:00:00 +0000

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. However, languages are also free to provide a more ergonomic API for direct usage.

The Logs API consist of these main components:

Instrumentation Configuration API

Mon, 01 Jan 0001 00:00:00 +0000

Status: Mixed

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 representation of a configuration mapping node.

ConfigProvider

Status: Development

Baggage API

Mon, 01 Jan 0001 00:00:00 +0000

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 restrictive than the W3C Baggage Specification, § 3.2.1.1 which allows duplicate entries for a given name.

OpenTelemetry mission, vision, and values

Mon, 01 Jan 0001 00:00:00 +0000

Mission

Our overall north star as a community

OpenTelemetry’s Mission: to enable effective observability by making high-quality, portable telemetry ubiquitous.

Vision

The world we imagine for OTel end-users

Effective observability is powerful because it enables developers to innovate faster while maintaining high reliability. But effective observability absolutely requires high-quality telemetry – and the performant, consistent instrumentation that makes it possible.

Telemetry in this context is the firehose of raw observational data streaming out of software applications, and while “high-quality telemetry” may be a requirement for excellent observability, it’s still unreasonable and unrealistic to expect developers of application software to add or maintain the necessary instrumentation on their own. That is a massive undertaking, and in practice it’s not “just code” – there is also necessary alignment around protocols and semantic conventions for tags, attributes, and other metadata to consider.

OpenTelemetry

Configure OBI export modes

Configure and run OBI

Quick start

Prerequisites

Getting started

Setup

Declarative configuration

Traces

Measure traffic between Cloud availability zones

Add src.zone and dst.zone attributes to regular network metrics

Getting Started

OBI network metrics quickstart

Specification Status Summary

Prerequisites

Sign the CNCF CLA

Metrics Data Model

Overview

Logs Data Model

Entity Data Model

Configuration Data Model

Overview

Versioning policy and stability guarantees

Overview

OpenTelemetry Client Architecture

Tracing API

Data types

Time

Metrics API

Overview

MeterProvider

Logs API

Instrumentation Configuration API

Overview

ConfigProvider

Baggage API

Overview

OpenTelemetry mission, vision, and values

Mission

Vision

Add `src.zone` and `dst.zone` attributes to regular network metrics