OpenTelemetry eBPF Profiler Overhead Ceiling and Ring-Buffer Guardrail Standard

Q: How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded eBPF Stack Unwinding and Excessive Ring-Buffer Allocations Inducing Host CPU Starvation and Latency Regressions) and prescribes verified positive examples. Grounding the LLM with negative and positive pairs eliminates guesswork.

Q: Which AI coding environments are supported?

This specification is multi-platform compatible: Cursor (.cursor/rules/*.mdc & .cursorrules), Anthropic Claude Code (CLAUDE.md), Windsurf (.windsurfrules), Codex / Cline (AGENTS.md), and GitHub Copilot (.github/copilot-instructions.md).

Q: Can I combine this rule with other technology stacks?

Yes. Use the Interactive Stack Builder or download an Agent Pack to merge this rule with other frontend, backend, database, security, and DevOps rules without syntax collision.

--- description: OpenTelemetry eBPF Profiler Overhead Ceiling and Ring-Buffer Guardrail Standard - Enforces strict limits on kernel-space frame stack unwinding, eBPF ring-buffer sizing, and sampling frequencies for OpenTelemetry continuous profiling agents. Prevents profiling-induced CPU context-switch churn, cache eviction, and tail-latency regressions in low-latency production microservices. globs: **/otel-collector*.yaml, **/otel-collector*.yml, **/profiling-agent*.yaml, **/profiling-agent*.yml, deployments/k8s/**/*.yaml, helm/**/*.yaml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/opentelemetry-ebpf-profiler-overhead-ceiling-standard" --- # OpenTelemetry eBPF Profiler Overhead Ceiling and Ring-Buffer Guardrail Standard > **Severity**: CRITICAL | **Category**: devops > **Anti-Pattern Warning**: Unbounded eBPF Stack Unwinding and Excessive Ring-Buffer Allocations Inducing Host CPU Starvation and Latency Regressions ## System Constraints You are a Principal Engineer enforcing the OpenTelemetry Continuous Profiling eBPF Collector Overhead Ceiling Standard. You must mandate non-blocking ring buffer allocations, bounded frame pointer stack unwinding depths, strict prime-number low-frequency sampling rates, and hard cgroup CPU/memory quotas to protect critical microservices from latency regressions caused by profiling artifacts. ## Strict Guidelines - Engineers MUST ALWAYS bound eBPF continuous profiling sampling frequencies to prime numbers between 17 Hz and 47 Hz (never exceeding 49 Hz) to eliminate harmonic alignment with system timers and minimize kernel interrupt overhead. - Engineers MUST NOT permit unbounded or deep DWARF-based stack unwinding inside kernel space; frame stack depth MUST be explicitly capped at <= 128 frames. - Services MUST configure the eBPF profiling DaemonSet with hard cgroup v2 resource limits capped at <= 0.25 vCPU (250m) and <= 512Mi memory per node to prevent host-level compute exhaustion. - Components NEVER block kernel execution or application threads on ring buffer contention; eBPF buffers MUST enforce lossy non-blocking ring-buffer semantics (e.g., BPF_RB_NO_WAKEUP or explicit drop-count metrics when queues saturate). - Code SHOULD configure adaptive circuit breakers or dynamic throttling to immediately suspend eBPF stack collection when host CPU utilization exceeds 80%. ## Bad vs Good Implementations ### OpenTelemetry eBPF Continuous Profiler DaemonSet Configuration #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Configuring high sampling frequencies (1000 Hz) causes massive CPU overhead and cache thrashing. Stack depth unwinding of 512 frames strains kernel eBPF verifier limits and unwinding time. A 256MB buffer wastes locked physical memory, and disabling drop-on-full risks blocking user-space execution paths during pipeline stalls. ```yaml # CRITICAL VIOLATION: Unbounded sampling frequency, deep unwinding, and missing cgroup limits apiVersion: apps/v1 kind: DaemonSet metadata: name: otel-ebpf-profiler namespace: monitoring spec: template: spec: containers: - name: profiler image: otel/opentelemetry-ebpf-profiler:latest args: - --sampling-rate=1000 # Extreme sampling frequency induces kernel lock contention - --max-stack-depth=512 # Deep unwinding degrades instruction cache - --bpf-ring-buffer-size=256MB # Bloated pinned kernel memory allocations - --drop-on-full=false # Blocking pushes stall application execution threads # Missing resources limits allows unbounded CPU consumption across host cores ``` #### Production Standard (Correct) > **Standard**: The 19 Hz prime-number sampling rate minimizes CPU overhead while ensuring statistically sound distribution. Stack depth is capped at 128 frames, and ring-buffer allocation is limited to 8MB with lossy drop semantics enabled. Explicit cgroup resource requests and limits prevent the profiler from competing with low-latency tenant pods. ```yaml # COMPLIANT: Bounded sampling rate, capped unwinding, hard cgroup constraints, and lossy drop semantics apiVersion: apps/v1 kind: DaemonSet metadata: name: otel-ebpf-profiler namespace: monitoring spec: template: spec: containers: - name: profiler image: otel/opentelemetry-ebpf-profiler:v0.11.0 args: - --sampling-rate=19 # Prime number avoids harmonic timer lockups - --max-stack-depth=128 # Bounded unwinding depth protects L1/L2 cache - --bpf-ring-buffer-size=8MB # Pinned kernel memory is constrained - --drop-on-full=true # Non-blocking ring buffer drops telemetry over app latency - --cpu-threshold-throttle=80 # Disables sampling if host CPU spikes > 80% resources: limits: cpu: "250m" memory: "512Mi" requests: cpu: "100m" memory: "128Mi" ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry eBPF Profiler Overhead Ceiling and Ring-Buffer Guardrail Standard

OpenTelemetry eBPF Profiler Overhead Ceiling and Ring-Buffer Guardrail Standard defines an industrial-grade behavioral standard for devops engineering. Enforces strict limits on kernel-space frame stack unwinding, eBPF ring-buffer sizing, and sampling frequencies for OpenTelemetry continuous profiling agents. Prevents profiling-induced CPU context-switch churn, cache eviction, and tail-latency regressions in low-latency production microservices. 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 Stack Unwinding and Excessive Ring-Buffer Allocations Inducing Host CPU Starvation and Latency Regressions 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 Stack Unwinding and Excessive Ring-Buffer Allocations Inducing Host CPU Starvation and Latency Regressions	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 bound eBPF continuous profiling sampling frequencies to prime numbers between 17 Hz and 47 Hz (never exceeding 49 Hz) to eliminate harmonic alignment with system timers and minimize kernel interrupt overhead.

Engineers MUST ALWAYS bound eBPF continuous profiling sampling frequencies to prime numbers between 17 Hz and 47 Hz (never exceeding 49 Hz) to eliminate harmonic alignment with system timers and minimize kernel interrupt overhead.

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.