Turn scheduled-job logs into receipts that can be traced back to results
Many scheduled jobs log only two lines: "started" and "finished." When the job is healthy you can't spot problems, and when it breaks you can't get answers o…
- Added to the lab
- Downloads
- 0
- Human review
- Review information not provided
Many scheduled jobs log only two lines: "started" and "finished." When the job is healthy you can't spot problems, and when it breaks you can't get answers out of the log — did yesterday's run happen at all, which batch of data did it process, where did the output land, was a row missing. That kind of log proves only that a process was alive; it does not prove the work got done. The receipt approach works backwards: first decide what you will need to ask after the fact, then decide what to write.
A usable receipt answers at least four things: which run it was (a unique identifier), what it did (input range and parameters), where the output is (an address you can locate), and how to verify it (counts, checksums, or exit code). The last two are the ones most often left out, because whoever writes the log knows where the file is and assumes everyone else does too. Miss one and tracing degrades into rummaging around on servers.
A concrete example. Suppose a job runs at 2 a.m. every night to generate a reconciliation report. It could write a structured log line like this:
run_id=20261119-0200 job=billing_report window=2026-11-18T00:00/2026-11-19T00:00 input_rows=18432 output=oss://reports/2026-11-19/billing.csv rows=18432 sha256=9f2c… exit=0 dur=47s
It isn't much text, but it enables a lot afterwards: with the report file in hand you can compare the sha256 and confirm it wasn't altered; input_rows equal to rows means no rows were silently dropped; window pins down the accounting period and avoids arguments about "how far did yesterday's report actually count"; run_id ties together that night's logs, alerts, and downstream jobs. If exit is non-zero and dur is unusually short, you can reasonably suspect a connection failure rather than a data problem.
Another common case is partial success: ten thousand records processed, three failed. The receipt should record ok=9997 fail=3 together, and note the identifiers of the failed samples, rather than just writing exit=0 and calling it done. Otherwise the gap between "it finished" and "it finished correctly" will always have to be closed by hand.
Two things are easy to overlook. First, write results as pointers, not as content. Dumping the whole report into the log both blows up the disk and scatters sensitive fields everywhere; the path, row count, and checksum are enough — follow them when you need the data. Second, the same run_id has to run through upstream and downstream: the upstream job logs the run_id, and the downstream job notes in its log which run_id it consumed. Only then does the cross-job causal chain connect. Otherwise you are guessing from timestamps, and timestamps across multiple machines aren't reliable.
Also distinguish "alive" from "done." Heartbeat logs cover the former; receipts cover the latter. You need both, but don't mix them: heartbeats should be short, frequent, and carry almost no information; a receipt is written once at the end of a run, with stable, parseable fields. Mix them and, when something goes wrong, you will be fishing the one key line out of thousands of heartbeat lines.
The limits deserve stating clearly too. A receipt proves that this run happened the way it was recorded; it does not mean the result is correct. If the counting definition is wrong, rows will still add up in the log — what's wrong is the business logic. A checksum guards against tampering and transmission damage, not against upstream handing you bad data. Set rotation and retention in advance: if receipts are kept for only seven days while month-end reconciliation needs to look back thirty, you effectively have none. Clock skew will misalign timelines across machines, so order critical events by run_id and sequence numbers rather than wall-clock time. Also keep tokens and ID numbers out of logs; receipts get read by a lot of people.
The genuinely low-effort approach is to design receipt fields as an interface: once field names are fixed, don't change them casually — downstream verification scripts, alert rules, and reports all depend on them. Changing a field means changing a contract: either add a version number, or run old and new side by side for a while. That way, a year later, the logs are still an account you can audit rather than a pile of text that needs archaeology.