# OpenTelemetry eBPF Instrumentation > Learn how to use OpenTelemetry eBPF Instrumentation for automatic instrumentation. --- Site [llms.txt](/zh/llms.txt) --- 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, Rate Errors Duration (RED) metrics, runtime metrics, and application and network relationships for supported Linux workloads. 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 and plain-text 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 (client and server)**: HTTP/S, HTTP/2, gRPC, Kafka, NATS, MQTT, Memcached, SunRPC (including NFS), and JSON-RPC - **Protocol support (client only)**: AMQP 1.0 and DNS queries - **Database instrumentation (client and server)**: PostgreSQL (including the pgx driver), MySQL, MSSQL, and Redis - **Database instrumentation (client only)**: MongoDB, Couchbase (N1QL/SQL++ and KV protocol), Aerospike, Elasticsearch, and OpenSearch - **HTTP payload instrumentation**: Server-side GraphQL and client-side Elasticsearch, OpenSearch, AWS S3, and AWS SQS, plus MCP over JSON-RPC on both clients and servers - **GenAI instrumentation**: Trace and metrics for OpenAI, OpenAI-compatible gateways, Ollama, Anthropic Claude, Google AI Studio (Gemini), AWS Bedrock, Qwen (DashScope), MCP over JSON-RPC, embedding and rerank APIs, and vector retrieval systems - **Runtime metrics**: Collect Go, HotSpot JVM, and Node.js event-loop metrics without SDK changes - **GPU instrumentation**: Capture supported CUDA runtime operations on Linux - **Span and service graph metrics**: Export application span metrics and service-to-service relationships - **Low cardinality metrics**: Prometheus-compatible metrics with low cardinality for cost reduction - **Network observability**: Capture network flows between services with byte and packet counters, TCP RTT, retransmit, connection, and socket I/O metrics - **Enhanced service discovery**: Improved service name lookup with DNS resolution - **Collector integration**: Run OBI as an OpenTelemetry Collector receiver component ## Recent highlights (v0.12.1) OBI v0.12.1 is the published release of the changes prepared for v0.12.0. Although v0.12.0 was tagged, it was not published after release validation failed. Install v0.12.1, which includes the intended v0.12.0 changes and the release correction. Notable changes include: - **Node.js manual spans**: Captures spans created with `@opentelemetry/api` when the application has not registered an OpenTelemetry SDK - **Node.js runtime metrics**: Adds event-loop time, utilization, and delay metrics - **More precise Config v2 filters**: Applies application filters independently by protocol and signal - **Process-context enrichment**: Reads resource attributes and metadata that instrumented processes publish through the experimental `OTEL_CTX` mapping - **Database server metrics**: Adds `db.server.operation.duration` for server-side Redis, Memcached, and SQL operations - **Improved Java service names**: Uses the Spring Boot application name, JAR manifest title, or JAR base name before falling back to `java` - **Reliability fixes**: Protects private-stack kernels from uprobe preemption, avoids unsafe context propagation when a required probe cannot attach, and corrects trace parenting, wrapped Go TLS connections, short-lived process log enrichment, and OTLP attribute handling For a complete list of changes and upgrade notes, see the [release notes](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/releases/tag/v0.12.1). If you want to explore the upstream examples, see the [NGINX walkthrough](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/tree/v0.12.1/examples/nginx) and the [Apache walkthrough](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation/tree/v0.12.1/examples/apache). ## How OBI works The following diagram shows the high-level OBI architecture and where eBPF instrumentation fits into the telemetry pipeline. ![OBI eBPF architecture](./ebpf-arch.svg) ## Compatibility OBI supports Linux environments that meet the following requirements: | Requirement | Supported | | :--------------- | :-------------------------------------------------------------------- | | CPU architecture | `amd64`, `arm64` | | Linux kernel | `5.8+`, or RHEL-family Linux `4.18+` with the required eBPF backports | | Kernel features | BTF | | Privileges | Root, or the Linux capabilities required by the enabled OBI features | OBI publishes the following supported release artifacts: | Artifact | Supported platforms | | :-------------------------------------------------- | :--------------------------- | | `obi` binary archive | Linux `amd64`, Linux `arm64` | | `otel/ebpf-instrument` container image | Linux `amd64`, Linux `arm64` | | `otel/opentelemetry-ebpf-k8s-cache` container image | Linux `amd64`, Linux `arm64` | 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](distributed-traces/): context propagation support, runtime-specific requirements, and distributed tracing limitations - [Trace context association](context-propagation/): parent-child association support for asynchronous and threaded request handling - [Export data](configure/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](distributed-traces/) and [exported instrumentation](configure/export-data/). For a comprehensive list of capabilities required by OBI, refer to [Security, permissions and capabilities](security/). ## Get started with OBI - Follow the [setup](setup/) documentation to get started with OBI either with Docker or Kubernetes. - Learn about [trace-log correlation](./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](./configure/collector-receiver/) for centralized telemetry processing. ## Troubleshooting - See the [troubleshooting](./troubleshooting) guide for help with common issues. --- Section pages: - [Configure OBI](/zh/docs/zero-code/obi/configure/): Learn how to configure OBI. - [Network metrics](/zh/docs/zero-code/obi/network/): Configuring OBI to observe point-to-point network metrics. - [Set up OBI](/zh/docs/zero-code/obi/setup/): Learn how to set up and run OBI. - [OBI exported metrics](/zh/docs/zero-code/obi/metrics/): Learn about the application, runtime, and network metrics OBI can export. - [Distributed traces with OBI](/zh/docs/zero-code/obi/distributed-traces/): Learn about OBI's distributed traces support. - [Measuring total request times, instead of service times](/zh/docs/zero-code/obi/requesttime/): How to measure total request times from the point of view of the client - [OBI security, permissions, and capabilities](/zh/docs/zero-code/obi/security/): Privileges and capabilities required by OBI - [Troubleshooting](/zh/docs/zero-code/obi/troubleshooting/): Troubleshooting OBI common issues and errors - [OBI and Cilium compatibility](/zh/docs/zero-code/obi/cilium-compatibility/): Compatibility notes when running OBI alongside Cilium - [Trace context association in OBI](/zh/docs/zero-code/obi/context-propagation/): Learn how OBI associates outgoing requests with incoming parent requests for distributed traces. - [OBI metrics cardinality](/zh/docs/zero-code/obi/cardinality/): Overview of how to calculate the cardinality of metrics produced by a default OBI installation, considering the size and complexity of the instrumented environment. - [Trace-log correlation](/zh/docs/zero-code/obi/trace-log-correlation/): Learn how OBI correlates application logs with distributed traces for faster debugging and troubleshooting.