Skip to main content
Version: 1.1.0

Read execution traces

A trace records the calls, decisions and checks of an execution. Start with its final status, then follow the events that explain the outcome.

Produce and read a trace​

touba run programme.air.json --entry strategy:app/Run --trace-out trace.json
touba inspect trace.json

Use your program’s entry point. The inspector summarizes the execution and its notable events. Open the exported file to read the event details. In VS Code, Touba: Render Trace provides a text view; Touba: Open Trace Event Source locates the source when the matching artifacts are available.

Find the relevant events​

ElementWhat to read
Final status and reasonResult, wait, refusal or execution error
call_started / call_completedStart and completion of a call
Agent and resourceResponsible context and declared target
Human decisionRecorded request, response and resumption
Budgets and refusalsReached limit or missing authorization

Context identifiers relate calls within an execution. The trace reference describes their structure.

Persistent journals​

Trace storage covers SQLite, paginated reading and PostgreSQL export. A trace reference identifies one journal segment; keep the reference and its matching storage together.

Prepare an audit​

touba audit --trace trace.json --air programme.air.json --output text

The audit guide explains the checks and supporting artifacts. Review data and identifiers before sharing an export.

For a hands-on example: read your first trace.