Kernel eBPF RingBuffer Allocation and Consumer Backpressure Bounding

--- description: Kernel eBPF RingBuffer Allocation and Consumer Backpressure Bounding - Enforces strict memory isolation, zero-allocation safety, and non-blocking backpressure contracts across kernel-to-userspace eBPF RingBuffer pipelines. Prohibits silent telemetry drops by mandating atomic per-CPU counter accounting on buffer starvation and enforces adaptive userspace wakeup thresholds to prevent CPU exhaustion. globs: **/*.bpf.c, **/*.bpf.h, src/bpf/**/*.c, pkg/ebpf/**/*.go, src/ebpf/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-ringbuf-backpressure-invariant" --- # Kernel eBPF RingBuffer Allocation and Consumer Backpressure Bounding > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unchecked RingBuffer Reservations and Silent Drop Telemetry Starvation Under Consumer Lag ## System Constraints You are a Principal Linux Kernel & Systems Architect enforcing zero-leak, bounded-memory eBPF telemetry pipelines. All kernel-side eBPF code interacting with BPF_MAP_TYPE_RINGBUF must strictly check allocation invariants, manage userspace wakeup pressure adaptively, and ensure observable drop telemetry via per-CPU counters without blocking hot kernel probe paths. ## Strict Guidelines - Engineers MUST ALWAYS verify the pointer returned by `bpf_ringbuf_reserve` against NULL before dereferencing or writing event data. - Engineers MUST ALWAYS record telemetry drops using a dedicated `BPF_MAP_TYPE_PERCPU_ARRAY` atomic counter when `bpf_ringbuf_reserve` or `bpf_ringbuf_output` yields NULL or -ENOSPC. - Engineers MUST NOT invoke `bpf_ringbuf_submit` with uninitialized or partially written memory structures; zero or fully populate structs prior to submission. - Kernel probes MUST NOT use `BPF_RB_FORCE_WAKEUP` on high-throughput event paths; engineers MUST employ `BPF_RB_NO_WAKEUP` or evaluate watermark batching thresholds to avert kernel-to-userspace context switch storms. - Userspace consumers MUST configure `ring_buffer__poll` with explicit bounded timeout budgets and drain loops to prevent upstream buffer fill states. - Components NEVER block, spin-wait, or attempt synchronous retries inside probe contexts when a ring-buffer reservation fails. ## Bad vs Good Implementations ### Unsafe RingBuffer Reservation vs. Resilient Non-Blocking Backpressure Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Dereferencing the reservation pointer without checking for NULL triggers kernel verifier rejections or kernel null-pointer panics on older kernels. Forcing wakeups on every event creates kernel scheduler thrashing, while silent drops during consumer starvation leave operators unaware of missing critical telemetry. ```c #include <vmlinux.h> #include <bpf/bpf_helpers.h> struct event { __u32 pid; char comm[16]; }; struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 256 * 1024); } events SEC(".maps"); SEC("tp/sched/sched_process_exec") int handle_exec(void *ctx) { struct event *e; // ANTI-PATTERN: No NULL check, silent telemetry drop, unthrottled wakeup storm e = bpf_ringbuf_reserve(&events, sizeof(*e), 0); e->pid = bpf_get_current_pid_tgid() >> 32; bpf_get_current_comm(&e->comm, sizeof(e->comm)); bpf_ringbuf_submit(e, BPF_RB_FORCE_WAKEUP); return 0; } ``` #### Production Standard (Correct) > **Standard**: Validates the allocation pointer to satisfy verifier constraints and isolate execution. Records dropped events into a per-CPU array to provide immediate observability into consumer lag, and utilizes BPF_RB_NO_WAKEUP to let the userspace epoll/poll loop consume events in high-throughput batches without context switch overhead. ```c #include <vmlinux.h> #include <bpf/bpf_helpers.h> struct event { __u32 pid; char comm[16]; }; struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 256 * 1024); } events SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __uint(max_entries, 1); __type(key, __u32); __type(value, __u64); } dropped_events SEC(".maps"); SEC("tp/sched/sched_process_exec") int handle_exec(void *ctx) { struct event *e; __u32 drop_key = 0; // Bound backpressure: reserve memory locklessly without blocking e = bpf_ringbuf_reserve(&events, sizeof(*e), 0); if (!e) { // Invariant: Account for every backpressure drop atomically per-CPU __u64 *drops = bpf_map_lookup_elem(&dropped_events, &drop_key); if (drops) { (*drops)++; } return 0; // Drop silently avoided; drop metrics preserved } e->pid = bpf_get_current_pid_tgid() >> 32; bpf_get_current_comm(&e->comm, sizeof(e->comm)); // Adaptive userspace notification: suppress forced context switches bpf_ringbuf_submit(e, BPF_RB_NO_WAKEUP); return 0; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Kernel eBPF RingBuffer Allocation and Consumer Backpressure Bounding

Kernel eBPF RingBuffer Allocation and Consumer Backpressure Bounding defines an industrial-grade behavioral standard for devops engineering. Enforces strict memory isolation, zero-allocation safety, and non-blocking backpressure contracts across kernel-to-userspace eBPF RingBuffer pipelines. Prohibits silent telemetry drops by mandating atomic per-CPU counter accounting on buffer starvation and enforces adaptive userspace wakeup thresholds to prevent CPU exhaustion. 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: Unchecked RingBuffer Reservations and Silent Drop Telemetry Starvation Under Consumer Lag 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	Unchecked RingBuffer Reservations and Silent Drop Telemetry Starvation Under Consumer Lag	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 verify the pointer returned by `bpf_ringbuf_reserve` against NULL before dereferencing or writing event 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.