Capturing Stack Traces
An error message tells you what went wrong. A stack trace tells you how the code arrived there — and that is usually the harder half of the question.
Where to find it
Architect Panel → Configuration:
- Site Settings — Capture Stack Trace, and the limit and argument settings
Architect Panel → Activity:
- Error Log — the entries traces are attached to
What a trace gives you
The chain of calls that led to the failure. "Undefined value" on its own is nearly useless when the same function is reached from a dozen places; the trace tells you which route was taken this time.
For intermittent problems it is often the only useful evidence, because the conditions cannot be reproduced on demand.
Turning it on
Capture Stack Trace enables it. It is worth having on: the cost is a modest amount of storage per error, and on a healthy system there are not many errors.
The reasonable exception is an installation logging errors in very high volume — but that is a signal to fix the errors rather than to stop describing them.
Traces contain data
This is the important caveat, and it is why the related settings exist. A trace records the path through the code, and depending on configuration it can also record the values being passed along that path.
That makes the error log more sensitive than it first appears. Treat access to it as you would access to the data it describes, and see the article on including arguments before turning that option on.
Use it with the error log, not instead of it
The trace explains one occurrence. The pattern across the log — when it started, how often, from which addresses — explains the problem. Investigations that read one trace closely and never look at the surrounding entries usually fix a symptom.
Deployment is the moment that matters
Most new error types appear immediately after a change. A trace captured in the first hours after a deployment is worth more than the same trace found a fortnight later, because the change that caused it is still obvious.
Worked example
An intermittent failure appears a few times a week with a message that identifies nothing. With traces enabled, three occurrences show the same route into the failing function — from a scheduled task rather than from the interface, which nobody had considered. The cause is a record the task processes that the interface never produces. Without a trace, the investigation had been stuck for a month.
Recommendations
- Keep trace capture enabled.
- Read the log around a trace, not just the trace.
- Check the log soon after every deployment.
- Treat the error log as sensitive once traces are on.