OpenTelemetry eBPF Profiling Zero-Overhead Frame-Pointer Invariant

--- description: OpenTelemetry eBPF Profiling Zero-Overhead Frame-Pointer Invariant - Enforces compiler-level frame-pointer preservation across all compiled production binaries, container base images, and runtime flags to guarantee zero-overhead continuous eBPF CPU stack unwinding. Omitting frame pointers breaks kernel-space eBPF stack walks, forcing either complete profiling blind spots or catastrophic kernel DWARF-unwinding performance degradation in production environments. globs: **/Dockerfile*, **/.cargo/config.toml, **/CMakeLists.txt, **/Makefile*, **/BUILD.bazel, **/*.mk, **/entrypoint.sh alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-profiling-frame-pointer-preservation" --- # OpenTelemetry eBPF Profiling Zero-Overhead Frame-Pointer Invariant > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Compiling Production Binaries with Frame Pointer Elimination (-fomit-frame-pointer) ## System Constraints You are a Principal Systems & DevOps Engineer enforcing the OpenTelemetry Profiling Agent Zero-Overhead Frame-Pointer Invariant. Continuous eBPF profilers traverse runtime call stacks using the architectural frame pointer register (RBP on x86_64, R29/FP on AArch64). You must strictly mandate that all production C/C++, Rust, Go, JVM, and Node.js compilation toolchains and runtime execution flags preserve frame pointers. Reject any build configuration or Dockerfile that strips frame pointers or relies on DWARF-based unwinding during production eBPF sampling. ## Strict Guidelines - Engineers MUST ALWAYS pass `-fno-omit-frame-pointer` and `-mno-omit-leaf-frame-pointer` to C/C++ compiler toolchains (GCC, Clang) in release optimization profiles (`-O2`, `-O3`). - Engineers MUST ALWAYS configure Rust release targets with `-C force-frame-pointers=yes` via `RUSTFLAGS` or `.cargo/config.toml`. - Engineers MUST ALWAYS enforce the JVM flag `-XX:+PreserveFramePointer` in production container definitions and execution scripts. - Engineers MUST NOT allow build pipelines to execute stripping utilities (`strip --strip-all`) that discard dynamic symbol tables or unwind metadata required by the OpenTelemetry profiler agent. - Services MUST enable Node.js runtime flag `--perf-prof` or `--interpreted-frames-native-stack` when using V8/Node.js workloads alongside eBPF profilers. - Components NEVER utilize Alpine/musl toolchains unless frame-pointer retention has been explicitly validated in the musl libc build itself. ## Bad vs Good Implementations ### Dockerfile C/C++ Release Build Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default GCC/Clang release optimizations (`-O2`, `-O3`) enable `-fomit-frame-pointer` on x86_64 architectures to free the RBP register for general allocation. This prevents eBPF profilers (such as OpenTelemetry eBPF agent) from walking stack frames in the kernel, generating disconnected single-frame traces. ```dockerfile # syntax=docker/dockerfile:1 FROM gcc:13-bookworm AS builder WORKDIR /src COPY . . # VIOLATION: O2 implicitly enables -fomit-frame-pointer on x86_64, breaking eBPF unwinding RUN gcc -O2 -DNDEBUG -o server main.c FROM debian:bookworm-slim COPY --from=builder /src/server /usr/local/bin/server ENTRYPOINT ["/usr/local/bin/server"] ``` #### Production Standard (Correct) > **Standard**: Providing `-fno-omit-frame-pointer` and `-mno-omit-leaf-frame-pointer` instructs the compiler to retain standard frame pointer setup and teardown instructions in the function prologue and epilogue, enabling the eBPF kernel agent to unwind call stacks in under a microsecond without invoking expensive DWARF stack unwinding. ```dockerfile # syntax=docker/dockerfile:1 FROM gcc:13-bookworm AS builder WORKDIR /src COPY . . # INVARIANT: Explicitly preserve frame pointers for leaf and non-leaf routines under optimization ENV CFLAGS="-O2 -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer -g -grecord-gcc-switches" RUN gcc ${CFLAGS} -DNDEBUG -o server main.c FROM debian:bookworm-slim COPY --from=builder /src/server /usr/local/bin/server ENTRYPOINT ["/usr/local/bin/server"] ``` ### Rust Production Cargo Configuration (.cargo/config.toml) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Rust's LLVM backend automatically drops frame pointers for performance when compiling with standard release profiles (`opt-level = 3`), blinding eBPF CPU profilers. ```toml # VIOLATION: Release profile enables aggressive LTO and codegen optimization without frame pointers [profile.release] opt-level = 3 lto = true codegen-units = 1 ``` #### Production Standard (Correct) > **Standard**: Setting `rustflags = ["-C", "force-frame-pointers=yes"]` ensures LLVM retains the RBP/FP register conventions across all crate dependencies and standard library linkages, allowing continuous profiling traces to map directly to Rust functions. ```toml # INVARIANT: Retain frame pointer chains across all compiled release targets [build] rustflags = ["-C", "force-frame-pointers=yes"] [profile.release] opt-level = 3 lto = true codegen-units = 1 debug = 1 # Preserves line table information without bloating binary footprint ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry eBPF Profiling Zero-Overhead Frame-Pointer Invariant

OpenTelemetry eBPF Profiling Zero-Overhead Frame-Pointer Invariant defines an industrial-grade behavioral standard for devops engineering. Enforces compiler-level frame-pointer preservation across all compiled production binaries, container base images, and runtime flags to guarantee zero-overhead continuous eBPF CPU stack unwinding. Omitting frame pointers breaks kernel-space eBPF stack walks, forcing either complete profiling blind spots or catastrophic kernel DWARF-unwinding performance degradation in production 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: Compiling Production Binaries with Frame Pointer Elimination (-fomit-frame-pointer) 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	Compiling Production Binaries with Frame Pointer Elimination (-fomit-frame-pointer)	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 pass `-fno-omit-frame-pointer` and `-mno-omit-leaf-frame-pointer` to C/C++ compiler toolchains (GCC, Clang) in release optimization profiles (`-O2`, `-O3`).

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.