OpenTelemetry

Quick start

Thu, 27 Aug 2026 05:31:10 +0000

The OpenTelemetry Collector receives telemetry such as traces, metrics, and logs, processes it, and forwards it to one or more observability backends through its component pipeline.

Note

This quick start demo creates a basic local setup. The goal is to show you how the Collector works, not to set up a production-ready environment.

In this guide, you will:

Start a local instance of the OpenTelemetry Collector
Generate trace data and send it to the Collector
Check that the Collector receives and processes the data

By the end, you will have a simple pipeline running on your machine and a clearer idea of how the Collector fits into an observability stack. If you want more context before getting started, see the Collector overview.

Configure OBI export modes

Mon, 24 Aug 2026 20:08:18 +0000

Note

This page uses Config v1 field names and examples. For Config v2, see the Config v2 reference. To convert an existing file, use the migration guide.

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:

Set Up OpenTelemetry PHP Distro

Tue, 18 Aug 2026 21:29:20 +0000

Learn how to instrument your PHP application with OpenTelemetry PHP Distro and send telemetry data to an OTLP-compatible backend.

Prerequisites

Have a destination for telemetry data (OTLP endpoint).
Use a supported Linux distribution and PHP version.
Do not run another PHP APM or OpenTelemetry agent in the same process.

For supported operating systems and PHP versions, see Supported technologies.

Limitations

Known runtime and compatibility limitations are described in Limitations.

Configuration

Tue, 18 Aug 2026 21:29:20 +0000

OpenTelemetry PHP Distro supports standard OpenTelemetry SDK configuration and distro-specific options.

Configuration method

Configure via environment variables available to PHP processes:

OTEL_* for OpenTelemetry standard options
OTEL_PHP_* for distro-specific options

Example:

export OTEL_EXPORTER_OTLP_ENDPOINT="https://your-endpoint:443/"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"
export OTEL_PHP_LOG_LEVEL_STDERR="INFO"

OpenTelemetry options

The distro supports standard OpenTelemetry PHP SDK options.

Option	Default	Accepted values	Description
`OTEL_EXPORTER_OTLP_ENDPOINT`	`http://localhost:4318`	URL	OTLP endpoint URL
`OTEL_EXPORTER_OTLP_HEADERS`	(empty)	`key=value,key2=value2`	OTLP request headers
`OTEL_EXPORTER_OTLP_INSECURE`	`false`	`true` or `false`	Disable TLS verification (testing only)
`OTEL_EXPORTER_OTLP_CERTIFICATE`	(empty)	Filesystem path (PEM)	CA certificate path for OTLP TLS
`OTEL_EXPORTER_OTLP_CLIENT_CERTIFICATE`	(empty)	Filesystem path (PEM)	Client certificate for OTLP mTLS
`OTEL_EXPORTER_OTLP_CLIENT_KEY`	(empty)	Filesystem path (PEM)	Client key for OTLP mTLS
`OTEL_EXPORTER_OTLP_CLIENT_KEYPASS`	(empty)	String	Passphrase for encrypted OTLP client key
`OTEL_SERVICE_NAME`	`unknown_service`	String	Value of `service.name` resource attribute
`OTEL_RESOURCE_ATTRIBUTES`	(empty)	`key=value,key2=value2`	Resource attributes
`OTEL_TRACES_SAMPLER`	`parentbased_always_on`	Sampler name	Trace sampler
`OTEL_TRACES_SAMPLER_ARG`	(empty)	String/number	Sampler argument
`OTEL_LOG_LEVEL`	`info`	`error`, `warn`, `info`, `debug`	SDK internal log level

Distro-specific options (`OTEL_PHP_*`)

All OTEL_PHP_* options can be set as environment variables or in php.ini.

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.

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
- Versioning policy and stability guarantees
- File-based configuration model
  - YAML file format
  - Environment variable substitution

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:

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
- ConfigProvider
  - ConfigProvider operations
    - Get instrumentation config
- ConfigProperties

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:

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

Quick start

Configure OBI export modes

Set Up OpenTelemetry PHP Distro

Prerequisites

Limitations

Configuration

Configuration method

OpenTelemetry options

Distro-specific options (OTEL_PHP_*)

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

Entity Data Model

Configuration Data Model

Overview

Overview

OpenTelemetry Client Architecture

Tracing API

Data types

Time

Metrics API

Overview

MeterProvider

Logs API

Instrumentation Configuration API

Overview

Baggage API

Overview

OpenTelemetry mission, vision, and values

Mission

Vision

Distro-specific options (`OTEL_PHP_*`)

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