Kernel-Level W3C Trace Context and Baggage Propagation via eBPF Socket Operations

--- description: Kernel-Level W3C Trace Context and Baggage Propagation via eBPF Socket Operations - Enforces deterministic extraction and injection of W3C Trace Context and Baggage at the Linux socket layer using eBPF sock_ops and sk_msg programs. Eliminates runtime bytecode instrumentation while guaranteeing parent-child lineage across uninstrumented processes and external native runtimes. Prevents TCP frame corruption and sequence desynchronization when parsing or splicing L7 headers in kernel space. globs: **/*.bpf.c, **/*.bpf.h, pkg/telemetry/**/*.go, src/telemetry/**/*.rs, deploy/daemonsets/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-ebpf-socket-baggage-propagation" --- # Kernel-Level W3C Trace Context and Baggage Propagation via eBPF Socket Operations > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Invasive Bytecode Modification or Uncoordinated Socket Splicing That Breaks HTTP/2/gRPC Framing ## System Constraints You are a Principal Software Architect enforcing zero-overhead, non-invasive observability via OpenTelemetry and eBPF. You mandate that distributed trace context and baggage propagation occur deterministically at the Linux kernel socket layer without bytecode tampering or stream corruption. ## Strict Guidelines - Engineers MUST ALWAYS parse HTTP/1.1 and HTTP/2 stream headers using bounded eBPF loops and verify sk_buff length before invoking bpf_skb_load_bytes or bpf_msg_pull_data. - Engineers MUST NOT perform direct linear payload mutation on established TCP streams without adjusting the socket sequence numbers via bpf_msg_push_data or userland proxy ring-buffer coordination. - Code SHOULD forward extracted W3C headers (traceparent, tracestate, baggage) through BPF ring buffers (BPF_MAP_TYPE_RINGBUF) to a localized userland OpenTelemetry collector daemon. - Services MUST reconcile kernel-observed socket events (connect, sendmsg, recvmsg) with userland OpenTelemetry spans using socket cookies (bpf_get_socket_cookie) as correlation identifiers. - Components NEVER drop baggage attributes when crossing asynchronous boundary transitions between kernel network queues and userland task runtimes. ## Bad vs Good Implementations ### eBPF Socket Context Extraction and Userland Correlation Bridge #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example assumes arbitrary socket payloads contain clean strings without matching against socket file descriptors or kernel cookies, omits W3C baggage extraction entirely, and fails to handle boundary fragmentation across multi-packet TCP segments. ```go // BAD: Naive socket reader reading partial buffers without socket cookie correlation, // truncating baggage, and dropping parent-child lineage for uninstrumented sockets. package telemetry import ( "context" "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/propagation" ) type KernelTraceBridge struct{} func (b *KernelTraceBridge) HandleRawSocketEvent(ctx context.Context, payload []byte) { // Directly parses buffer without verifying boundaries or correlating socket lifecycle headerStr := string(payload) carrier := propagation.MapCarrier{"traceparent": headerStr} // Fails to propagate baggage or handle W3C tracestate newCtx := otel.GetTextMapPropagator().Extract(ctx, carrier) _, span := otel.Tracer("ebpf-bridge").Start(newCtx, "untracked-socket-read") span.End() } ``` #### Production Standard (Correct) > **Standard**: The good example uses a composite propagator supporting both W3C TraceContext and Baggage, extracts structured HTTP headers tied to a unique kernel socket cookie and PID, and establishes verified lineage without mutating running process memory. ```go // GOOD: Robust userland eBPF event consumer validating socket cookie identity, // extracting full W3C TraceContext and Baggage, and correlating across kernel-to-user boundaries. package telemetry import ( "context" "strings" "go.opentelemetry.io/otel" "go.opentelemetry.io/otel/baggage" "go.opentelemetry.io/otel/propagation" "go.opentelemetry.io/otel/trace" ) type SocketContextEvent struct { SocketCookie uint64 PID uint32 Comm [16]byte RawHeaders []byte } type BpfTraceBridge struct { tracer trace.Tracer propagator propagation.TextMapPropagator } func NewBpfTraceBridge() *BpfTraceBridge { return &BpfTraceBridge{ tracer: otel.Tracer("ebpf-kernel-bridge"), propagator: propagation.NewCompositeTextMapPropagator( propagation.TraceContext{}, propagation.Baggage{}, ), } } func (b *BpfTraceBridge) ProcessSocketEvent(ctx context.Context, evt *SocketContextEvent) (context.Context, trace.Span) { carrier := propagation.MapCarrier{} lines := strings.Split(string(evt.RawHeaders), "\r\n") for _, line := range lines { parts := strings.SplitN(line, ": ", 2) if len(parts) == 2 { key := strings.ToLower(strings.TrimSpace(parts[0])) val := strings.TrimSpace(parts[1]) if key == "traceparent" || key == "tracestate" || key == "baggage" { carrier[key] = val } } } extractedCtx := b.propagator.Extract(ctx, carrier) bgg := baggage.FromContext(extractedCtx) ctxWithTrace, span := b.tracer.Start( extractedCtx, "socket.kernel_transit", trace.WithSpanKind(trace.SpanKindServer), ) span.SetAttributes( KernelSocketCookieAttr(evt.SocketCookie), KernelProcessIdAttr(evt.PID), ) _ = bgg // Baggage remains preserved in extractedCtx for downstream userland spans return ctxWithTrace, span } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kernel-Level W3C Trace Context and Baggage Propagation via eBPF Socket Operations

Kernel-Level W3C Trace Context and Baggage Propagation via eBPF Socket Operations defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic extraction and injection of W3C Trace Context and Baggage at the Linux socket layer using eBPF sock_ops and sk_msg programs. Eliminates runtime bytecode instrumentation while guaranteeing parent-child lineage across uninstrumented processes and external native runtimes. Prevents TCP frame corruption and sequence desynchronization when parsing or splicing L7 headers in kernel space. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Invasive Bytecode Modification or Uncoordinated Socket Splicing That Breaks HTTP/2/gRPC Framing Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Invasive Bytecode Modification or Uncoordinated Socket Splicing That Breaks HTTP/2/gRPC Framing	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS parse HTTP/1.1 and HTTP/2 stream headers using bounded eBPF loops and verify sk_buff length before invoking bpf_skb_load_bytes or bpf_msg_pull_data.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.