AgentRules.org
RulesStacksClientsAuditorPrunerSelf-HealRFCsBenchmarkCLICI/CDAuthorsSubmit
This specification is maintained by the AgentRules Working Group. Have enhancements or want to claim maintainership?Submit Specification →
devopscritical PriorityID: otel-ebpf-unwind-budget-guardrail

OpenTelemetry Continuous Profiling eBPF Unwind Budget and Stack Depth Guardrail

Enforces strict instruction budgets, stack-depth bounds, and tail-call execution limits on eBPF continuous profiling probes. Prevents NMI-watchdog lockups, CPU pipeline saturation, and tail latency regressions in mission-critical, low-latency microservices by constraining DWARF/frame-pointer walking iterations. Guarantees predictable agent resource consumption under high-frequency sample rates across Linux kernel fleets.

Prohibited Anti-Pattern: Unbounded or Deep DWARF Unwinding in eBPF Probes Inducing Kernel Preemption Latency Spikes

Export Ready-to-Drop Configuration

Select format below to copy code or download file directly.

---
description: OpenTelemetry Continuous Profiling eBPF Unwind Budget and Stack Depth Guardrail - Enforces strict instruction budgets, stack-depth bounds, and tail-call execution limits on eBPF continuous profiling probes. Prevents NMI-watchdog lockups, CPU pipeline saturation, and tail latency regressions in mission-critical, low-latency microservices by constraining DWARF/frame-pointer walking iterations. Guarantees predictable agent resource consumption under high-frequency sample rates across Linux kernel fleets.
globs: src/**/*.{c,h,bpf.c,bpf.h,rs,go,ts}
alwaysApply: true
verified_by: "agentrules.org"
license: "CC-BY-4.0"
source: "https://agentrules.org/rules/otel-ebpf-unwind-budget-guardrail"
---

# OpenTelemetry Continuous Profiling eBPF Unwind Budget and Stack Depth Guardrail

> **Severity**: CRITICAL | **Category**: devops
> **Anti-Pattern Warning**: Unbounded or Deep DWARF Unwinding in eBPF Probes Inducing Kernel Preemption Latency Spikes

## System Constraints
You are a Principal Engineer enforcing the OpenTelemetry Continuous Profiling eBPF Unwind Budget Guardrail. Mandate invariants that strictly govern eBPF native unwinder instruction ceilings, maximum stack walk depths, and fallback circuit-breakers to protect host CPU stability under heavy workloads.

## Strict Guidelines
- Engineers MUST ALWAYS enforce a hard upper bound on stack unwinding depth (maximum 128 frames for native code; maximum 64 frames for interpreted runtimes) within eBPF verifier limits.
- Engineers MUST NOT execute unbounded loops or unrolled iterations that exceed the kernel BPF instruction budget (max 1M instructions verified, with runtime limits capped at <= 4,000 instructions per sample event).
- Code SHOULD implement adaptive sampling or back-off thresholds that detect NMI/soft-lockup pressure and reduce sampling frequency dynamically if probe execution exceeds 5 microseconds per invocation.
- Services MUST emit a truncated-stack diagnostic metric (e.g., `profiling.unwind.truncated`) whenever unwinding is halted due to budget exhaustion, rather than silently failing or dropping frames.
- Components NEVER fall back to full userspace DWARF evaluation inside kernel space; complex table lookups must rely on compact, pre-parsed `.eh_frame_hdr` or frame-pointer records mapped to static BPF perf rings.

## Bad vs Good Implementations
### Configuring eBPF Unwind Stack Depth and Cycle Budget Constraints

#### Bad Antipattern (AI Common Hallucination)
> **Why it fails**: Configuring a DWARF-based unwinder without hard bounds on stack depth or execution budget exposes target nodes to soft lockups and latency spikes when traversing deeply nested call chains or mangled stacks.
```typescript
// Anti-pattern: Unbounded stack depth and missing instruction budget configuration
export interface ProfilerConfig {
  sampleRateHz: number;
  unwindStrategy: 'dwarf' | 'fp';
  maxStackDepth?: number;
}

export const productionProfiler: ProfilerConfig = {
  sampleRateHz: 99,
  unwindStrategy: 'dwarf',
  // Missing maxStackDepth and per-probe CPU budget allows unwinder to walk deep recursion,
  // exhausting verifier branch budget or spiking scheduler latency on high-core systems.
};
```

#### Production Standard (Correct)
> **Standard**: Explicitly binds the unwinding depth, sets instruction budgets for the eBPF runtime, and provisions latency thresholds that avert CPU saturation and kernel watchdogs under heavy load.
```typescript
// Production standard: Explicit unwinding budget, stack limits, and circuit breakers
export interface UnwindBudgetConfig {
  sampleRateHz: number;
  unwindStrategy: 'dwarf' | 'fp' | 'hybrid';
  maxStackDepth: number;
  maxInstructionsPerProbe: number;
  adaptiveBackoffThresholdUs: number;
  emitTruncationTelemetry: boolean;
}

export const productionProfiler: UnwindBudgetConfig = {
  sampleRateHz: 49, // Optimal prime frequency to avoid harmonic resonance
  unwindStrategy: 'hybrid',
  maxStackDepth: 128, // Hard upper limit matching eBPF ring buffer payload constraints
  maxInstructionsPerProbe: 4096, // Bounds BPF verifier complexity and probe CPU budget
  adaptiveBackoffThresholdUs: 5, // Tripwire to throttle sampling if unwinding exceeds 5us
  emitTruncationTelemetry: true
};
```
Recommended MCP Servers (mcp-serverlist.com)

Equip agent with system tools to verify code for this stack.

eBPF Verifier & Profile Validator
Static analysis server verifying eBPF instruction counts and memory boundary invariants prior to deployment.
Recommended Agent Skills (askills.dev)

Ready-to-use executable skill functions tailored to this stack.

bpftool CLI Checker
Inspects loaded BPF program runtimes, jited instruction sizes, and verifies instruction execution budgets.
Architectural Specification & Invariant Rationale

Architectural Invariant Design: OpenTelemetry Continuous Profiling eBPF Unwind Budget and Stack Depth Guardrail

OpenTelemetry Continuous Profiling eBPF Unwind Budget and Stack Depth Guardrail defines an industrial-grade behavioral standard for devops engineering. Enforces strict instruction budgets, stack-depth bounds, and tail-call execution limits on eBPF continuous profiling probes. Prevents NMI-watchdog lockups, CPU pipeline saturation, and tail latency regressions in mission-critical, low-latency microservices by constraining DWARF/frame-pointer walking iterations. Guarantees predictable agent resource consumption under high-frequency sample rates across Linux kernel fleets. 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 or Deep DWARF Unwinding in eBPF Probes Inducing Kernel Preemption Latency Spikes 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 ModeAI Symptom (The Anti-Pattern)SeverityProduction Impact & Remedy
AI Hallucination & Deprecation DriftUnbounded or Deep DWARF Unwinding in eBPF Probes Inducing Kernel Preemption Latency SpikesCritical
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 InconsistencyAI 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:

1

Engineers MUST ALWAYS enforce a hard upper bound on stack unwinding depth (maximum 128 frames for native code

Engineers MUST ALWAYS enforce a hard upper bound on stack unwinding depth (maximum 128 frames for native code; maximum 64 frames for interpreted runtimes) within eBPF verifier limits.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
2

Engineers MUST NOT execute unbounded loops or unrolled iterations that exceed the kernel BPF instruction budget (max 1M instructions verified, with runtime limits capped at <= 4,000 instructions per sample event).

Engineers MUST NOT execute unbounded loops or unrolled iterations that exceed the kernel BPF instruction budget (max 1M instructions verified, with runtime limits capped at <= 4,000 instructions per sample event).

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
3

Code SHOULD implement adaptive sampling or back-off thresholds that detect NMI/soft-lockup pressure and reduce sampling frequency dynamically if probe execution exceeds 5 microseconds per invocation.

Code SHOULD implement adaptive sampling or back-off thresholds that detect NMI/soft-lockup pressure and reduce sampling frequency dynamically if probe execution exceeds 5 microseconds per invocation.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
4

Services MUST emit a truncated-stack diagnostic metric (e.g., `profiling.unwind.truncated`) whenever unwinding is halted due to budget exhaustion, rather than silently failing or dropping frames.

Services MUST emit a truncated-stack diagnostic metric (e.g., `profiling.unwind.truncated`) whenever unwinding is halted due to budget exhaustion, rather than silently failing or dropping frames.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
5

Components NEVER fall back to full userspace DWARF evaluation inside kernel space

Components NEVER fall back to full userspace DWARF evaluation inside kernel space; complex table lookups must rely on compact, pre-parsed `.eh_frame_hdr` or frame-pointer records mapped to static BPF perf rings.

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.
Enforcement:Integrated into the Agent Pack rule file. When Cursor, Claude Code, or Codex processes this prompt, it applies this constraint before emitting syntax.
Technical Questions & Answers

Frequently Asked Technical Questions

Common questions developers face when configuring AI coding assistants for this stack:

Q:Why is OpenTelemetry Continuous Profiling eBPF Unwind Budget and Stack Depth Guardrail critical for AI coding assistants?

Enforces strict instruction budgets, stack-depth bounds, and tail-call execution limits on eBPF continuous profiling probes. Prevents NMI-watchdog lockups, CPU pipeline saturation, and tail latency regressions in mission-critical, low-latency microservices by constraining DWARF/frame-pointer walking iterations. Guarantees predictable agent resource consumption under high-frequency sample rates across Linux kernel fleets. Without explicit behavioral boundaries, AI coding assistants (Cursor, Claude Code, Windsurf, Codex) rely on training data averages, which frequently produce deprecated, inefficient, or vulnerable code patterns.

Q:How does adopting this rule prevent AI hallucinations?

This rule explicitly declares what the AI must avoid (Unbounded or Deep DWARF Unwinding in eBPF Probes Inducing Kernel Preemption Latency Spikes) 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.

Open Specification · CC BY 4.0·Free for Personal, Team & Commercial In-Repo Use

Citation & Open Source Attribution Guidelines

This specification is licensed under Creative Commons Attribution 4.0 International (CC BY 4.0). You are completely free to adapt and share this rule in your workspace. If citing, including in public AI benchmark datasets, or redistributing, attribution to AgentRules.org is required.

Related DEVOPS Rules

View all rules →
devops
86

Kubernetes Gateway API v1 HTTPRoute Canary and ReferenceGrant Invariants

Enforces strict conformance to Kubernetes Gateway API v1 specifications during migration from legacy Ingress controllers. Mandates explicit ReferenceGrant resources for cross-namespace routing, strict relative integer weighting for HTTPRoute canary releases, and explicit backendRef port declarations.

devops
118

ArgoCD ApplicationSet Matrix Generator Invariants & Cascade Deletion Guards

Enforces strict structural constraints on ArgoCD ApplicationSet Matrix generators combining cluster selectors and Git directories. Prevents catastrophic multi-cluster cascade pruning, accidental secret exposure through parameter interpolation, and runaway Application CR explosion via explicit sync policies, preservation finalizers, and parameter validation.

devops
40

Karpenter Resilient Topology, Interruption Queue, and Consolidation Budget Standard

Enforces deterministic disruption budgets, multi-instance-type diversification, and event-driven SQS interruption queue handling across Karpenter NodePools and EC2NodeClasses. Eliminates cascading eviction loops, instance starvation, and availability downtime during AWS Spot rebalances and underutilized node consolidation.

1 Rule in Stack

OpenTelemetry