OpenTelemetry eBPF Instrumentation

OpenTelemetry libraries provide telemetry collection for popular programming languages and frameworks. However, getting started with distributed tracing can be complex. In some compiled languages like Go or Rust, you must manually add tracepoints to the code.

OpenTelemetry eBPF Instrumentation (OBI) is an auto-instrumentation tool to easily get started with Application Observability. OBI uses eBPF to automatically inspect application executables and the OS networking layer, and capture trace spans related to web transactions and Rate Errors Duration (RED) metrics for Linux HTTP/S and gRPC services. All data capture occurs without any modifications to application code or configuration.

OBI offers the following features:

• Wide language support: Java (JDK 8+), .NET, Go, Python, Ruby, Node.js, C, C++, and Rust
• Lightweight: No code changes required, no libraries to install, no restarts needed
• Efficient instrumentation: Traces and metrics are captured by eBPF probes with minimal overhead
• Distributed tracing: Distributed trace spans are captured and reported to a collector
• Log enrichment: Enrich JSON logs with trace context for correlation
• Kubernetes-native: Provides configuration-free auto-instrumentation for Kubernetes applications
• Visibility into encrypted communications: Capture transactions over TLS/SSL without decryption
• Context propagation: Propagate trace context across services automatically
• Protocol support: HTTP/S, gRPC, gRPC-Web, MQTT, Memcached, and more
• Database instrumentation: PostgreSQL (including pgx driver), MySQL, MongoDB, Redis, Couchbase (N1QL/SQL++ and KV protocol)
• GenAI instrumentation: Trace and metrics for OpenAI and Anthropic Claude API calls with automatic payload extraction
• Low cardinality metrics: Prometheus-compatible metrics with low cardinality for cost reduction
• Network observability: Capture network flows between services with host-level TCP RTT statistics
• Enhanced service discovery: Improved service name lookup with DNS resolution
• Collector integration: Run OBI as an OpenTelemetry Collector receiver component

Recent highlights (v0.7.0)

OBI v0.7.0 introduces several significant improvements:

• StatsO11y: New statistical metrics pipeline for host-level network statistics, starting with TCP RTT metrics
• Expanded protocol coverage: Added Memcached protocol tracing support
• Enhanced GenAI instrumentation: Added support for Anthropic Claude with automatic payload extraction
• Python asyncio improvements: Added context propagation support for Python asyncio workloads using uvloop
• New example scenario: Added an NGINX example covering direct routing, reverse proxying, and route-based telemetry across Docker, Kubernetes, and standalone deployments
• Prometheus exemplars: Support for exemplars in metrics export for better correlation with traces
• New span types: SQL instrumentation now emits server spans for database calls
• Operational controls: Added configurable log_format and Kubernetes API reconnect interval settings
• Network diagnostics: Added obi_bpf_network_ignored_packets_total for troubleshooting dropped network packets
• Release artifacts: CycloneDX SBOMs now included in release packages for supply chain security

For a complete list of changes and upgrade notes, see the release notes.

If you want to explore the new NGINX example, see the example walkthrough.

How OBI works

The following diagram shows the high-level OBI architecture and where eBPF instrumentation fits into the telemetry pipeline.

Compatibility

OBI supports Linux environments that meet the following requirements:

OBI publishes the following supported release artifacts:

OBI can be deployed on standalone Linux hosts, in containers, and on Kubernetes when the environment meets the requirements above.

OBI does not support non-Linux operating systems, Linux architectures other than amd64 and arm64, Linux environments without BTF, or kernel versions earlier than Linux 5.8 outside the documented RHEL-family 4.18+ exception.

Feature-specific support details are documented in these guides:

• Distributed traces: context propagation support, runtime-specific requirements, and distributed tracing limitations
• Export data: protocol, database, messaging, GenAI, GPU, and Go library instrumentation support

Limitations

OBI provides application and protocol observability without code changes, but it does not replace language-level instrumentation in every scenario. Use language agents or manual instrumentation when you need custom spans, application-specific attributes, business events, or other in-process telemetry that eBPF-based instrumentation cannot derive automatically.

OBI can automatically capture network and protocol activity, but it cannot always recover application-specific details that are not visible from eBPF observation points.

Some features also have additional caveats or narrower support than the core platform requirements. For details, refer to the feature-specific documentation for distributed traces and exported instrumentation.

For a comprehensive list of capabilities required by OBI, refer to Security, permissions and capabilities.

Get started with OBI

• Follow the setup documentation to get started with OBI either with Docker or Kubernetes.
• Learn about trace-log correlation to connect traces with application logs and enrich JSON logs with trace context.
• Discover how to run OBI as a Collector receiver for centralized telemetry processing.

Troubleshooting

• See the troubleshooting guide for help with common issues.