eBPF TC Egress Telemetry Rate-Limiting & Ring Buffer Overflow Guardrail

--- description: eBPF TC Egress Telemetry Rate-Limiting & Ring Buffer Overflow Guardrail - Enforces bounded eBPF ring buffer reservations, non-blocking telemetry drops, and token-bucket rate limiting in Traffic Control (TC) egress hook paths. Prevents kernel memory exhaustion, NET_TX softirq CPU starvation, and network egress throughput degradation during high-volume packet bursts. Mandates that telemetry failures never fail open to packet rejection. 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-tc-egress-telemetry-rate-limiting-guardrail" --- # eBPF TC Egress Telemetry Rate-Limiting & Ring Buffer Overflow Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded per-packet eBPF ring buffer emissions in TC egress paths without drop counters or sampling, causing packet drop and softirq stalls. ## System Constraints You are a Principal Systems Engineer and Linux Kernel eBPF Architect. You strictly enforce safe telemetry emission patterns in Traffic Control (TC) egress filters. You must mandate pre-allocated ring buffers, per-CPU drop metrics, non-blocking reservations, strict fallback to packet forward (TC_ACT_OK) on telemetry backpressure, and zero allocation within the datapath. ## Strict Guidelines - Engineers MUST ALWAYS return TC_ACT_OK (or the intended forwarding decision) even when ring buffer reservation or submission fails. - Engineers MUST NOT emit telemetry per-packet unconditionally; high-throughput TC filters must implement token-bucket rate-limiting or power-of-two packet sampling. - Engineers MUST ALWAYS verify the pointer returned by bpf_ringbuf_reserve against NULL before writing payload data. - Engineers MUST pass the BPF_RB_NO_WAKEUP flag to bpf_ringbuf_submit in hot TC paths and handle wakeups through batched epoll/poll triggers to minimize IPI overhead. - Services MUST monitor telemetry drops via a dedicated BPF_MAP_TYPE_PERCPU_ARRAY counter map rather than attempting retry loops inside the eBPF hook. - Ring buffers MUST be sized as page-aligned powers of two (e.g., 2^N pages) and bounded by configured cgroup/kernel memlock limits. ## Bad vs Good Implementations ### Unbounded Ring Buffer Emission in TC Egress Hook vs Bounded Rate-Limited Pattern #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The bad example attempts to reserve ring buffer space on every single packet without sampling or rate-limiting. When the ring buffer fills during a burst, bpf_ringbuf_reserve returns NULL, causing the program to erroneously drop actual network packets with TC_ACT_SHOT. Additionally, submitting with 0 flags causes frequent kernel wakeups and high IPI overhead under load. ```c #include <linux/bpf.h> #include <linux/pkt_cls.h> #include <bpf/bpf_helpers.h> struct event_t { __u32 len; __u32 ifindex; }; struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 1 << 20); // 1MB } events SEC(".maps"); SEC("tc/egress") int tc_egress_telemetry(struct __sk_buff *skb) { struct event_t *evt; // CRITICAL BUG: Allocating on every single packet without rate limiting or sampling. // In high-traffic bursts, this exhausts the ring buffer and softirq stalls occur. evt = bpf_ringbuf_reserve(&events, sizeof(*evt), 0); if (!evt) { // CRITICAL BUG: Dropping network packets because telemetry failed! return TC_ACT_SHOT; } evt->len = skb->len; evt->ifindex = skb->ifindex; // Inefficient: Wakes up userspace on every single packet bpf_ringbuf_submit(evt, 0); return TC_ACT_OK; } ``` #### Production Standard (Correct) > **Standard**: The good example samples packet flows, safely handles ring buffer reservation exhaustion without interrupting network traffic (always returning TC_ACT_OK), tracks dropped telemetry in a per-CPU counter map, and submits with BPF_RB_NO_WAKEUP to avoid softirq wake-up storms. ```c #include <linux/bpf.h> #include <linux/pkt_cls.h> #include <bpf/bpf_helpers.h> struct event_t { __u32 len; __u32 ifindex; }; struct rate_limit_t { __u64 last_time; __u32 tokens; }; struct { __uint(type, BPF_MAP_TYPE_RINGBUF); __uint(max_entries, 1 << 24); // 16MB bounded ring buffer } events SEC(".maps"); struct { __uint(type, BPF_MAP_TYPE_PERCPU_ARRAY); __uint(max_entries, 2); __type(key, __u32); __type(value, __u64); } telemetry_stats SEC(".maps"); #define STAT_DROPPED 0 #define STAT_SENT 1 #define SAMPLE_MASK 0x3F // Sample 1 in 64 packets SEC("tc/egress") int tc_egress_telemetry(struct __sk_buff *skb) { __u32 key = STAT_DROPPED; // Guardrail: Sample packets to avoid saturating ringbuf on 100GbE bursts if ((skb->len & SAMPLE_MASK) != 0) { return TC_ACT_OK; } struct event_t *evt = bpf_ringbuf_reserve(&events, sizeof(*evt), 0); if (!evt) { // Safe degradation: increment drop counter map and allow traffic to pass unimpeded __u64 *drops = bpf_map_lookup_elem(&telemetry_stats, &key); if (drops) { __sync_fetch_and_add(drops, 1); } return TC_ACT_OK; } evt->len = skb->len; evt->ifindex = skb->ifindex; // Guardrail: BPF_RB_NO_WAKEUP prevents per-packet interrupts in the network TX path bpf_ringbuf_submit(evt, BPF_RB_NO_WAKEUP); key = STAT_SENT; __u64 *sent = bpf_map_lookup_elem(&telemetry_stats, &key); if (sent) { __sync_fetch_and_add(sent, 1); } return TC_ACT_OK; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF TC Egress Telemetry Rate-Limiting & Ring Buffer Overflow Guardrail

eBPF TC Egress Telemetry Rate-Limiting & Ring Buffer Overflow Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces bounded eBPF ring buffer reservations, non-blocking telemetry drops, and token-bucket rate limiting in Traffic Control (TC) egress hook paths. Prevents kernel memory exhaustion, NET_TX softirq CPU starvation, and network egress throughput degradation during high-volume packet bursts. Mandates that telemetry failures never fail open to packet rejection. 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 per-packet eBPF ring buffer emissions in TC egress paths without drop counters or sampling, causing packet drop and softirq stalls. 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 per-packet eBPF ring buffer emissions in TC egress paths without drop counters or sampling, causing packet drop and softirq stalls.	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 return TC_ACT_OK (or the intended forwarding decision) even when ring buffer reservation or submission fails.

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.