OpenTelemetry

Deploy OBI in Kubernetes with Helm

Fri, 16 Oct 2026 12:20:11 +0000

নোট

For more details about the diverse Helm configuration options, check out the OBI Helm chart documentation or browse the chart on Artifact Hub. For detailed configuration parameters, see the values.yaml file.

Contents:

Deploying OBI from helm
Configuring OBI
Configuring OBI metadata
Centralizing Kubernetes metadata with k8s-cache
Providing secrets to the Helm configuration

Deploying OBI from helm

First, you need to add the OpenTelemetry helm repository to Helm:

Run OBI as a Docker container

Thu, 08 Oct 2026 19:58:07 +0000

OBI can run a standalone Docker container that can instrument a process running in another container.

OBI container images are published to both registries:

Docker Hub: otel/ebpf-instrument:v<version>
GHCR: ghcr.io/open-telemetry/opentelemetry-ebpf-instrumentation/ebpf-instrument:v<version>

The development tag is also published on Docker Hub as:

otel/ebpf-instrument:main

The OBI container must be configured in following way:

run as a privileged container, or as a container with the SYS_ADMIN capability (but this last option might not work in some container environments)
Use the host PID namespace to allow accessing to the processes in other containers.

Image Signing and Verification

The OBI container image is signed using Cosign with ephemeral keys, authenticated via the OIDC (OpenID Connect) protocol in GitHub Actions. This ensures the authenticity and integrity of the container published by the OpenTelemetry project.

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.

নোট

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.

OBI Config v2 reference

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

Config v2 is available in OBI v0.11.0 and later. It uses the OpenTelemetry declarative configuration structure. Common settings such as resources, sampling, and exporters remain at the root of the document, while OBI-specific settings are grouped under extensions.obi.

If you already have a Config v1 file, use the Config v1 to v2 migration guide instead of rewriting it by hand.

Choose a configuration structure

How you structure the configuration depends on how you run OBI:

OBI global configuration properties

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

নোট

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

OBI can be configured via environment variables or via a YAML configuration file passed either with the -config command-line argument or the OTEL_EBPF_CONFIG_PATH environment variable. Environment variables have priority over the properties in the configuration file. For example, in the following command line, the OTEL_EBPF_LOG_LEVEL option overrides any log_level settings inside config.yaml:

Configure OBI export modes

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

নোট

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:

Performance Overhead

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

This page outlines performance implications of using OpenTelemetry PHP Distro and provides guidance for minimizing overhead.

Like any instrumentation agent, the distro runs in application processes and adds runtime cost. The exact impact depends on architecture, configuration, deployment environment, and workload.

The benchmark below compares multiple PHP observability variants in a local Docker setup (PHP-FPM 8.2 + NGINX). In scenarios with a collector, the collector also runs locally and shares host CPU resources.

Supported Technologies

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

OpenTelemetry PHP Distro is a distribution of OpenTelemetry PHP. It inherits OpenTelemetry compatibility and extends runtime features with native components.

Auto-instrumentation scope

Auto-instrumentation captures telemetry for supported frameworks and libraries, but it does not instrument:

Proprietary or custom framework internals
Closed-source components without instrumentation hooks
Application-specific business logic

For unsupported areas, use manual OpenTelemetry instrumentation.

PHP versions

Supported PHP versions: 8.1 to 8.5.

Supported SAPIs

php-cli
php-fpm
php-cgi/fcgi
mod_php (prefork)

Supported operating systems

Linux
- Architectures: x86_64, arm64
- glibc-based systems: deb, rpm
- musl-based systems (Alpine): apk

Instrumented frameworks

Laravel 6.x to 13.x
Slim 4.x

Instrumented libraries

cURL
HTTP async (php-http/httplug)
MySQLi
PDO
PostgreSQL
PSR-18 HTTP Client (psr/http-client)

Included auto-instrumentation packages

Name	Included from distro version	Package
`curl`	1.0	open-telemetry/opentelemetry-auto-curl
`http-async-client`	1.0	open-telemetry/opentelemetry-auto-http-async
`laravel`	1.0	open-telemetry/opentelemetry-auto-laravel
`mysqli`	1.0	open-telemetry/opentelemetry-auto-mysqli
`pdo`	1.0	open-telemetry/opentelemetry-auto-pdo
`postgresql`	1.2	open-telemetry/opentelemetry-auto-postgresql
`psr18`	0.5	open-telemetry/opentelemetry-auto-psr18
`slim`	1.0	open-telemetry/opentelemetry-auto-slim

Included metrics packages

Included from distro version	Package	Emitted metrics
0.6.0	open-telemetry/opentelemetry-metrics-runtime	PHP memory usage, GC cycles, peak memory

Additional runtime features

Automatic root span creation
Root span URL grouping
Inferred spans
Attribute-based instrumentation (#[WithSpan], #[SpanAttribute])
Background telemetry sending
PHP runtime metrics (memory, GC — exported automatically via the native async transport)

Background sending (non-blocking export) works with OTLP http/protobuf (default). If the exporter or protocol is changed to an unsupported transport (for example gRPC), export becomes synchronous.

Limitations

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

This page describes known limitations and constraints of OpenTelemetry PHP Distro.

Running with another PHP telemetry agent

Do not run OpenTelemetry PHP Distro together with another PHP APM or OpenTelemetry agent in the same process. Running both can cause conflicts, duplicate instrumentation, and unstable behavior.

`open_basedir`

If open_basedir is enabled in php.ini, the distro installation path must be included in allowed paths, otherwise the agent may fail to load.

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.

Logs

Fri, 07 Aug 2026 01:33:39 -0700

A log is a timestamped text record, either structured (recommended) or unstructured, with optional metadata. Of all telemetry signals, logs have the biggest legacy. Most programming languages have built-in logging capabilities or well-known, widely used logging libraries.

OpenTelemetry logs

OpenTelemetry provides a Logs API and SDK for producing log records, and language SDKs and logging bridges to integrate with existing logging frameworks. Logs are anything you send through a Logging Provider, and events are a special type of logs. Not all logs are events, but all events are logs. The Logs API is public and can be used directly by application code or indirectly via existing logging libraries and bridges.

Metrics

Thu, 02 Jul 2026 12:10:42 +0530

A metric is a measurement of a service captured at runtime. The moment of capturing a measurement is known as a metric event, which consists not only of the measurement itself, but also the time at which it was captured and associated metadata.

Application and request metrics are important indicators of availability and performance. Custom metrics can provide insights into how availability indicators impact user experience or the business. Collected data can be used to alert of an outage or trigger scheduling decisions to scale up a deployment automatically upon high demand.

OBI Network Metrics configuration options

Thu, 23 Apr 2026 01:01:38 -0700

Network metrics are configured under the network property of the OBI Configuration YAML file or with a set of environment variables prefixed as OTEL_EBPF_NETWORK_.

Example YAML:

network:
 enable: true
 cidrs:
 - 10.10.0.0/24
 - 10.0.0.0/8
 - 10.30.0.0/16
attributes:
 kubernetes:
 enable: true
 select:
 obi_network_flow_bytes:
 include:
 - k8s.src.owner.name
 - k8s.src.namespace
 - k8s.dst.owner.name
 - k8s.dst.namespace
 - src.cidr
 - dst.cidr
otel_metrics_export:
 endpoint: http://localhost:4318

In addition to the network YAML section, OBI configuration requires an endpoint to export the network metrics (in the previous example, otel_metrics_export, but it also accepts a Prometheus endpoint).

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:

নোট

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

নোট

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.

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.

OpenTelemetry

Deploy OBI in Kubernetes with Helm

Deploying OBI from helm

Run OBI as a Docker container

Image Signing and Verification

Quick start

OBI Config v2 reference

Choose a configuration structure

OBI global configuration properties

Configure OBI export modes

Performance Overhead

Supported Technologies

Auto-instrumentation scope

PHP versions

Supported SAPIs

Supported operating systems

Instrumented frameworks

Instrumented libraries

Included auto-instrumentation packages

Included metrics packages

Additional runtime features

Limitations

Running with another PHP telemetry agent

open_basedir

Set Up OpenTelemetry PHP Distro

Prerequisites

Limitations

Configuration

Configuration method

OpenTelemetry options

Distro-specific options (OTEL_PHP_*)

Logs

OpenTelemetry logs

Metrics

OBI Network Metrics configuration options

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

Prerequisites

Sign the CNCF CLA

`open_basedir`

Distro-specific options (`OTEL_PHP_*`)

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