Continuous Profiling eBPF Unwind Table Kernel Memory Budget Standard

--- description: Continuous Profiling eBPF Unwind Table Kernel Memory Budget Standard - Enforces deterministic kernel memory bounds and eviction protocols on eBPF BPF_MAP_TYPE_STACK_TRACE and custom compact unwind tables (e.g., .eh_frame/DWARF-less frame pointers) utilized by distributed profiling agents. Prevents node kernel memory exhaustion, non-reclaimable slab starvation, and soft-lockup panics in high-churn container environments. globs: **/profiling/**/*.{ts,go,rs,c,bpf.c,yaml}, **/daemonset/**/*.{yaml,yml}, **/collector/**/*.{yaml,yml} alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-unwind-table-kernel-memory-budget-standard" --- # Continuous Profiling eBPF Unwind Table Kernel Memory Budget Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded eBPF map sizing and unconstrained unwind table loading causing kernel OOM and scheduling lockups ## System Constraints You are a Principal Systems Engineer and Kernel Reliability Architect enforcing strict memory ceilings and admission controls on continuous profiling eBPF stack unwind tables. Mandate kernel-space memory budgets, pre-allocated bounded LRU maps, and userspace shedding strategies to prevent non-reclaimable slab exhaustion and node kernel deadlocks. ## Strict Guidelines - Engineers MUST ALWAYS pre-allocate eBPF unwind and stack trace maps using explicit memory budgets that never exceed 5% of total node physical RAM. - Engineers MUST NOT utilize unbounded BPF_MAP_TYPE_HASH or growing radix trees in kernel space for frame unwind records; BPF_MAP_TYPE_LRU_HASH or fixed-capacity chunk arrays MUST be used. - Services MUST implement userspace admission control and deduplication of unwind tables prior to loading native ELF binary unwind info into kernel memory. - Code SHOULD enforce strict TTL and reference counting on executable mapping segments to aggressively purge stale shared library unwind entries on process termination. - Components NEVER execute raw DWARF parsing inside kernel probes; unwind programs MUST strictly consume pre-processed, highly compressed framing metadata (e.g., SFrame or ORC compact tables). ## Bad vs Good Implementations ### Configuring BPF Map Bounds and DaemonSet Limits for Compact Unwinding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using BPF_MAP_TYPE_HASH with dynamic expansion or unconstrained entries bypasses standard container cgroup limits and consumes non-reclaimable kernel slab memory (kmalloc-512/kmalloc-1024), risking node-wide kernel deadlocks under process churn. ```typescript import { ProfilerAgentConfig } from './types'; // ANTI-PATTERN: Dynamically allocating unbudgeted hash maps for stack unwinding export const config: ProfilerAgentConfig = { ebpf: { stackMapType: 'BPF_MAP_TYPE_HASH', // Zero or infinite entries causes unconstrained memory expansion during load spikes maxStackEntries: 0, dwarfParsingInKernel: true, unwindTableAllocationBytes: 0, // Unbounded }, resources: { // Node can be starved because kernel allocations are charged to kernel slab, not cgroup memory limits: { memory: '512Mi' }, }, }; ``` #### Production Standard (Correct) > **Standard**: Adopts BPF_MAP_TYPE_LRU_HASH to guarantee bounded memory usage, uses compact userspace-parsed SFrame formats, and enforces hard limits on maximum kernel unwind pages, preventing kernel slab exhaustion. ```typescript import { ProfilerAgentConfig } from './types'; // PRODUCTION FIX: Hard memory ceilings, LRU map eviction, and compact unwind constraints const KERNEL_UNWIND_MAX_PAGES = 16384; // 64 MiB strict kernel ceiling const MAX_STACK_TRACE_ENTRIES = 32768; // Deterministic stack footprint export const config: ProfilerAgentConfig = { ebpf: { stackMapType: 'BPF_MAP_TYPE_LRU_HASH', maxStackEntries: MAX_STACK_TRACE_ENTRIES, unwindFormat: 'SFRAME_COMPACT', dwarfParsingInKernel: false, unwindTableAllocationBytes: KERNEL_UNWIND_MAX_PAGES * 4096, evictionPolicy: 'LRU_ON_CAPACITY_LIMIT', }, kernelMemoryGuard: { maxKernelBudgetPercentOfRam: 2.5, bpfMemlockEnforcement: 'STRICT', dropSamplesOnMemoryPressure: true, }, resources: { limits: { memory: '1Gi' }, requests: { memory: '512Mi' }, }, }; ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Continuous Profiling eBPF Unwind Table Kernel Memory Budget Standard

Continuous Profiling eBPF Unwind Table Kernel Memory Budget Standard defines an industrial-grade behavioral standard for devops engineering. Enforces deterministic kernel memory bounds and eviction protocols on eBPF BPF_MAP_TYPE_STACK_TRACE and custom compact unwind tables (e.g., .eh_frame/DWARF-less frame pointers) utilized by distributed profiling agents. Prevents node kernel memory exhaustion, non-reclaimable slab starvation, and soft-lockup panics in high-churn container environments. 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 eBPF map sizing and unconstrained unwind table loading causing kernel OOM and scheduling lockups 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 eBPF map sizing and unconstrained unwind table loading causing kernel OOM and scheduling lockups	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 pre-allocate eBPF unwind and stack trace maps using explicit memory budgets that never exceed 5% of total node physical RAM.

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.