Skip to content

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.

Every execution produces a trace containing a sequence of trace entries. Each entry records a specific event:

Entry TypeWhat It Records
PLAN_GENERATEDThe Plan Draft and Full Plan IR produced by the Planner
STEP_STARTEDWhen a capability invocation begins, with resolved inputs
STEP_COMPLETEDWhen a capability invocation succeeds, with outputs
STEP_FAILEDWhen a capability invocation fails, with error details
GATE_TRIGGEREDWhen a policy gate pauses execution for approval
GATE_RESOLVEDWhen a gate is approved or rejected
INTERACTION_REQUESTEDWhen a capability requests user input
INTERACTION_RECEIVEDWhen the user responds to an interaction
OUTBOX_STAGEDWhen an external side effect is staged
OUTBOX_COMMITTEDWhen staged side effects are committed
EXECUTION_COMPLETEDWhen the full plan execution finishes
EXECUTION_FAILEDWhen execution fails with error context

Traces support three levels of detail, configured per-deployment:

LevelWhat Is RecordedUse Case
minimalExecution start/end, step outcomes, errors onlyProduction auditing with minimal storage
standardAll events above plus resolved inputs/outputsDefault for most deployments
verboseEverything including internal pipeline details and LLM call tracesDebugging and development

Configure the trace level in your Zakardo config:

const config: ZakardoConfig = {
// ...
trace: { level: 'standard' },
};

The Trace Reader provides a query interface for finding and inspecting traces:

import { TraceReader } from '@zakardo/core';
// Get all traces for an execution
const traces = traceReader.getByExecution(executionId);
// Filter by entry type
const failures = traceReader.getByExecution(executionId, {
entryTypes: ['STEP_FAILED', 'EXECUTION_FAILED'],
});

Via the REST API:

Terminal window
# List traces for an execution
curl http://localhost:3000/zakardo/v1/traces?execution_id=exec_abc123
# Get a specific trace with all entries
curl http://localhost:3000/zakardo/v1/traces/trace_abc123
PropertyTraditional LogsZakardo Traces
StructureUnstructured text, grep-friendlyStructured JSON, typed entries
CompletenessPartial, depends on what developers logComplete — every execution event
ReplayabilityNot replayableReplayable — contains all inputs and outputs
ImmutabilityMutable log filesImmutable, append-only
PurposeDebugging after the factAuditing, regression testing, plan promotion, debugging

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

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