Traces
A trace is an immutable, append-only record of everything that happens during a plan execution. Traces are not logs — they are structured, replayable execution records that drive auditing, debugging, regression testing, and plan promotion.
What Traces Record
Section titled “What Traces Record”Every execution produces a trace containing a sequence of trace entries. Each entry records a specific event:
| Entry Type | What It Records |
|---|---|
PLAN_GENERATED | The Plan Draft and Full Plan IR produced by the Planner |
STEP_STARTED | When a capability invocation begins, with resolved inputs |
STEP_COMPLETED | When a capability invocation succeeds, with outputs |
STEP_FAILED | When a capability invocation fails, with error details |
GATE_TRIGGERED | When a policy gate pauses execution for approval |
GATE_RESOLVED | When a gate is approved or rejected |
INTERACTION_REQUESTED | When a capability requests user input |
INTERACTION_RECEIVED | When the user responds to an interaction |
OUTBOX_STAGED | When an external side effect is staged |
OUTBOX_COMMITTED | When staged side effects are committed |
EXECUTION_COMPLETED | When the full plan execution finishes |
EXECUTION_FAILED | When execution fails with error context |
Trace Levels
Section titled “Trace Levels”Traces support three levels of detail, configured per-deployment:
| Level | What Is Recorded | Use Case |
|---|---|---|
minimal | Execution start/end, step outcomes, errors only | Production auditing with minimal storage |
standard | All events above plus resolved inputs/outputs | Default for most deployments |
verbose | Everything including internal pipeline details and LLM call traces | Debugging and development |
Configure the trace level in your Zakardo config:
const config: ZakardoConfig = { // ... trace: { level: 'standard' },};Querying Traces
Section titled “Querying Traces”The Trace Reader provides a query interface for finding and inspecting traces:
import { TraceReader } from '@zakardo/core';
// Get all traces for an executionconst traces = traceReader.getByExecution(executionId);
// Filter by entry typeconst failures = traceReader.getByExecution(executionId, { entryTypes: ['STEP_FAILED', 'EXECUTION_FAILED'],});Via the REST API:
# List traces for an executioncurl http://localhost:3000/zakardo/v1/traces?execution_id=exec_abc123
# Get a specific trace with all entriescurl http://localhost:3000/zakardo/v1/traces/trace_abc123Traces vs Logs
Section titled “Traces vs Logs”| Property | Traditional Logs | Zakardo Traces |
|---|---|---|
| Structure | Unstructured text, grep-friendly | Structured JSON, typed entries |
| Completeness | Partial, depends on what developers log | Complete — every execution event |
| Replayability | Not replayable | Replayable — contains all inputs and outputs |
| Immutability | Mutable log files | Immutable, append-only |
| Purpose | Debugging after the fact | Auditing, regression testing, plan promotion, debugging |
Trace-Based Features
Section titled “Trace-Based Features”Traces power several Zakardo subsystems:
- Training System — Training runs execute plans and compare trace outputs against expected results
- Plan Library — Trust scores are computed from trace data (success rates, execution times)
- Regression Detection — New training runs are compared against previous runs using trace data
- Studio Trace Viewer — The Studio visualizes traces as interactive timelines
Viewing Traces in Studio
Section titled “Viewing Traces in Studio”The Zakardo Studio Trace Viewer provides:
- Timeline view — see all execution events in chronological order
- Step inspection — click any step to see resolved inputs, outputs, and timing
- Error details — failed steps show full error context with stack traces
- Gate/interaction history — see when gates were triggered and how they were resolved
Further Reading
Section titled “Further Reading”- Execution Engine API — how the engine produces trace entries
- Training & Validation API — how traces drive regression testing
- Trace System Specification — full specification