OpenTelemetry eBPF Kernel-Space Continuous Context Propagation Invariants

--- description: OpenTelemetry eBPF Kernel-Space Continuous Context Propagation Invariants - Enforces deterministic W3C trace context propagation and network topology discovery via eBPF kernel probes without runtime SDK overhead. Guards against context severance at user-space TLS encryption boundaries, thread scheduler asynchronous hops, and duplicate traceparent injection collisions. globs: k8s/**/*.yaml, deploy/**/*.{yaml,yml}, src/**/*.{ts,js,go,rs,py}, monitoring/**/*.{yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-ebpf-continuous-context-propagation-standard" --- # OpenTelemetry eBPF Kernel-Space Continuous Context Propagation Invariants > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Fragmented Distributed Traces and Context Severance Caused by Uncoordinated TLS Socket Probing and Manual Header Mutation ## System Constraints You are a Principal Architect enforcing OpenTelemetry zero-overhead observability via eBPF continuous context propagation. You must ensure that kernel-space probes (kprobes/tracepoints on tcp_sendmsg/sock_recvmsg) coordinate seamlessly with user-space probes (uprobes on libssl, BoringSSL, Go crypto/tls) and application network clients to preserve W3C Trace Context (traceparent/tracestate) across polyglot microservice topologies. ## Strict Guidelines - Engineers MUST configure eBPF agents to hook uprobes into user-space TLS libraries (e.g., OpenSSL, BoringSSL, Go runtime tls) prior to encryption, preventing uninstrumented encrypted payloads at raw socket kprobes. - Engineers MUST NOT manually mutate, discard, or generate pseudo-random W3C traceparent headers in application code when eBPF kernel-space auto-instrumentation is active. - Services MUST ensure asynchronous task boundaries and background worker threads propagate the active parent span context down to egress network call dispatchers to prevent eBPF uprobes from spawning orphaned root spans. - Deployments MUST mount cgroupv2 hierarchies and host PID namespaces with CAP_BPF, CAP_PERFMON, and CAP_NET_ADMIN capabilities to ensure deterministic socket-to-pod metadata correlation. - Components NEVER drop context headers on downstream HTTP/gRPC requests, guaranteeing that incoming W3C traceparent headers are passed unmodified through reverse proxies and service meshes. ## Bad vs Good Implementations ### TypeScript HTTP Dispatcher: Manual Context Tampering vs. eBPF Transparent Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Overwriting the traceparent with an ad-hoc generated ID severs the continuous trace chain established by eBPF kprobes on socket handshakes. It creates duplicate, disconnected trace roots and strips existing tracestate metadata. ```typescript import http from 'node:http'; import crypto from 'node:crypto'; export function dispatchOrderEvent(payload: Record<string, unknown>, host: string) { const data = JSON.stringify(payload); // ANTI-PATTERN: Generating fragmented synthetic trace context in user-space // overrides and corrupts continuous eBPF kernel-space W3C socket context propagation. const syntheticTraceId = crypto.randomBytes(16).toString('hex'); const syntheticSpanId = crypto.randomBytes(8).toString('hex'); const brokenTraceparent = `00-${syntheticTraceId}-${syntheticSpanId}-01`; const req = http.request({ hostname: host, port: 443, path: '/api/v1/orders', method: 'POST', headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data), 'traceparent': brokenTraceparent // Breaks kernel-level uprobe/kprobe correlation } }); req.write(data); req.end(); } ``` #### Production Standard (Correct) > **Standard**: Transparently forwards active W3C traceparent and tracestate headers across async hops, enabling eBPF user-space uprobes and kernel socket hooks to continuously stitch request spans without generating broken or orphaned traces. ```typescript import http from 'node:http'; import { AsyncLocalStorage } from 'node:async_hooks'; interface TracingContext { traceparent?: string; tracestate?: string; } export const tracingStorage = new AsyncLocalStorage<TracingContext>(); export function dispatchOrderEvent(payload: Record<string, unknown>, host: string) { const data = JSON.stringify(payload); const currentContext = tracingStorage.getStore(); const headers: Record<string, string | number> = { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(data) }; // INVARIANT: Preserve existing inbound W3C context across async boundaries // allowing eBPF uprobes (TLS) and kprobes (TCP) to continuously trace transparently. if (currentContext?.traceparent) { headers['traceparent'] = currentContext.traceparent; } if (currentContext?.tracestate) { headers['tracestate'] = currentContext.tracestate; } const req = http.request({ hostname: host, port: 443, path: '/api/v1/orders', method: 'POST', headers }); req.write(data); req.end(); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry eBPF Kernel-Space Continuous Context Propagation Invariants

OpenTelemetry eBPF Kernel-Space Continuous Context Propagation Invariants defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic W3C trace context propagation and network topology discovery via eBPF kernel probes without runtime SDK overhead. Guards against context severance at user-space TLS encryption boundaries, thread scheduler asynchronous hops, and duplicate traceparent injection collisions. 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: Fragmented Distributed Traces and Context Severance Caused by Uncoordinated TLS Socket Probing and Manual Header Mutation 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	Fragmented Distributed Traces and Context Severance Caused by Uncoordinated TLS Socket Probing and Manual Header Mutation	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 configure eBPF agents to hook uprobes into user-space TLS libraries (e.g., OpenSSL, BoringSSL, Go runtime tls) prior to encryption, preventing uninstrumented encrypted payloads at raw socket kprobes.

Engineers MUST configure eBPF agents to hook uprobes into user-space TLS libraries (e.g., OpenSSL, BoringSSL, Go runtime tls) prior to encryption, preventing uninstrumented encrypted payloads at raw socket kprobes.

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.