OpenTelemetry

Run OBI as a Docker container

Tue, 07 Apr 2026 15:43:33 -0700

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.

OBI Network Metrics configuration options

Mon, 06 Apr 2026 03:41:58 -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).

OBI global configuration properties

Mon, 30 Mar 2026 12:18:35 +0200

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:

Config argument:

OTEL_EBPF_LOG_LEVEL=debug obi -config /path/to/config.yaml

Config environment variable:

OTEL_EBPF_LOG_LEVEL=debug OTEL_EBPF_CONFIG_PATH=/path/to/config.yaml obi

Refer to the example YAML configuration file for a configuration file template.

Profiles

Mon, 23 Mar 2026 13:05:23 +0100

Status: Alpha

A profile is a collection of samples and associated metadata that shows where applications consume resources during execution. A sample records values encountered in some program context (typically a stack trace), optionally augmented with auxiliary information like the trace ID corresponding to a higher-level request.

The moment of capturing a sample is known as a sample event and consists not only of the observation data point, but also the time at which it was captured.

Migrating from OpenCensus

Thu, 19 Mar 2026 06:58:46 -0700

Migrating from OpenTracing

Thu, 19 Mar 2026 06:58:46 -0700

Backward compatibility with OpenTracing has been a priority for the OpenTelemetry project from the start. To ease migration, OpenTelemetry supports the use of both the OpenTelemetry and OpenTracing APIs in the same codebase. This allows OpenTracing instrumentation to be recorded using OpenTelemetry SDKs.

To accomplish this, each OpenTelemetry SDK provides an OpenTracing shim, which acts as a bridge between the OpenTracing API and the OpenTelemetry SDK. Note that OpenTracing shims are disabled by default.

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.

Deploy OBI in Kubernetes

Tue, 24 Feb 2026 02:36:21 +0530

নোট

This document explains how to manually deploy OBI in Kubernetes, setting up all the required entities by yourself.

Configuring Kubernetes metadata decoration

OBI can decorate your traces with the following Kubernetes labels:

k8s.namespace.name
k8s.deployment.name
k8s.statefulset.name
k8s.replicaset.name
k8s.daemonset.name
k8s.node.name
k8s.pod.name
k8s.container.name
k8s.pod.uid
k8s.pod.start_time
k8s.cluster.name

To enable metadata decoration, you need to:

Baggage

Sun, 22 Feb 2026 10:36:00 -0500

In OpenTelemetry, Baggage is contextual information that resides next to context. Baggage is a key-value store, which means it lets you propagate any data you like alongside context.

Baggage means you can pass data across services and processes, making it available to add to traces, metrics, or logs in those services.

Example

Baggage is often used in tracing to propagate additional data across services.

For example, imagine you have a clientId at the start of a request, but you’d like for that ID to be available on all spans in a trace, some metrics in another service, and some logs along the way. Because the trace may span multiple services, you need some way to propagate that data without copying the clientId across many places in your codebase.

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.

Deploy OBI in Kubernetes with Helm

Mon, 26 Jan 2026 02:42:14 -0800

নোট

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
Providing secrets to the Helm configuration

Deploying OBI from helm

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

Logs

Tue, 20 Jan 2026 17:54:28 +0000

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.

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.

Metrics

Tue, 15 Jul 2025 18:17:55 +0200

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.

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.

Getting Started

Fri, 21 Mar 2025 16:06:24 -0400

This page will show you how to get started with OpenTelemetry .NET Automatic Instrumentation.

If you are looking for a way to manually instrument your application, check out this guide.

You will learn how you can instrument a simple .NET application automatically, in such a way that traces, metrics and logs are emitted to the console.

Prerequisites

Ensure that you have the following installed locally:

.NET SDK 6+

Example Application

The following example uses a basic Minimal API with ASP.NET Core application. If you are not using ASP.NET Core, that’s OK — you can still use OpenTelemetry .NET Automatic Instrumentation.

OpenTelemetry

Run OBI as a Docker container

Image Signing and Verification

OBI Network Metrics configuration options

OBI global configuration properties

Profiles

Migrating from OpenCensus

Migrating from OpenTracing

Configure OBI export modes

Configure and run OBI

Deploy OBI in Kubernetes

Configuring Kubernetes metadata decoration

Baggage

Example

Quick start

Prerequisites

Getting started

Setup

Declarative configuration

Deploy OBI in Kubernetes with Helm

Deploying OBI from helm

Logs

OpenTelemetry logs

Traces

Measure traffic between Cloud availability zones

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

Getting Started

OBI network metrics quickstart

Metrics

Prerequisites

Sign the CNCF CLA

Getting Started

Prerequisites

Example Application

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