> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vinmake.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracing a run

> Every deployed graph traces into one project, separable by root run name. What a trace shows, what it does not, and why.

# Tracing a run

Every one of the five deployed graphs emits a trace, with a child span per node.

## One project, five root names

All five write into a single tracing project.

They are separable because **the compiled graph name is the root run name**: `clerk`, `bookkeeper`, `auditor`, `accountant`, `typewriter`.
Filter on run name.

Per-agent *projects* are not achievable without a code change, because one service process hosts all the graphs and the project setting is process-wide.
Adding per-agent tags is a one-line change per agent, deliberately not made as part of a build-and-stage task: it wraps the compiled graph in a binding the platform server introspects, and validating that belongs with a deploy.

<Note>
  Eval experiments are deliberately **kept out** of that project.
  Each graded run writes to its own experiment project, so a graded run never mixes with production traffic.
</Note>

## What a trace actually looks like

Three real traces, sampled during a baseline run.

| Root run     | Spans | Node spans                                                                                                                                                                                                                    |
| ------------ | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `clerk`      | 18    | `intake_router, ingest, classify, load_registry, sop_retrieve, extract, resolve_and_map, validate,` **`extract, resolve_and_map, validate, extract, resolve_and_map, validate,`** `braintrust_ground_and_judge, route, queue` |
| `bookkeeper` | 4     | `ingest, match, propose` - **stops at the posting gate, as designed**                                                                                                                                                         |
| `auditor`    | 4     | `scope_gate, audit, answer`                                                                                                                                                                                                   |

Two of those are worth reading closely.

**The Clerk's 18 spans show the bounded repair loop firing twice.**
`validate` failed a shape check, re-prompted `extract`, and the cycle ran twice more before the record went to routing.
That is real control flow rendered as a trace, not a flat list of steps.

**The Bookkeeper's four spans are quietly the best evidence in the whole system.**
The trace *itself* shows the graph stopping at the gate.
Not a log line claiming it stopped: the absence of a `post` span, in a graph that has one.

The Clerk's chat path traces separately as `intake_router, scope_gate, scoped_answer, output_check`, or ending in `decline`.

Child spans carry step tags plus the assistant and checkpoint identifiers, so a paused run can be tied to the checkpoint a resume will restore.

## The honest gap

<Warning>
  **There are no model-call runs in the trace.**

  Model calls go through the keyless Agent SDK, which shells out to the local CLI. So the tracer sees the **node span** but not token counts, not model latency, and not the prompt or response bodies for the call itself.

  Tracing is healthy for **graph** observability.
  It is not currently giving you model-level cost and latency telemetry.
</Warning>

That is a real limitation of the keyless model path, and it is the trade for not holding an API key in the deployment.
It is stated here rather than left for someone to discover while trying to attribute a cost.

## Checking that tracing is alive

```bash theme={null}
make eval-health
```

Reports whether the key authenticates, which project the runs are landing in, when the last run was, and the root run names in the recent history.

Note what it does **not** do: trust the configured project name.

<Note>
  **A configuration drift worth knowing about.**
  One environment file sets the tracing project to a name no project matches; every trace lands in the real project anyway, because that file is **not** what the deployed service reads for this variable.

  Harmless today, and misleading tomorrow.
  The health probe therefore reports project drift explicitly rather than trusting the environment variable, which is the right posture for any check that could otherwise pass by reading its own configuration.
</Note>

## Reading a trace when something went wrong

| Symptom in the trace                                      | What it usually means                                                                                                                      |
| --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| a `bookkeeper` run with a `post` span and no ledger entry | look at the refusal - the mandate, the separation-of-duties check, or an unmapped account                                                  |
| a `bookkeeper` run that re-enters and pauses again        | another graph ran on that thread and overwrote its channels. See [the Bookkeeper](/greatbook/agents/bookkeeper)                            |
| a `clerk` run ending at `ingest`                          | the run died mid-pipeline. The checkpoint resumes it, and the [Auditor's orphan family](/greatbook/agents/auditor) flags it if it does not |
| the repair loop at its bound                              | the model could not produce a schema-valid shape. The record flags for a human, which is the designed outcome                              |
| an `auditor` run with fewer families than requested       | a read failed. Those come back **inconclusive**, never as a pass                                                                           |

## Where it is enforced

| Concern                                             | Code                                                  |
| --------------------------------------------------- | ----------------------------------------------------- |
| the health probe                                    | `langgraph_chat/agents/evals/langsmith_sync.health()` |
| the tracing environment                             | the deploy manifest and `DEPLOY.md`                   |
| the compiled graph names that become root run names | each agent's `app.py`                                 |

## Related

* [The agent org](/greatbook/agents/index) - the five graphs that trace
* [The Bookkeeper](/greatbook/agents/bookkeeper) - the four-span trace and what it proves
* [The Clerk](/greatbook/agents/clerk) - the repair loop the 18-span trace shows
* [Reading a run](/greatbook/proof/traces) - the same traces, rendered three ways