eBPF Continuous Profiling DWARF-less Frame Pointer Unwind Standard

--- description: eBPF Continuous Profiling DWARF-less Frame Pointer Unwind Standard - Enforces frame-pointer preservation across all compiled production binaries and runtime flags to enable zero-overhead kernel-level eBPF stack unwinding. Replaces heavy user-space DWARF/`.eh_frame` stack-walking algorithms with native BPF helper unwinding (`bpf_get_stackid`), guaranteeing continuous profiling CPU overhead remains strictly under 1%. globs: **/Dockerfile*, **/Makefile, **/CMakeLists.txt, **/*.bpf.c, **/*.bpf.h, deploy/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/ebpf-frame-pointer-unwind-overhead-guardrail" --- # eBPF Continuous Profiling DWARF-less Frame Pointer Unwind Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Omitted Frame Pointers Forcing Out-of-Band DWARF Stack Walks and High CPU Overhead ## System Constraints You are a Principal Systems & SRE Architect enforcing zero-overhead continuous profiling via eBPF. Enforce strict preservation of frame pointers across all production compile chains and container runtime configurations. Mandate kernel-level unwinding via `bpf_get_stackid` with `BPF_F_USER_STACK` or compact frame traversals, strictly rejecting reliance on costly user-space DWARF unwinders (`libunwind`, high-frequency `bpf_probe_read_user` stack sweeps) that violate the <1% CPU ceiling. ## Strict Guidelines - Engineers MUST ALWAYS compile native production binaries (C/C++, Rust, Go) with preserved frame pointers (e.g., `-fno-omit-frame-pointer`, `-mno-omit-leaf-frame-pointer` or equivalent compiler flags). - Engineers MUST NOT rely on runtime user-space DWARF parsing (`.eh_frame`, `.debug_frame`) for continuous real-time fleet profiling due to excessive CPU cycle and memory paging overhead. - Code SHOULD configure managed runtimes to retain frame pointers in compiled JIT segments (e.g., `-XX:+PreserveFramePointer` for JVM, Node.js `--perf-prof-unwinding-info`). - Services MUST configure eBPF profiler kernel programs using `bpf_get_stackid(ctx, &stackmap, BPF_F_USER_STACK)` or optimized frame-pointer iterations with bound checks. - Components NEVER drop eBPF ring buffers or stack maps due to blocking page-fault recovery loops caused by deep user-space stack unwinds. ## Bad vs Good Implementations ### C/eBPF & Build Config - Preserving Frame Pointers vs DWARF Scraping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Omitting frame pointers strips the RBP chain. Profilers must dump raw memory and perform user-space DWARF unwind tables lookups, inducing page faults, cache churn, and spiking CPU usage far beyond the 1% target. ```makefile # Anti-Pattern: Frame pointers omitted for minor register saving; # Forces continuous profiler to copy full 64KB user stack pages to userland for DWARF traversal. CFLAGS := -O3 -fomit-frame-pointer -g # eBPF profiler fallback using expensive raw stack copying (Causes >5% CPU overhead): # SEC("perf_event") # int record_stack(struct bpf_perf_event_data *ctx) { # bpf_probe_read_user(raw_stack_buf, sizeof(raw_stack_buf), (void *)ctx->regs.sp); # bpf_ringbuf_output(&events, raw_stack_buf, sizeof(raw_stack_buf), 0); # return 0; # } ``` #### Production Standard (Correct) > **Standard**: Retaining frame pointers allows `bpf_get_stackid` to traverse the RBP link list directly in kernel context in under a microsecond, keeping continuous profiling overhead consistently below 1%. ```makefile # Production Standard: Retain frame pointers for O(1) kernel-space stack unwinding CFLAGS := -O3 -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -gline-tables-only # eBPF profiler leverages kernel fast-path unwinding (<0.5% CPU overhead): # SEC("perf_event") # int record_stack(struct bpf_perf_event_data *ctx) { # int stack_id = bpf_get_stackid(ctx, &stack_traces, BPF_F_USER_STACK); # if (stack_id >= 0) { # bpf_map_update_elem(&counts, &stack_id, &one, BPF_ANY); # } # return 0; # } ``` ### Container Build Configuration - Polyglot Frame Pointer Preservation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: HotSpot JIT generates assembly without frame pointers by default, leading to broken and truncated flame graphs unless costly symbols/DWARF unwind hooks are engaged. ```dockerfile # Anti-Pattern: Omits runtime frame-pointer flags, breaking eBPF user stack walking FROM openjdk:17-slim ENV JAVA_OPTS="-Xms4g -Xmx4g" ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"] ``` #### Production Standard (Correct) > **Standard**: `-XX:+PreserveFramePointer` instructs the JVM JIT compiler to keep RBP intact in compiled bytecode methods, allowing eBPF to trace combined OS and Java stacks seamlessly at negligible overhead. ```dockerfile # Production Standard: Explicitly preserve frame pointers for JIT compilation FROM openjdk:17-slim ENV JAVA_OPTS="-Xms4g -Xmx4g -XX:+PreserveFramePointer -XX:+UnlockDiagnosticVMOptions -XX:+DebugNonSafepoints" ENTRYPOINT ["sh", "-c", "java $JAVA_OPTS -jar app.jar"] ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: eBPF Continuous Profiling DWARF-less Frame Pointer Unwind Standard

eBPF Continuous Profiling DWARF-less Frame Pointer Unwind Standard defines an industrial-grade behavioral standard for devops engineering. Enforces frame-pointer preservation across all compiled production binaries and runtime flags to enable zero-overhead kernel-level eBPF stack unwinding. Replaces heavy user-space DWARF/`.eh_frame` stack-walking algorithms with native BPF helper unwinding (`bpf_get_stackid`), guaranteeing continuous profiling CPU overhead remains strictly under 1%. 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: Omitted Frame Pointers Forcing Out-of-Band DWARF Stack Walks and High CPU Overhead 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	Omitted Frame Pointers Forcing Out-of-Band DWARF Stack Walks and High CPU Overhead	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 compile native production binaries (C/C++, Rust, Go) with preserved frame pointers (e.g., `-fno-omit-frame-pointer`, `-mno-omit-leaf-frame-pointer` or equivalent compiler flags).

Engineers MUST ALWAYS compile native production binaries (C/C++, Rust, Go) with preserved frame pointers (e.g., `-fno-omit-frame-pointer`, `-mno-omit-leaf-frame-pointer` or equivalent compiler flags).

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.