eBPF Ring Buffer Multi-Consumer Non-Blocking Memory Reclamation Standard

--- description: eBPF Ring Buffer Multi-Consumer Non-Blocking Memory Reclamation Standard - Enforces non-blocking memory reclamation and watermark-driven telemetry pacing across multi-consumer eBPF ring buffer architectures. Prevents kernel slab exhaustion during high-volume syscall storms by orchestrating lockless consumer draining, zero-copy commit timeouts, and automatic degradation tiers. Ensures security telemetry streaming remains lossless without risking host kernel panic or unbounded buffer backpressure. globs: src/**/*.{c,h,bpf.c,bpf.h}, pkg/ebpf/**/*.{go,rs,c}, daemon/telemetry/**/*.{go,rs,ts} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-ringbuf-nonblocking-reclamation-standard" --- # eBPF Ring Buffer Multi-Consumer Non-Blocking Memory Reclamation Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded BPF Ring Buffer Reservations and Blocking Polling Cascading into Kernel Slab Starvation ## System Constraints You are a Principal Systems & DevOps Engineer enforcing the eBPF Ring Buffer Multi-Consumer Non-Blocking Memory Reclamation Standard. You must ensure all eBPF kernel probes and userspace ingestion pipelines utilize lock-free allocations, non-blocking ringbuf reservations with explicit discard paths, adaptive polling epochs, and zero-allocation backpressure bounds. Never permit bpf_ringbuf_reserve calls without unconditional discard/submit pairs, and enforce strict watermark-triggered drainers to prevent kernel memory pressure. ## Strict Guidelines - Engineers MUST ALWAYS pair every `bpf_ringbuf_reserve` call with an unconditional `bpf_ringbuf_submit` or `bpf_ringbuf_discard` execution branch. - Engineers MUST NOT execute blocking operations, mutex locks, or dynamic userspace allocations within active ring buffer consumer polling loops. - Code SHOULD dynamically tune ring buffer wake-up watermarks (flags: `BPF_RB_NO_WAKEUP` vs `BPF_RB_FORCE_WAKEUP`) based on ingress syscall burst velocity. - Services MUST fall back to deterministic telemetry loss counters via non-allocating per-CPU arrays when `bpf_ringbuf_reserve` returns NULL under slab pressure. - Components NEVER hold uncommitted ring buffer reservation headers past the immediate kprobe or tracepoint execution context. ## Bad vs Good Implementations ### Kernel Ringbuf Allocation & Userspace Adaptive Consumer Loop #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Failing to discard an unused reservation leaves the memory pinned in the ring buffer. Under heavy syscall volume, uncommitted reservations prevent the producer from advancing write pointers, stalling userspace consumers and exhausting kernel vmalloc/slab allocations. ```c // ANTI-PATTERN: Indefinite reserve retention, no discard on downstream validation failure, // and blocking epoll without batch consumption guarantees. SEC("kprobe/sys_enter_execve") int trace_execve(struct trace_event_raw_sys_enter *ctx) { struct event_t *event; // Reserves memory in ring buffer without checking allocation limits or handling errors event = bpf_ringbuf_reserve(&telemetry_ringbuf, sizeof(*event), 0); if (!event) { // Silently fails, dropping telemetry with zero observability return 0; } event->pid = bpf_get_current_pid_tgid() >> 32; if (event->pid == 0) { // LEAK: Unsubmitted reservation locks ring buffer pages, depleting kernel slab return 0; } bpf_ringbuf_submit(event, 0); return 0; } ``` #### Production Standard (Correct) > **Standard**: Every reservation branch is explicitly terminated with either submit or discard. Memory drops are accurately accounted for via static per-CPU arrays, and BPF_RB_NO_WAKEUP mitigates expensive kernel context-switching during sustained telemetry bursts. ```c // PRODUCTION STANDARD: Bounded reservation, deterministic discard on error branches, // drop-counter accounting via per-CPU map, and adaptive wake-up throttling. SEC("kprobe/sys_enter_execve") int trace_execve(struct trace_event_raw_sys_enter *ctx) { struct event_t *event; __u32 key = 0; // Attempt non-blocking reservation event = bpf_ringbuf_reserve(&telemetry_ringbuf, sizeof(*event), 0); if (!event) { // Atomically increment per-CPU drop metric without memory allocation __u64 *drops = bpf_map_lookup_elem(&telemetry_drop_counter, &key); if (drops) { __sync_fetch_and_add(drops, 1); } return 0; } event->pid = bpf_get_current_pid_tgid() >> 32; if (event->pid == 0) { // Explicit reclamation: discard unneeded reservation immediately bpf_ringbuf_discard(event, 0); return 0; } // Adaptive notification: Suppress wake-up signals during active drain phase bpf_ringbuf_submit(event, BPF_RB_NO_WAKEUP); return 0; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF Ring Buffer Multi-Consumer Non-Blocking Memory Reclamation Standard

eBPF Ring Buffer Multi-Consumer Non-Blocking Memory Reclamation Standard defines an industrial-grade behavioral standard for devops engineering. Enforces non-blocking memory reclamation and watermark-driven telemetry pacing across multi-consumer eBPF ring buffer architectures. Prevents kernel slab exhaustion during high-volume syscall storms by orchestrating lockless consumer draining, zero-copy commit timeouts, and automatic degradation tiers. Ensures security telemetry streaming remains lossless without risking host kernel panic or unbounded buffer backpressure. 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: Unbounded BPF Ring Buffer Reservations and Blocking Polling Cascading into Kernel Slab Starvation 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	Unbounded BPF Ring Buffer Reservations and Blocking Polling Cascading into Kernel Slab Starvation	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 pair every `bpf_ringbuf_reserve` call with an unconditional `bpf_ringbuf_submit` or `bpf_ringbuf_discard` execution branch.

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.