OpenTelemetry

Run OBI as a Docker container

Wed, 21 Oct 2026 23:50:30 +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 for the example below, or grant the capabilities required by the enabled features. Starting with v0.14.0, most probes do not require SYS_ADMIN; Go library-level context propagation and other user-memory-write features still do.
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.

OBI Network Metrics configuration options

Wed, 21 Oct 2026 23:50:30 +0000

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:

metrics:
 features: [network]
network:
 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).

OBI Config v2 reference

Wed, 21 Oct 2026 23:50:30 +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

Wed, 21 Oct 2026 23:50:30 +0000

Nota

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:

OBI network metrics quickstart

Wed, 21 Oct 2026 23:50:30 +0000

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.

Measure traffic between Cloud availability zones

Wed, 21 Oct 2026 23:50:30 +0000

Nota

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:

Configure OBI export modes

Wed, 21 Oct 2026 23:50:30 +0000

Nota

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.

For Direct mode, set the OTLP endpoint with OTEL_EXPORTER_OTLP_ENDPOINT. If the endpoint requires authentication, also set OTEL_EXPORTER_OTLP_HEADERS with the credentials.

Deploy OBI in Kubernetes with Helm

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

Nota

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:

Primeiros Passos

Wed, 07 Oct 2026 13:19:47 +0000

Esta página apresenta a forma mais rápida para começar a monitorar seu cluster Kubernetes com o OpenTelemetry. Ela focará na coleta de métricas e logs de clusters, nós, pods e contêineres Kubernetes, assim como habilitar o cluster para dar suporte a serviços que emitem dados OTLP.

Para ver o OpenTelemetry em ação com Kubernetes, o melhor lugar para começar é a OpenTelemetry Demo. O objetivo da demo é ilustrar a implementação do OpenTelemetry, mas ela não pretende ser um exemplo de como monitorar o Kubernetes em si. Depois de terminar este passo a passo, pode ser um experimento divertido instalar a demo e ver como todo o monitoramento responde a uma carga de trabalho ativa.

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.

Métricas

Fri, 03 Jul 2026 11:11:16 -0400

Uma métrica é uma medição de um serviço capturada em tempo de execução. O momento de captura dessa medição é conhecido como evento de métrica, que consiste não apenas na medição em si, mas também no momento em que ela foi capturada e os metadados associados.

Métricas de aplicação e de requisição são indicadores importantes de disponibilidade e desempenho. Métricas personalizadas podem fornecer insights sobre como os indicadores de disponibilidade impactam a experiência do usuário ou o negócio. Os dados coletados podem ser usados para alertar sobre uma interrupção ou desencadear decisões de escalonamento para aumentar automaticamente uma implantação em caso de alta demanda.

Logs

Thu, 04 Jun 2026 11:53:28 -0400

Um log é um registro de texto com marcação de data e hora, que pode ser tanto estruturado (recomendado) quanto não estruturado, e com metadados opcionais. Dentre os sinais de telemetria, os logs têm uma história mais consolidada. A maioria das linguagens de programação possuem recursos nativos ou bibliotecas bem conhecidas e amplamente utilizadas para gerar logs.

Logs do OpenTelemetry

O OpenTelemetry fornece uma API e SDK de Logs para produzir registros de log, e SDKs de linguagem e pontes de log (logging bridges) para integrar com frameworks de logging existentes. Logs são qualquer coisa que você envie através de um Logging Provider, e eventos são um tipo especial de logs. Nem todos os logs são eventos, mas todos os eventos são logs. A API de Logs é pública e pode ser usada diretamente pelo código da aplicação ou indiretamente por meio de bibliotecas de logging e pontes existentes.

Rastros

Thu, 04 Jun 2026 11:53:28 -0400

Os rastros nos fornecem uma visão geral do que acontece quando uma solicitação é feita para uma aplicação. Seja sua aplicação um monólito com um único banco de dados ou uma grande variedade de serviços, os rastros são essenciais para compreender o “caminho” completo que uma solicitação percorreu na sua aplicação.

Vamos explorar isso com três unidades de trabalho, representadas como Trechos:

Note

Os exemplos JSON a seguir não apresentam um formato específico, especialmente o OTLP/JSON, que é mais verboso.

Início rápido

Thu, 04 Jun 2026 11:53:28 -0400

O OpenTelemetry Collector recebe rastros, métricas e logs, processa a telemetria e a exporta para diversos backends de observabilidade utilizando seus componentes. Para uma visão geral conceitual do Collector, veja Collector.

Você aprenderá a fazer o seguinte em menos de cinco minutos:

Configurar e executar o OpenTelemetry Collector.
Enviar telemetria e vê-la sendo processada pelo Collector.

Pré-requisitos

Certifique-se de que seu ambiente de desenvolvimento tenha o seguinte. Esta página pressupõe que você esteja usando bash. Adapte as configurações e comandos conforme necessário para o seu shell de preferência.

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.

Pré-requisitos

Fri, 24 Oct 2025 10:43:45 -0300

Para contribuir com este repositório, você precisa estar familiarizado com as seguintes tecnologias e ferramentas:

git
GitHub
Markdown (CommonMark)
YAML

Para detalhes técnicos sobre como a documentação é construída e testada localmente, consulte a página de Desenvolvimento Local.

Assinatura do CNCF CLA

Todos os contribuidores do OpenTelemetry devem assinar o Contrato de Licença de Contribuidor (CLA) da Linux Foundation.

Os pull requests de contribuidores que não assinaram o CLA falharão nos testes automatizados. O nome e o e-mail que você fornecer devem corresponder aos encontrados no seu git config, e seu nome e e-mail do Git devem corresponder aos usados para assinar o CLA da CNCF.

OpenTelemetry

Run OBI as a Docker container

Image Signing and Verification

OBI Network Metrics configuration options

OBI Config v2 reference

Choose a configuration structure

OBI global configuration properties

OBI network metrics quickstart

Measure traffic between Cloud availability zones

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

Configure OBI export modes

Deploy OBI in Kubernetes with Helm

Deploying OBI from helm

Primeiros Passos

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_*)

Métricas

Logs

Logs do OpenTelemetry

Rastros

Início rápido

Pré-requisitos

Getting started

Setup

Declarative configuration

Pré-requisitos

Assinatura do CNCF CLA

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

`open_basedir`

Distro-specific options (`OTEL_PHP_*`)