How eBPF intstrumentation actually works?

[buger]

Hello! I had a few questions about implementation, and wanted to check the code, but I can't find eBPF part 🤔
Are you depend on some third party project here, or this code is not part of this repo?

Thanks!

[edeNFed]

Hi @buger
You can find the eBPF source code here:
https://github.com/keyval-dev/opentelemetry-go-instrumentation

We recently donated this project to the OpenTelemetry community, therefore development is moving to this repo:
https://github.com/open-telemetry/opentelemetry-go-instrumentation

[Yamparala-Venkata-Gopi]

Great question! Here is how eBPF-based auto-instrumentation actually works under the hood.

The Core Mechanism: uprobes + eBPF programs

eBPF instrumentation does not modify your application binary or inject agents into your process. Instead, it attaches eBPF programs to uprobes — kernel-level hooks that fire when specific user-space functions are called.

Here is the flow end-to-end:

1. Uprobe attachment
The Odigos agent (running as a DaemonSet) identifies target processes and attaches eBPF programs to specific function entry/exit points in the binary — things like net/http.(*Transport).roundTrip, google.golang.org/grpc.(*ClientConn).Invoke, or database/sql.(*DB).QueryContext.

2. Data capture in kernel space
When your application calls one of these instrumented functions, the eBPF program runs in the kernel context of your process. It reads function arguments and return values directly from the stack/registers using BPF helpers — no code injection, no shared libraries, no JVM agents.

3. Ring buffer handoff
Captured data (HTTP method, URL, status code, timestamps, goroutine ID for context propagation) is written to a BPF ring buffer (or perf event array on older kernels). This is a zero-copy shared memory region between kernel and user space.

4. User-space reconstruction
A Go user-space process reads from the ring buffer continuously and reconstructs span data. Context propagation is handled by tracking goroutine IDs to trace context mappings, since Go does not have thread-local storage like Java or Python.

5. OTel export
The reconstructed spans are converted to OpenTelemetry format and exported via OTLP to your collector.

Why no code changes are needed
The uprobe fires at the kernel level regardless of what the application does. The instrumentation library maintains per-Go-version offsets since Go binary layout can shift between releases.

The tricky parts in practice:

• Goroutine scheduler makes context propagation non-trivial (goroutines are not 1:1 with OS threads)
• Go version changes can break uprobe offset calculations — hence per-version support tables
• TLS interception requires attaching at the crypto/tls layer before encryption happens

The eBPF kernel programs (.bpf.c files) and per-library instrumentors live in opentelemetry-go-instrumentation under internal/pkg/instrumentors/ — each subdirectory is a different library (http, grpc, sql, etc.) with its own uprobe attachment logic.