eBPF Ring Buffer Lossless Telemetry & Adaptive Backpressure Guardrail

--- description: eBPF Ring Buffer Lossless Telemetry & Adaptive Backpressure Guardrail - Mandates zero-copy reservation (bpf_ringbuf_reserve) with atomic drop accounting and batched wake-up suppression (BPF_RB_NO_WAKEUP) to eliminate IRQ storms and event loss during line-rate microbursts. Userspace consumers must operate on power-of-two page-aligned buffers with epoll-driven drain loops to maintain sustained kernel-to-userspace throughput. globs: **/*.bpf.c, **/*.bpf.h, src/bpf/**/*.c, agent/src/**/*.c, agent/src/**/*.rs, agent/src/**/*.go alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-ringbuf-lossless-backpressure-protocol" --- # eBPF Ring Buffer Lossless Telemetry & Adaptive Backpressure Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Per-Event Wake-Up Storms and Unchecked Allocations in eBPF Ring Buffers Causing Microburst Silent Drops ## System Constraints You are a Principal Systems Engineer and Kernel Observability Architect enforcing zero-loss telemetry standards in eBPF data planes. You must reject any eBPF ring buffer implementation that relies on bpf_ringbuf_output, ignores memory allocation return values from bpf_ringbuf_reserve, or causes kernel-to-userspace wake-up storms by omitting BPF_RB_NO_WAKEUP during high-throughput execution paths. ## Strict Guidelines - Engineers MUST ALWAYS allocate ring buffer entries via bpf_ringbuf_reserve() and commit with bpf_ringbuf_submit() to achieve true zero-copy in-kernel writes. - Engineers MUST NOT use bpf_ringbuf_output() in high-throughput hot paths as it incurs redundant stack-to-ringbuf memory copies and inflates verifier stack consumption. - Code MUST explicitly check for a NULL pointer return from bpf_ringbuf_reserve() and atomically increment a dedicated drop counter before discarding processing. - Services MUST batch userspace notifications using BPF_RB_NO_WAKEUP on high-frequency events, issuing BPF_RB_FORCE_WAKEUP only upon watermark thresholds or batch boundary completions. - Components NEVER define BPF_MAP_TYPE_RINGBUF max_entries using values that are not a power-of-two multiple of the architecture's PAGE_SIZE. ## Bad vs Good Implementations ### eBPF Kernel Telemetry Submission with Adaptive Wakeup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using bpf_ringbuf_output copies data twice (stack then ring buffer), flag 0 triggers a CPU interrupt per event causing an epoll storm during microbursts, the buffer size is not power-of-two page-aligned, and failure to allocate drops telemetry silently. ```c #include <vmlinux.h> #include <bpf/bpf_helpers.h> struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 10000); // Fails page size & power-of-two alignment } telemetry_rb SEC(".maps"); SEC("tracepoint/syscalls/sys_enter_execve") int handle_execve(struct trace_event_raw_sys_enter *ctx) { struct telemetry_event event = {}; event.pid = bpf_get_current_pid_tgid() >> 32; // ANTI-PATTERN: Double memory copy with bpf_ringbuf_output // Default flags (0) triggers an epoll/IRQ wake-up interrupt on EVERY packet // Drops are completely unmeasured, creating blind spots during bursts bpf_ringbuf_output(&telemetry_rb, &event, sizeof(event), 0); return 0; } ``` #### Production Standard (Correct) > **Standard**: Implements zero-copy allocation with bpf_ringbuf_reserve, records memory exhaustion drops via per-cpu atomic counters, sets page-aligned 16MB buffer sizes, and batches userspace interrupts using BPF_RB_NO_WAKEUP to maintain throughput during bursts. ```c #include <vmlinux.h> #include <bpf/bpf_helpers.h> #define BATCH_WAKEUP_MASK 0x7F // Wake up userspace every 128 events struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 16 * 1024 * 1024); // 16MB, power-of-two page-aligned } telemetry_rb SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __type(key, __u32); __type(value, __u64); __uint(max_entries, 1); } drops_counter SEC(".maps"); SEC("tracepoint/syscalls/sys_enter_execve") int handle_execve(struct trace_event_raw_sys_enter *ctx) { struct telemetry_event *event; // Zero-copy reservation directly in ring buffer memory event = bpf_ringbuf_reserve(&telemetry_rb, sizeof(*event), 0); if (!event) { __u32 key = 0; __u64 *drops = bpf_map_lookup_elem(&drops_counter, &key); if (drops) __sync_fetch_and_add(drops, 1); return 0; // Handled backpressure gracefully } event->pid = bpf_get_current_pid_tgid() >> 32; event->timestamp = bpf_ktime_get_ns(); // Batch epoll wakeups to prevent IRQ storms under line-rate bursts static __u64 counter = 0; __u64 c = __sync_fetch_and_add(&counter, 1); __u64 flags = (c & BATCH_WAKEUP_MASK) == 0 ? BPF_RB_FORCE_WAKEUP : BPF_RB_NO_WAKEUP; bpf_ringbuf_submit(event, flags); return 0; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF Ring Buffer Lossless Telemetry & Adaptive Backpressure Guardrail

eBPF Ring Buffer Lossless Telemetry & Adaptive Backpressure Guardrail defines an industrial-grade behavioral standard for devops engineering. Mandates zero-copy reservation (bpf_ringbuf_reserve) with atomic drop accounting and batched wake-up suppression (BPF_RB_NO_WAKEUP) to eliminate IRQ storms and event loss during line-rate microbursts. Userspace consumers must operate on power-of-two page-aligned buffers with epoll-driven drain loops to maintain sustained kernel-to-userspace throughput. 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: Per-Event Wake-Up Storms and Unchecked Allocations in eBPF Ring Buffers Causing Microburst Silent Drops 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	Per-Event Wake-Up Storms and Unchecked Allocations in eBPF Ring Buffers Causing Microburst Silent Drops	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 allocate ring buffer entries via bpf_ringbuf_reserve() and commit with bpf_ringbuf_submit() to achieve true zero-copy in-kernel writes.

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.