From 5c20f4e11447333d5125db685ced341c84471bde Mon Sep 17 00:00:00 2001 From: Mattia Meleleo Date: Tue, 27 Jan 2026 16:33:58 +0100 Subject: [PATCH 1/3] OTEP: correlating OBI traces to profiles Signed-off-by: Mattia Meleleo --- .../profiles/4855-profiles-obi-correlation.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 oteps/profiles/4855-profiles-obi-correlation.md diff --git a/oteps/profiles/4855-profiles-obi-correlation.md b/oteps/profiles/4855-profiles-obi-correlation.md new file mode 100644 index 00000000000..37c1d253902 --- /dev/null +++ b/oteps/profiles/4855-profiles-obi-correlation.md @@ -0,0 +1,38 @@ +# Correlating Profiles to OBI Traces + +This OTEP introduces a standard communication channel and a specification for correlating profiles to [opentelemetry-ebpf-instrumentation (OBI)](https://github.com/open-telemetry/opentelemetry-ebpf-instrumentation) traces. + + +* [Motivation](#motivation) +* [Design Notes](#design-notes) + * [Communication Channel](#communication-channel) + * [Data Model](#data-model) + + +## Motivation + +Currently, OBI traces and profiles operate independently, making it difficult to attribute profiling data to specific traces or spans. By establishing a standard kernel-resident communication channel, this OTEP enables: + +- Correlating profiles with their corresponding traces or spans +- End-to-end observability workflows without requiring application-level instrumentation + +## Design Notes + +### Communication Channel + +The communication channel between OBI and the profiler is implemented via an eBPF map pinned at `/sys/fs/bpf/obi_ctx`. + +For both programs to access the map, the `/sys/fs/bpf` filesystem (bpffs) must be mounted and accessible. + +### Data Model + +As described in the [Profiles Data Model](./0239-profiles-data-model.md), the shared eBPF map uses a minimal structure to store correlation data: + +- **Key:** `(u64)pid_tgid` +- **Value:** + +```c +struct trace_context { + u8 trace_id[16]; + u8 span_id[8]; +}; From 931904307373a61c02f1c03d7466ea310613a061 Mon Sep 17 00:00:00 2001 From: Mattia Meleleo Date: Thu, 29 Jan 2026 12:01:29 +0100 Subject: [PATCH 2/3] add review suggestions Signed-off-by: Mattia Meleleo --- .../profiles/4855-profiles-obi-correlation.md | 25 ++++++++++++++++--- 1 file changed, 22 insertions(+), 3 deletions(-) diff --git a/oteps/profiles/4855-profiles-obi-correlation.md b/oteps/profiles/4855-profiles-obi-correlation.md index 37c1d253902..abe8b5ba6ed 100644 --- a/oteps/profiles/4855-profiles-obi-correlation.md +++ b/oteps/profiles/4855-profiles-obi-correlation.md @@ -20,13 +20,31 @@ Currently, OBI traces and profiles operate independently, making it difficult to ### Communication Channel -The communication channel between OBI and the profiler is implemented via an eBPF map pinned at `/sys/fs/bpf/obi_ctx`. +The communication channel between OBI and the profiler is implemented via an eBPF map pinned at `$PINPATH/otel_traces_ctx_v1`. -For both programs to access the map, the `/sys/fs/bpf` filesystem (bpffs) must be mounted and accessible. +$PINPATH will default to bpffs (`/sys/fs/bpf`) but there must be options to specify an alternative location. If set, the user-configured + +location in OBI must match the one set in the profiler. + +On startup, both OBI and the profiler, will create the map and pin it if it doesn't exist. OBI will expose an helper function for the profiler + +to do so. ### Data Model -As described in the [Profiles Data Model](./0239-profiles-data-model.md), the shared eBPF map uses a minimal structure to store correlation data: +As described in the [Profiles Data Model](./0239-profiles-data-model.md), the shared eBPF map uses a minimal structure to store correlation data. + +#### eBPF Map Specification + +```c +struct { + __uint(type, BPF_MAP_TYPE_LRU_HASH); + __type(key, u64); + __type(value, struct trace_context); + __uint(max_entries, 1 << 14); + __uint(pinning, LIBBPF_PIN_BY_NAME); +} otel_traces_ctx_v1 SEC(".maps"); +``` - **Key:** `(u64)pid_tgid` - **Value:** @@ -36,3 +54,4 @@ struct trace_context { u8 trace_id[16]; u8 span_id[8]; }; +``` From 97076fdce828aea3583c93111ac77833ff42f18b Mon Sep 17 00:00:00 2001 From: Mattia Meleleo Date: Mon, 2 Feb 2026 12:58:21 +0100 Subject: [PATCH 3/3] add review suggestions Signed-off-by: Mattia Meleleo --- oteps/profiles/4855-profiles-obi-correlation.md | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/oteps/profiles/4855-profiles-obi-correlation.md b/oteps/profiles/4855-profiles-obi-correlation.md index abe8b5ba6ed..7facbd19ed5 100644 --- a/oteps/profiles/4855-profiles-obi-correlation.md +++ b/oteps/profiles/4855-profiles-obi-correlation.md @@ -20,19 +20,17 @@ Currently, OBI traces and profiles operate independently, making it difficult to ### Communication Channel -The communication channel between OBI and the profiler is implemented via an eBPF map pinned at `$PINPATH/otel_traces_ctx_v1`. +The communication channel between OBI and the profiler is implemented via an eBPF map pinned at `$PINPATH/otel/traces_ctx_v1`. $PINPATH will default to bpffs (`/sys/fs/bpf`) but there must be options to specify an alternative location. If set, the user-configured location in OBI must match the one set in the profiler. -On startup, both OBI and the profiler, will create the map and pin it if it doesn't exist. OBI will expose an helper function for the profiler - -to do so. +On startup, both OBI and the profiler, will create the map and pin it if it doesn't exist. ### Data Model -As described in the [Profiles Data Model](./0239-profiles-data-model.md), the shared eBPF map uses a minimal structure to store correlation data. +As described in the [Profiles Data Model](./0239-profiles-data-model.md), the shared eBPF map uses a minimal structure to store correlation data. OBI will be responsible of removing entries in order to avoid keeping stale contexts. #### eBPF Map Specification @@ -43,7 +41,7 @@ struct { __type(value, struct trace_context); __uint(max_entries, 1 << 14); __uint(pinning, LIBBPF_PIN_BY_NAME); -} otel_traces_ctx_v1 SEC(".maps"); +} traces_ctx_v1 SEC(".maps"); ``` - **Key:** `(u64)pid_tgid`