Tracing is optional. Without it, the ledger and reports already hold every result. With it, you can inspect each run in neatlogs, next to your agent's own traces.
Turn it on#
Give Culprit a neatlogs API key. culprit init asks for one, or set NEATLOGS_API_KEY in your shell
or the repo's .env. See Configuration.
Without a key, tracing is off and Culprit prints neatlogs tracing off (no NEATLOGS_API_KEY) at the
end of a run.
What is traced#
- Every command is one trace, labelled with the workflow
culprit. Its session ID is the run ID, so you can find a run's traces by searching for it. - Every step is a span: git operations, worktrees, installs, each agent run, each decision with its interval and threshold, and fetching the intent.
- Culprit's own model calls are captured with their prompts, responses and token counts.
- Every span carries the run ID and the commit SHA, so you can filter a trace to one commit.
If your agent also traces with neatlogs and reports trace_id in its JSON line, each data point in a
bisect links to the agent's own trace for that run. Culprit passes CULPRIT_RUN_ID, COMMIT_SHA,
TASK_ID and REPETITION so your agent can tag its traces the same way.
Verify a run's traces#
culprit verify-trace <run_id>Reads the run's traces back from neatlogs and checks them against what Culprit should have recorded:
that each trace is finalised, has the right workflow and session, and has the expected spans. It needs
the neatlogs CLI installed and logged in, since an ingest key can't read traces. If the CLI isn't on
your PATH, set NEATLOGS_CLI in your shell to its location.