Retain logs that answer concrete troubleshooting questions. Recording every prompt and payload may expose unnecessary data while still failing to show whether the customer’s business operation completed.
Log selection starts with failure questions
Troubleshooting log selection identifies the minimum events and fields needed to investigate defined failure classes. Useful questions include whether a call arrived, a transfer was accepted, a tool rejected input, or a write remained uncertain.
In a proposed event catalogue, record interaction and operation references, configuration versions, stage transitions, safe error categories, and authoritative result references. Keep execution attempts separate from logical business operations so retries can be reconstructed.
OWASP’s logging guidance addresses event design, data exclusion, protection, and verification. Use those principles to build a purposeful catalogue rather than enabling indiscriminate payload capture.
Diagnose a fictional failed save
Staff report that a caller heard confirmation but no request is visible. The useful log chain shows the confirmation claim, operation reference, write rejection category, and deployed adapter version. It does not need to include the caller’s full address to establish that the adapter mishandled the result.
For a recognition dispute about a name, those events may not resolve what was pronounced. State that limitation. Additional collection should follow an approved purpose and policy rather than becoming a permanent default because one incident was difficult.
| Diagnostic question | Event to retain |
|---|---|
| Did telephone ingress occur? | Route and call mapping reference |
| Which proposal executed? | Intent revision and operation identity |
| Why did validation fail? | Safe category and contract version |
| Did the write commit? | Authoritative result or unknown state |
| Which release was running? | Prompt, model, tool, and runtime versions |
Test whether an authorised reviewer can resolve fictional incidents using only the proposed logs. Also test that prohibited synthetic markers do not appear in exports.
Assign retention and access per category
Short-lived detailed diagnostics and longer-lived minimal operation records may serve different purposes. Set periods only after the actual operational, contractual, and legal requirements are established. Do not assume one storage setting reaches every exporter and backup.
Minimal logs reduce exposure and cost, but can limit nuanced conversation analysis. Make that tradeoff explicit and preserve controlled routes to authorised source evidence where policy permits. Log volume alone is not a measure of investigability.
This catalogue is proposed. The voice platform case study describes related integration work. Pair it with diagnostic retention design.
Troubleshooting log FAQ
Should raw tool arguments always be logged?
No. Prefer safe fields and controlled source references unless a defined purpose justifies more.
Are errors alone enough?
Usually not. Stage and operation context are needed to establish what happened before and after the error.
How should the catalogue evolve?
Add fields when a demonstrated investigation gap justifies them, then verify minimisation, access, retention, and diagnostic usefulness.