Stack Trace Capture

Stack Trace Capture Settings

Three settings govern what a stack trace contains. They interact, so it is worth seeing them together rather than one at a time.

Where to find it

Architect Panel → Configuration:

• Site Settings — Capture Stack Trace, Include Arguments in Stacktrace, Stack Frame Limit

Architect Panel → Activity:

• Error Log — the result

The three settings

• Capture Stack Trace — whether a trace is recorded at all. Everything else depends on this.
• Include Arguments in Stacktrace — whether the values passed to each frame are recorded.
• Stack Frame Limit — how many frames are kept.

How they combine

The limit multiplies the effect of arguments. A four-frame trace with arguments records the values passed to four calls; a fifty-frame trace with arguments records fifty. The storage and the exposure both scale with the product of the two, not with either alone.

That is why a large limit and arguments together is the combination to avoid, and why raising one should prompt a look at the other.

Sensible combinations

• Production — capture on, arguments off, a small limit. Enough to see the route without accumulating data.
• Development — capture on, arguments on, a larger limit. Maximum information, no real data at risk.
• Production, investigating — arguments temporarily on, limit unchanged, both reverted afterwards.

Change one thing at a time

When a trace is not telling you enough, raise the limit first. It is the cheaper of the two adjustments and it frequently resolves the problem on its own, because the missing context is usually a caller further out rather than a value.

Reach for arguments only when the route is clear and the failing value is not.

Verify after cloning an environment

These settings travel with a configuration copy. A production instance built from a development snapshot will carry development's settings — arguments on, a generous limit — and nothing will draw attention to it.

Add it to whatever checklist you use when standing up an environment.

They apply to errors, not to normal operation

Nothing here is recorded during ordinary use; these settings only take effect when an error occurs. The performance question is therefore about how many errors you have rather than how much traffic — another reason a rising error rate deserves attention.

Worked example

A team runs production with capture on, arguments off and a limit of four. An obscure failure produces a trace that stops short of anything meaningful, so they raise the limit to twelve for a week. The extra frames show the call originating in a scheduled task, which is enough — arguments are never needed, and the limit goes back to four.

Recommendations

• Capture on, arguments off, small limit in production.
• Raise the limit before enabling arguments.
• Never combine a large limit with arguments on live data.
• Check these settings whenever you clone an environment.

Stack Frame Limits

The Stack Frame Limit is the maximum number of frames recorded with an error. It ships small, and that is usually correct.

Where to find it

Architect Panel → Configuration:

• Site Settings — Stack Frame Limit

Architect Panel → Activity:

• Error Log — where the recorded frames appear

What a frame is

One step in the chain of calls. The first frame is where the error occurred, the second is what called that, and so on outwards. A limit of four keeps the four nearest and discards the rest.

Why nearest-first is the right end to keep

The frames closest to the failure are almost always the informative ones. The outer frames tend to be the same general machinery on every request, so keeping them costs storage and tells you little.

This is also why a small limit is a reasonable default rather than a compromise — it keeps the part you would read.

When to raise it

Raise it when traces are consistently stopping just short of something useful — typically when the error occurs in shared code reached from many places, and the four nearest frames are identical every time.

Go up in steps. Doubling is usually enough, and going straight to a very large number produces traces nobody reads and, with arguments enabled, a great deal of captured data.

What it costs

Storage per error, multiplied by your error rate. On its own that is minor. Combined with argument capture it is not, because each additional frame brings the values passed to another call.

If you are raising the limit on a system with arguments enabled, consider turning arguments off first.

It does not change what failed

Worth stating because it catches people out: raising the limit does not produce more errors or different ones, and lowering it does not hide problems. It only changes how much of the route is described. If a trace is unhelpful, the limit is one possible reason — the error message and the surrounding log entries are others.

Put it back afterwards

A limit raised for one investigation tends to stay raised. Note the original value when you change it, and restore it when you are done — otherwise you accumulate a setting nobody remembers choosing.

Worked example

A platform runs with a limit of four. A recurring error in a shared validation routine produces four identical frames every time, saying only that validation failed somewhere. The limit goes to eight; the extra frames show two distinct callers, one of which is a form nobody had associated with the problem. The fix takes an hour, and the limit returns to four the same day.

Recommendations

• Leave it small by default.
• Raise in steps, and only when traces stop short.
• Turn arguments off before raising it on a live system.
• Record the original value and restore it afterwards.