Stack Trace Capture

Beyond the basic enable/disable, the stack trace capture engine has several tuning knobs. This article covers them in detail so you can balance diagnostic value, storage cost and privacy concerns.

Available Settings

• Max frames: Cap the depth of captured traces. Defaults to 50.
• Include arguments: See dedicated article.
• Include locals: Capture local variables at each frame (expensive, valuable).
• Skip vendor frames: Hide frames inside vendor/ (Composer libraries) — keeps traces focused on your code.
• Skip framework frames: Hide framework internals — even narrower focus.
• Redaction patterns: Regex list applied to argument names.
• Sample rate: Capture full traces on X% of errors; rest get minimal.

Recommended Combinations

• Dev: 100 frames, arguments + locals on, no skipping. Maximum detail.
• Staging: 75 frames, arguments on, locals off, skip vendor frames.
• Production (low traffic): 50 frames, arguments off, skip vendor + framework.
• Production (high traffic): 30 frames, arguments off, sampled at 5%, skip vendor + framework.

Why Skip Frames

A typical request goes through 20+ framework frames before reaching your code. Capturing those doesn't help debug your code — your bug is almost always in your code. Skipping them halves the trace size and makes the useful part stand out.

Worked Examples

• Performance investigation: Locals on temporarily to see what data the slow function was processing.
• Privacy-strict environment: Arguments off, plus aggressive redaction regex covering several custom field names.
• Storage budget: 30 frames + sample rate 10% keeps the error-log table from growing too fast.
• Library bug suspected: Skip vendor frames temporarily turned off so the library's internal call chain is visible.

How many frames is too many? How few is too few? Stack frame limits are a balance — too low and you miss the cause; too high and traces become unreadable and storage-expensive.

Default Limits

• Production default: 50 frames.
• Truncation indicator: If more frames exist, the trace shows “… 17 more frames omitted”.
• Per-frame size cap: Each frame's argument dump capped at 4KB.
• Total size cap: Trace truncated if it exceeds 64KB total.

How Many Frames Do You Really Need?

• The most useful frames are usually the bottom 5-10 (where the exception originated) and the top 2-3 (the entry point and controller).
• Middle frames are mostly framework plumbing.
• If you skip vendor/framework frames, your own code is typically 5-15 frames — perfectly readable.

When to Raise the Limit

• Deeply recursive code where the recursion path is the bug.
• Stack overflows — you need to see the full chain to find the cycle.
• Multi-tier framework debugging where the framework's internal path matters.

When to Lower the Limit

• Storage cost is squeezing.
• Most errors are simple and don't need deep traces.
• You consistently skip past the deep frames anyway.

Worked Examples

• API service: 30 frames with vendor/framework skip — typically captures 8-12 own-code frames. Clean and focused.
• Recursive workflow: Raise to 200 for one workflow type that has up to 50 levels of recursion.
• Storage tight: Lower to 20 frames + 32KB total cap. Loses some detail on deep paths but saves significant space.