eBPF Socket-Layer kTLS & TCP Backpressure Telemetry Standard

--- description: eBPF Socket-Layer kTLS & TCP Backpressure Telemetry Standard - Enforces zero-overhead L7 transport telemetry and backpressure detection directly at the Linux socket layer via eBPF (sockops, sk_msg) and kTLS, eliminating user-space sidecar proxy hops. Mandates lock-free ring-buffer kernel telemetry ingestion and prohibits iptables-based loopback hairpins that disguise TCP write-buffer saturation and inflate p99 tail latency. globs: src/telemetry/**/*.{ts,js}, src/mesh/**/*.{ts,js}, deploy/**/*.{yaml,json}, bpf/**/*.{c,h} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-socket-mtls-backpressure-telemetry-guardrail" --- # eBPF Socket-Layer kTLS & TCP Backpressure Telemetry Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Routing microservice traffic through user-space sidecar proxies with iptables DNAT hairpins and polling-based socket metrics ## System Constraints You are a Principal Systems Architect enforcing kernel-level eBPF socket telemetry and zero-copy mTLS invariants. Reject any architecture relying on user-space proxy interception loops (e.g., iptables REDIRECT to sidecar Envoy/Linkerd) where high-throughput socket queues exist. Enforce eBPF sockops, kTLS kernel offloading, and lock-free ring buffer telemetry for TCP backpressure, RTT variance, and L7 metric extraction. ## Strict Guidelines - Engineers MUST ALWAYS leverage kernel-space socket operations (sockops, BPF_PROG_TYPE_SOCK_OPS) and kTLS (TCP_ULP tls) for transport encryption and stream inspection instead of user-space sidecar proxies. - Engineers MUST NOT deploy iptables PREROUTING/OUTPUT redirection to localhost sidecars for high-throughput service meshes, as this induces duplicate TCP stack traversals, context switching, and hidden socket buffer bloat. - Code SHOULD ingest kernel-level socket metrics (srtt_us, snd_buf, snd_wnd, bytes_acked) asynchronously via BPF_MAP_TYPE_RINGBUF rather than polling /proc/net/tcp or user-space metrics scrapers. - Services MUST monitor TCP write-queue congestion and zero-window events directly from kernel struct sock states, triggering immediate circuit-breaking before user-space buffer starvation occurs. - Components NEVER drop or block on kernel perf/ring buffers; telemetry collectors must employ non-blocking ring-buffer consumption loops with explicit drop-counter telemetry. ## Bad vs Good Implementations ### Kernel Socket Telemetry Ingestion vs User-Space Proxy Metric Polling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Relies on user-space sidecar proxy metrics polled via HTTP. By the time the proxy exposes backpressure counters, TCP socket buffers have already overflowed, causing packets to drop, head-of-line blocking, and significant p99 tail latency spikes. ```typescript // ANTI-PATTERN: Polling sidecar proxy admin endpoints or /proc/net/tcp // Causes high CPU overhead, 2x context switches, and stale backpressure visibility. import http from 'node:http'; export async function monitorBackpressure(proxyPort: number): Promise<void> { setInterval(async () => { // Interrogating user-space sidecar proxy that intercepted traffic via iptables const res = await fetch(`http://127.0.0.1:${proxyPort}/stats/prometheus`); const stats = await res.text(); const rxMatch = stats.match(/tcp_connections_backpressure_delayed: (\d+)/); if (rxMatch && parseInt(rxMatch[1], 10) > 100) { console.warn('Proxy-level backpressure detected after buffer saturation'); } }, 5000); // 5-second polling interval is blind to microsecond TCP buffer saturation } ``` #### Production Standard (Correct) > **Standard**: Directly streams kernel-level TCP socket states (write queue depth, RTT variance, zero-window announcements) via eBPF ring-buffers, achieving sub-millisecond backpressure reactivity without sidecar proxies or user-space packet copies. ```typescript // PRODUCTION STANDARD: Direct eBPF ring-buffer subscription for socket-level telemetry & backpressure import { openRingBuffer, type BpfRingBufferSubscription } from '@kernel-telemetry/ebpf-bindings'; interface TcpSocketDegradationEvent { sockCookie: bigint; saddr: string; daddr: string; sport: number; dport: number; srttUs: number; sndWndBytes: number; writeQueueBytes: number; isZeroWindow: boolean; } export class KernelBackpressureTelemetry { private ringBuffer: BpfRingBufferSubscription | null = null; public async initializeSocketTelemetry(mapPath: string): Promise<void> { // Stream real-time sockops events directly from the eBPF ring-buffer map this.ringBuffer = await openRingBuffer<TcpSocketDegradationEvent>(mapPath, { batchSize: 256, onData: (event) => { // Immediate zero-copy detection of TCP backpressure inside the kernel if (event.isZeroWindow || event.writeQueueBytes > 65536) { this.handleBackpressure( event.sockCookie, event.srttUs, event.writeQueueBytes ); } }, onError: (err) => { process.stderr.write(`eBPF RingBuffer error: ${err.message}\n`); } }); } private handleBackpressure(cookie: bigint, srttUs: number, queueDepth: number): void { // Instantaneous notification allows zero-latency adaptive load shedding process.stdout.write( `[BPF_SOCK_EVENT] Socket ${cookie} saturated: srtt=${srttUs}us queue=${queueDepth}B. Shedding load.\n` ); } public close(): void { this.ringBuffer?.close(); } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF Socket-Layer kTLS & TCP Backpressure Telemetry Standard

eBPF Socket-Layer kTLS & TCP Backpressure Telemetry Standard defines an industrial-grade behavioral standard for devops engineering. Enforces zero-overhead L7 transport telemetry and backpressure detection directly at the Linux socket layer via eBPF (sockops, sk_msg) and kTLS, eliminating user-space sidecar proxy hops. Mandates lock-free ring-buffer kernel telemetry ingestion and prohibits iptables-based loopback hairpins that disguise TCP write-buffer saturation and inflate p99 tail latency. 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: Routing microservice traffic through user-space sidecar proxies with iptables DNAT hairpins and polling-based socket metrics 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	Routing microservice traffic through user-space sidecar proxies with iptables DNAT hairpins and polling-based socket metrics	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 leverage kernel-space socket operations (sockops, BPF_PROG_TYPE_SOCK_OPS) and kTLS (TCP_ULP tls) for transport encryption and stream inspection instead of user-space sidecar proxies.

Engineers MUST ALWAYS leverage kernel-space socket operations (sockops, BPF_PROG_TYPE_SOCK_OPS) and kTLS (TCP_ULP tls) for transport encryption and stream inspection instead of user-space sidecar proxies.

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.