This repository provides eBPF instrumentation based on the OpenTelemetry standard. It provides a lightweight and efficient way to collect telemetry data using eBPF for user-space applications.

OpenTelemetry e-BPF Instrumentation is commonly referred to as OBI.

OBI is currently in Development. Users should expect breaking changes between minor releases while the project remains in v0.

If you are evaluating OBI for production use:

• pin to a specific semver release tag instead of relying on latest, which is a moving, non-stable tag
• review release notes before upgrading between minor versions
• expect configuration, behavior, supported environments, and emitted telemetry to change between v0 minor releases
• avoid assuming telemetry continuity for dashboards, alerts, or downstream processors before OBI declares those surfaces stable

For the project's versioning and stability policy, see VERSIONING.md.

Requirements:

• Docker
• GNU Make

1. First, generate all the eBPF Go bindings via make docker-generate. You need to re-run this make task each time you add or modify a C file under the bpf/ folder.
2. To run linter, unit tests: make fmt verify.
3. To run integration tests, run either:

make integration-test make integration-test-k8s make oats-test 

, or all the above tasks. Each integration test target can take up to 50 minutes to complete, but you can use standard go command-line tooling to individually run each integration test suite under the internal/test/integration and internal/test/integration/k8s folder.

Below are quick reference instructions for getting OBI up and running with binary downloads or container images. For comprehensive setup, configuration, and troubleshooting guidance, refer to the OpenTelemetry zero-code instrumentation documentation, which is the authoritative source of truth.

OBI provides pre-built binaries for Linux (amd64 and arm64). Download the latest release from the releases page.

Each release includes:

• obi-<version>-linux-amd64.tar.gz - Linux AMD64/x86_64 archive
• obi-<version>-linux-arm64.tar.gz - Linux ARM64 archive
• SHA256SUMS - Checksums for verification

# Set your desired version (find latest at https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases) VERSION=1.0.0 # Determine your architecture # For Intel/AMD 64-bit: amd64 # For ARM 64-bit: arm64 ARCH=amd64 # Change to arm64 for ARM systems # Download the archive for your architecture wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/obi-v${VERSION}-linux-${ARCH}.tar.gz # Download checksums wget https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/download/v${VERSION}/SHA256SUMS # Verify the archive sha256sum -c SHA256SUMS --ignore-missing # Extract the archive tar -xzf obi-v${VERSION}-linux-${ARCH}.tar.gz # The archive contains: # - obi: Main OBI binary # - k8s-cache: Kubernetes cache binary # - LICENSE: Project license # - NOTICE: Legal notices # - NOTICES/: Third-party licenses and attributions

After extracting the archive, you can install the binaries to a location in your PATH so they can be used from any directory.

The Java agent is embedded in the obi binary, so no separate Java agent JAR installation is required. At runtime, OBI extracts the embedded Java agent into the user cache directory (typically $XDG_CACHE_HOME/obi/java or ~/.cache/obi/java) and reuses a checksum-named cached file across runs.

The following example installs to /usr/local/bin, which is a standard location on most Linux distributions. You can install to any other directory in your PATH:

# Move binaries to a directory in your PATH sudo cp obi /usr/local/bin/ sudo cp k8s-cache /usr/local/bin/ # Verify installation obi --version

OBI is also available as container images:

# Set your desired version. export VERSION=1.0.0 # (Optional) Verify the signature of the container image cosign verify --certificate-identity-regexp 'https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/' --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' otel/ebpf-instrument:${VERSION} # Pull the image docker pull otel/ebpf-instrument:${VERSION} # Run OBI in a container # Note: OBI requires elevated privileges (--privileged) to instrument processes # See https://opentelemetry.io/docs/zero-code/obi/setup/docker/ for more details docker run --privileged otel/ebpf-instrument:${VERSION}

See CONTRIBUTING

OpenTelemetry eBPF Instrumentation is licensed under the terms of the Apache Software License version 2.0. See the license file for more details.