OpenTelemetry Continuous Profiling Frame Pointer Unwinding Guardrail

--- description: OpenTelemetry Continuous Profiling Frame Pointer Unwinding Guardrail - Enforces preservation of frame pointers across all compiled languages and runtimes in containerized production workloads to enable zero-overhead eBPF stack unwinding. Prohibits runtime DWARF unwinding in production containers, capping continuous profiling CPU overhead below 1% while eliminating kernel-to-userspace page-fault stalls. Ensures full stack visibility across mixed native, Go, JVM, and Node.js call graphs for OpenTelemetry Profiling agents. globs: **/Dockerfile*, **/Containerfile*, **/CMakeLists.txt, **/Makefile*, **/*.mk, **/build.zig, **/Cargo.toml, **/.cargo/config.toml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/otel-profiling-frame-pointer-unwinding-guardrail" --- # OpenTelemetry Continuous Profiling Frame Pointer Unwinding Guardrail > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Compiling production binaries with frame pointer omission, causing eBPF profilers to fail unwinding or fall back to resource-intensive DWARF parsers. ## System Constraints You are a Principal Systems and Infrastructure Architect enforcing OpenTelemetry continuous profiling standards. Continuous profiling via eBPF requires deterministic native-stack unwinding using hardware frame pointers (RBP on x86_64, FP/R29 on AArch64). You must strictly mandate that all C/C++, Rust, Go (cgo), JVM, and runtime build steps preserve frame pointers and avoid relying on DWARF .eh_frame parsing at runtime. You must reject any configuration that uses `-fomit-frame-pointer` or omits explicit preservation flags in container builds. ## Strict Guidelines - Engineers MUST ALWAYS compile native code (C, C++, Rust, cgo) with explicit frame pointer preservation flags (`-fno-omit-frame-pointer` in GCC/Clang, `force-frame-pointers = true` in Rust Cargo profiles). - Engineers MUST ALWAYS configure JVM runtimes under eBPF profiling with `-XX:+PreserveFramePointer` and `-XX:+UnlockDiagnosticVMOptions`. - Engineers MUST NOT rely on userspace DWARF (.eh_frame) or debug-symbol table unwinding in production eBPF collectors, as it exceeds the 1% target CPU overhead budget and triggers kernel-space memory traps. - Dockerfiles and multi-stage container builds MUST set explicit compiler and linker flags (`CFLAGS`, `CXXFLAGS`, `CGO_CFLAGS`) in every intermediate compilation stage. - Binaries MAY be stripped of heavy debug symbols (`.debug_*`) using `strip --strip-debug` only if frame pointers and `.symtab`/`.dynsym` function boundaries remain intact for OpenTelemetry symbol resolution. ## Bad vs Good Implementations ### Dockerfile Native & Go Build Flags for Continuous Profiling #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Default optimization levels (-O2/-O3) omit the RBP/FP register to gain an extra general-purpose register. In production, this causes eBPF continuous profilers (like OTel/Parca/Pyroscope) to truncate native stacks or incur massive CPU degradation attempting userspace DWARF interpretation. ```dockerfile # Stage 1: Native builder omitting frame pointers for micro-optimizations FROM golang:1.22-bookworm AS builder WORKDIR /app COPY . . # Default GCC/Clang optimization -O2/-O3 implicitly enables -fomit-frame-pointer on x86_64 ENV CGO_ENABLED=1 RUN go build -ldflags="-s -w" -o /bin/service ./cmd/api FROM gcr.io/distroless/base-debian12 COPY --from=builder /bin/service /bin/service ENTRYPOINT ["/bin/service"] ``` #### Production Standard (Correct) > **Standard**: Passing `-fno-omit-frame-pointer` and `-mno-omit-leaf-frame-pointer` guarantees a valid linked-list of stack frames traversable by eBPF agents via 2-instruction pointer dereferencing, ensuring continuous profiling overhead stays below 1% CPU. ```dockerfile # Stage 1: Enforce frame pointer preservation across cgo and native builds FROM golang:1.22-bookworm AS builder WORKDIR /app COPY . . # Explicitly retain frame pointers on x86_64 & arm64 while disabling full omit-pointer optimizations ENV CGO_ENABLED=1 \ CGO_CFLAGS="-O2 -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer" \ CGO_CXXFLAGS="-O2 -fno-omit-frame-pointer -mno-omit-leaf-frame-pointer" # Strip DWARF debug sections to optimize binary size, while retaining the symbol table (.symtab) RUN go build -ldflags="-extldflags '-fno-omit-frame-pointer'" -o /bin/service ./cmd/api FROM gcr.io/distroless/base-debian12 COPY --from=builder /bin/service /bin/service ENTRYPOINT ["/bin/service"] ``` ### Rust Cargo Configuration for Profiling-Ready Release Builds #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Rust's release profile automatically strips frame pointer metadata when opt-level >= 1, severing eBPF continuous profiler call graphs at native Rust boundaries. ```toml # Cargo.toml [profile.release] opt-level = 3 lto = true codegen-units = 1 # Lacks frame pointer retention, defaulting to pointer omission on x86_64 ``` #### Production Standard (Correct) > **Standard**: Setting `force-frame-pointers = true` instructs LLVM to always emit standard prologue/epilogue instructions (`push rbp; mov rbp, rsp`), allowing zero-overhead unwinding by OpenTelemetry eBPF tracers. ```toml # Cargo.toml [profile.release] opt-level = 3 lto = "thin" codegen-units = 1 # Explicitly retain hardware frame pointers in release artifacts for eBPF collectors force-frame-pointers = true # Retain line table info without inflating production container footprints debug = 1 ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Continuous Profiling Frame Pointer Unwinding Guardrail

OpenTelemetry Continuous Profiling Frame Pointer Unwinding Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces preservation of frame pointers across all compiled languages and runtimes in containerized production workloads to enable zero-overhead eBPF stack unwinding. Prohibits runtime DWARF unwinding in production containers, capping continuous profiling CPU overhead below 1% while eliminating kernel-to-userspace page-fault stalls. Ensures full stack visibility across mixed native, Go, JVM, and Node.js call graphs for OpenTelemetry Profiling agents. 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 omission, causing eBPF profilers to fail unwinding or fall back to resource-intensive DWARF parsers. 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 omission, causing eBPF profilers to fail unwinding or fall back to resource-intensive DWARF parsers.	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 code (C, C++, Rust, cgo) with explicit frame pointer preservation flags (`-fno-omit-frame-pointer` in GCC/Clang, `force-frame-pointers = true` in Rust Cargo profiles).

Engineers MUST ALWAYS compile native code (C, C++, Rust, cgo) with explicit frame pointer preservation flags (`-fno-omit-frame-pointer` in GCC/Clang, `force-frame-pointers = true` in Rust Cargo profiles).

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.