eBPF application auto-instrumentation with OBI
Collecting application metrics and traces usually means adding language-specific agents or modifying application code. OBI (OpenTelemetry eBPF-based instrumentation) simplifies this process using eBPF for automatic application instrumentation. Without any code changes, OBI inspects executables and the OS networking stack to capture trace spans for web traffic and RED (Rate, Errors, Duration) metrics in Linux-based HTTP/S and gRPC services.
Ready to get started?
See our Getting started guide for setup instructions.
Key capabilities
- Zero-code, kernel-level instrumentation: Captures traces and RED metrics with no code changes, library installs, or application restarts.
- Broad language and protocol coverage: Works across Java, .NET, Go, Python, Ruby, Node.js, C, C++, and Rust, spanning HTTP/S, gRPC, gRPC-Web, JSON-RPC, plus major database, messaging, search, and AI/LLM protocols.
- Distributed tracing with context propagation: Automatically captures, propagates, and forwards trace spans across services.
- Encrypted-traffic visibility: Monitors TLS/SSL transactions without decrypting content. HTTPS instrumentation is supported for Java, Node.js, and generic Go protocols.
- AI/LLM observability: Captures payloads for OpenAI, Google Gemini (AI Studio and Vertex AI), AWS Bedrock, Qwen (DashScope), MCP over JSON-RPC, embedding providers (Voyage AI, Cohere, Jina AI), and rerank providers. View the captured AI traffic in Coralogix AI Center.
- Kubernetes-first with auto-discovery and cloud enrichment: Deploys as a DaemonSet, automatically discovering services and enriching telemetry with Kubernetes and AWS/Azure/GCP metadata.
OBI enables scalable, vendor-neutral observability without invasive changes.
How OBI works
OBI runs as a DaemonSet on each Kubernetes node, capturing every packet transmitted or received at the kernel level with no sampling and no code changes. The agent categorizes traffic by protocol (detected from raw data or via the originating library), maps service-to-service connections, and enriches each interaction with OpenTelemetry conventions. Your OpenTelemetry collector then processes the spans and metrics and forwards them to Coralogix.
This is built on eBPF (extended Berkeley Packet Filter), a Linux kernel technology that safely executes custom logic in-kernel for observability, networking, and security, without modifying applications. OBI uses the OpenTelemetry eBPF instrumentation agent, now part of the official CNCF OpenTelemetry project (upstream documentation).
Key concepts
- DaemonSet: One agent runs on every Kubernetes node, ensuring cluster-wide visibility and scaling naturally as the cluster grows. See Kubernetes DaemonSets.
- Automatic service discovery: Detects new pods, containers, and services in real-time without manual configuration.
- Service naming: Uses Kubernetes metadata (
deployment,daemonset, orstatefulsetnames) as the service name. - Network observability: Captures latency, packet drops, and errors across inter-service communication.
For background on the underlying technology, see the eBPF Foundation.
System requirements
- Architecture: AMD64, ARM64
- Kernel version: 5.8 and above (with BTF enabled), or RHEL 4.18 kernels build 348+
Supported protocols
Changed in v0.8.0
OBI detects all listed protocols across all supported languages. All protocols support encrypted/secure variants except MQTT. Trace context is propagated automatically for HTTP; for other protocols, OBI emits spans but does not propagate context downstream.
| Protocol | Versions | Methods | Notes |
|---|---|---|---|
| HTTP | 1.0/1.1/2.0 | All | — |
| gRPC | 1.0+ | All | Methods for long-lived connections opened before OBI starts can't be retrieved and are marked *. |
| JSON-RPC | 2.0 | All | — |
| GraphQL | All | All | — |
| Database | Versions | Methods | Notes |
|---|---|---|---|
| MySQL | All | All | Prepared statements created before OBI starts may be missed. |
| PostgreSQL | All | All | Prepared statements created before OBI starts may be missed. |
| MSSQL | All | All | Query text may be missing if statements were prepared before OBI starts. |
| Database | Versions | Methods | Notes |
|---|---|---|---|
| MongoDB | 5.0+ | insert, update, find, delete, findAndModify, aggregate, count, distinct, mapReduce | No support for compressed payloads. |
| Redis | All | All | For connections opened before OBI starts, the database number can't be inferred and db.namespace isn't added. |
| Couchbase | All | All | Bucket unknown if SELECT_BUCKET happened before OBI started; collection unknown if GET_COLLECTION_ID happened before OBI started. Full query text is captured in db.query.text. |
| SQL++ | All | All | — |
| Protocol | Versions | Methods | Notes |
|---|---|---|---|
| Kafka | All | produce, fetch | May fail to get the topic name for fetch requests in newer Kafka (Fetch API version ≥ 13). |
| MQTT | 3.1.1, 5.0 | publish, subscribe | Not encrypted. Only the first topic filter is used; payload is not captured. |
| NATS | All | publish, subscribe | — |
| AMQP | 1.0 | publish, process | Only transfer performatives generate spans. |
| Engine | Versions | Methods |
|---|---|---|
| Elasticsearch | 7.14+ | /_search, /_msearch, /_bulk, /_doc |
| Opensearch | 3.0.0+ | /_search, /_msearch, /_bulk, /_doc |
| Service | Versions | Methods |
|---|---|---|
| AWS S3 | All | CreateBucket, DeleteBucket, PutObject, DeleteObject, ListBuckets, ListObjects, GetObject |
| AWS SQS | All | All |
| Provider | Versions | Methods |
|---|---|---|
| OpenAI | All | All |
| Google Gemini (AI Studio) | All | All |
| Vertex AI (Gemini) | All | All |
| AWS Bedrock | All | All |
| Qwen (DashScope) | All | All |
| MCP over JSON-RPC | All | All |
| Embedding providers (Voyage AI, Cohere, Jina AI) | All | All |
| Rerank providers | All | All |
Additional instrumentation features
Beyond baseline protocol detection, OBI ships built-in enhancements that deepen telemetry quality for specific languages and environments: richer Go library coverage, an embedded OpenTelemetry Java agent for JVM telemetry, and automatic cloud-provider metadata enrichment.
Go-specific instrumentations
New in v0.8.0
For Go applications, the agent provides enhanced instrumentation for specific libraries:
| Library | Support |
|---|---|
| Standard Go net/http | ✅ |
| Gorilla Mux | ✅ |
| Gin | ✅ |
| gRPC-Go | ✅ |
| Go x/net/http2 | ✅ |
| Go-Redis v9 | ✅ |
| Sarama Kafka | ✅ |
| Kafka-Go | ✅ |
Java agent integration
New in v0.6.0
OBI v0.6.0+ embeds the OpenTelemetry Java agent directly in the OBI binary. The Java agent is enabled by default — no extra flag or download is required. To disable it, set java.enabled: false in your OBI config or OTEL_EBPF_JAVAAGENT_ENABLED=false in the environment.
This provides richer Java telemetry (for example, JVM metrics, detailed span attributes) without requiring a separate Java agent download or configuration.
Cloud metadata decoration
New in v0.6.0
OBI automatically detects and enriches telemetry with cloud provider resource attributes when running in AWS, Azure, or GCP environments. This adds attributes such as cloud region, account ID, and instance metadata to your spans and metrics without additional configuration.
Benefits
Why teams adopt OBI over agent-based or SDK-based instrumentation. Expand each item for details. Traditional instrumentation setup can be time-consuming and requires deployment effort, especially across complex or distributed systems. With eBPF, monitoring starts immediately after deployment, capturing relevant metrics and events from the kernel without the need to instrument or redeploy applications. This rapid setup accelerates time-to-value for APM tools. eBPF enables an APM solution to provide in-depth, real-time visibility across all aspects of system performance and application behavior without impacting overall system efficiency, making it a highly effective choice for modern, production-grade observability. For certain applications, especially legacy systems or proprietary software, adding instrumentation via OpenTelemetry or other SDKs may not be possible. eBPF shines here, as it attaches directly to system calls or network events at the kernel level, capturing relevant data regardless of application type, language, or compatibility with instrumentation libraries. This capability is crucial in environments with heterogeneous services or closed-source applications, allowing APM solutions to gather necessary performance data for uninstrumented services without any dependency on application-level telemetry support. eBPF runs securely within the kernel, with limited permissions needed. It minimizes attack surface and doesn't require changes to applications. The OpenTelemetry eBPF instrumentation agent is vendor-neutral and open source, ensuring no vendor lock-in and allowing for community-driven development and improvements.Accelerated time-to-value
Real-time, system-wide observability with minimal overhead
Unrestricted monitoring for legacy and closed-source applications
Security
Vendor-neutral and open source
What's changed
OBI behavior changes that may affect existing dashboards, queries, and span filters. Review the relevant version before upgrading.
OBI v0.9.0
View v0.9.0 release notes
- Database error response reporting is now opt-in. OBI no longer captures database error response bodies by default. Enable it explicitly if you previously relied on those fields appearing on SQL spans.
For the full release notes, see OBI v0.9.0.
OBI v0.7.0+
View v0.7.0 release notes
The following defaults and behaviors changed in OBI v0.7.0. They affect existing dashboards, queries, and span filters, so review them when upgrading.
- SQL spans now use Server kind. Database spans for SQL instrumentations (MySQL, PostgreSQL, MariaDB) are emitted as
SERVERspans instead ofCLIENT. Update any trace or span filters that key on span kind for SQL operations. - DNS excluded from span and service-graph metrics by default. DNS calls no longer appear in span metrics or in the service graph. If you relied on DNS visibility there, expect those entries to disappear after upgrading.
- Ordinal port guessing disabled by default for network metrics. OBI no longer infers a service identity from ordinal source/destination ports on network flows. Existing queries built on guessed ports may return different results.
- HTTP header enrichment available as an opt-in feature. You can now capture selected HTTP request and response headers as span attributes. Configure under
ebpf.payload_extraction.http.enrichment(env:OTEL_EBPF_HTTP_ENRICHMENT_ENABLED), disabled by default. See the upstream OBI configuration reference for the full schema, including matching rules and obfuscation options.
For the full release notes, see OBI v0.7.0 and v0.7.1.
APM feature matrix
The table below compares the features supported by Coralogix APM with full OpenTelemetry integration versus those of the eBPF-based APM.
| Feature (K8s environments only) | eBPF | Full OpenTelemetry |
|---|---|---|
| Service catalog | ✅ | ✅ |
| Database catalog | ✅ | ✅ |
| Service map (only for Events2Metrics as metrics data source) | ✅ | ✅ |
| Metrics contextualization | ✅ | ✅ |
| Service alerts | ✅ | ✅ |
| SLOs | ✅ | ✅ |
| Apdex | ✅ | ✅ |
| Span - log correlation | ✅ | ✅ |
| API error tracking | ✅ | ✅ |
| Service - log correlation | ✅ | ✅ |
| K8s resources correlation | ✅ | ✅ |
| Serverless monitoring | ❌ | ✅ |
| Transactions | ✅ | ✅ |
| Spans exploration | ✅ | ✅ |
| Traces exploration | ✅ | ✅ |
| Trace map | ✅ | ✅ |
| Sampling | ✅ | ✅ |
| Span metrics | ✅ | ✅ |
Additional resources
- Zero Instrumentation with OBI
- OpenTelemetry eBPF Instrumentation GitHub Repository
- OTel Documentation
- eBPF Foundation
- Troubleshooting OBI common issues and errors