axon trace - AXON

The axon trace command renders execution traces as human-readable timelines, making it easy to debug flow execution, identify bottlenecks, and analyze model behavior.

Synopsis

axon trace <file.trace.json> [--no-color]

Description

Reads a .trace.json file (produced by axon run --trace) and renders it as a formatted timeline with:

Step boundaries and durations
Model API calls with token counts
Anchor checks (pass/breach)
Validation results
Retry attempts and refinement loops
Memory operations
Confidence checks

Traces provide complete observability into AXON program execution.

Arguments

file

string

required

Path to the .trace.json file to visualize

Options

--no-color

flag

Disable ANSI color codes in output (useful for log files or non-TTY environments)

Exit Codes

Code	Meaning
`0`	Success — trace rendered
`2`	File not found or invalid JSON

Output Format

Trace Timeline

$ axon trace contract_analyzer.trace.json

════════════════════════════════════════════════════════════
  AXON Execution Trace
════════════════════════════════════════════════════════════
  source: contract_analyzer.axon
  backend: anthropic

  ┌─ Flow: AnalyzeContract (1247ms)
  │ [step_start]  Extract
  │ [model_call]  claude-3-5-sonnet-20241022
  │   prompt_tokens: 342
  │   completion_tokens: 156
  │ [validation_pass]  EntityMap
  │ [step_end]  Extract
  │ 
  │ [step_start]  Assess
  │ [anchor_check]  NoHallucination
  │ [anchor_pass]  confidence: 0.87
  │ [model_call]  claude-3-5-sonnet-20241022
  │   prompt_tokens: 498
  │   completion_tokens: 243
  │ [validation_pass]  RiskAnalysis
  │ [step_end]  Assess
  └─

════════════════════════════════════════════════════════════

Event Color Coding

When colors are enabled (default):

Event Type	Color
`step_start`, `step_end`	Cyan
`model_call`, `model_response`	Magenta
`anchor_pass`, `validation_pass`	Green
`anchor_breach`, `validation_fail`	Red
`retry_attempt`, `refine_start`, `anchor_check`	Yellow
`memory_read`, `memory_write`, `confidence_check`	Dim gray

Trace Structure

Execution traces are JSON files with this structure:

{
  "_meta": {
    "source": "program.axon",
    "backend": "anthropic",
    "axon_version": "0.4.0a0",
    "start_time": "2026-03-06T15:23:45.123Z",
    "duration_ms": 1247
  },
  "spans": [
    {
      "name": "Flow: AnalyzeContract",
      "duration_ms": 1247,
      "events": [ ... ],
      "children": [ ... ]
    }
  ],
  "events": [ ... ]
}

Event Types

AXON traces include 14 event types:

Execution Events

step_start

event

Marks the beginning of a flow stepData: step_name, inputs

step_end

event

Marks the completion of a flow stepData: step_name, outputs, duration_ms

Model Interaction

model_call

event

LLM API request initiatedData: model, prompt_tokens, temperature, max_tokens

model_response

event

LLM API response receivedData: completion_tokens, finish_reason, content_preview

Validation & Anchors

anchor_check

event

Anchor constraint being evaluatedData: anchor_name, constraint_type

anchor_pass

event

Anchor constraint satisfiedData: anchor_name, confidence

anchor_breach

event

Anchor constraint violatedData: anchor_name, violation_reason, severity

validation_pass

event

Output type validation succeededData: expected_type, actual_type

validation_fail

event

Output type validation failedData: expected_type, actual_type, reason

retry_attempt

event

Retry engine attempting recoveryData: attempt_number, max_attempts, failure_context

refine_start

event

Refinement loop initiatedData: reason, previous_output

Memory Operations

memory_read

event

Reading from persistent memoryData: key, value_preview

memory_write

event

Writing to persistent memoryData: key, value_preview

Epistemic Checks

confidence_check

event

Confidence threshold evaluationData: actual_confidence, required_confidence, passed

Examples

Basic Trace Visualization

# Generate trace during execution
axon run program.axon --trace

# Visualize the trace
axon trace program.trace.json

Non-Interactive Output

axon trace program.trace.json --no-color > trace.log

Save trace output to a file without color codes.

Filtering with jq

# Extract all model calls
cat program.trace.json | jq '.events[] | select(.type == "model_call")'

# Count retry attempts
cat program.trace.json | jq '[.events[] | select(.type == "retry_attempt")] | length'

# Find anchor breaches
cat program.trace.json | jq '.events[] | select(.type == "anchor_breach")'

# Calculate total tokens
cat program.trace.json | jq '
  [.events[] | select(.type == "model_call" or .type == "model_response") | 
   .data.prompt_tokens // 0, .data.completion_tokens // 0] | add
'

Comparing Traces

# Run with different backends
axon run program.axon --backend anthropic --trace
mv program.trace.json program.anthropic.trace.json

axon run program.axon --backend openai --trace
mv program.trace.json program.openai.trace.json

# Compare token usage
for file in *.trace.json; do
  echo "$file:"
  cat "$file" | jq '[.events[] | select(.type=="model_call") | 
    .data.prompt_tokens // 0] | add'
done

Debugging Failures

# Run and trace
axon run failing_program.axon --trace

# Visualize to find the failure point
axon trace failing_program.trace.json

# Extract error details
cat failing_program.trace.json | jq '.events[] | 
  select(.type == "anchor_breach" or .type == "validation_fail")'

Trace Analysis

Performance Profiling

Identify slow steps:

cat program.trace.json | jq '.spans[] | {name, duration_ms}'

Output:

{"name": "Extract", "duration_ms": 342}
{"name": "Assess", "duration_ms": 567}
{"name": "Report", "duration_ms": 183}

Token Usage Analysis

cat program.trace.json | jq '
  .events[] | 
  select(.type == "model_call" or .type == "model_response") |
  {type, tokens: (.data.prompt_tokens // 0) + (.data.completion_tokens // 0)}
'

Retry Pattern Detection

cat program.trace.json | jq '
  [.events[] | select(.type == "retry_attempt")] | 
  group_by(.data.step_name) | 
  map({step: .[0].data.step_name, retries: length})
'

Anchor Effectiveness

cat program.trace.json | jq '
  {total: [.events[] | select(.type == "anchor_check")] | length,
   passed: [.events[] | select(.type == "anchor_pass")] | length,
   breached: [.events[] | select(.type == "anchor_breach")] | length}
'

Integration Examples

CI/CD Trace Collection

# .github/workflows/test.yml
- name: Run AXON Tests
  run: |
    axon run test.axon --trace
    axon trace test.trace.json --no-color > test_output.log

- name: Upload Trace
  uses: actions/upload-artifact@v3
  with:
    name: execution-trace
    path: test.trace.json

Automated Performance Testing

#!/bin/bash
# perf_test.sh

for i in {1..10}; do
  echo "Run $i"
  axon run program.axon --trace
  mv program.trace.json "traces/run_$i.trace.json"
done

# Aggregate results
for file in traces/*.trace.json; do
  echo -n "$file: "
  cat "$file" | jq '._meta.duration_ms'
done | awk '{sum+=$2; count++} END {print "Average:", sum/count, "ms"}'

Log Aggregation

# Send traces to logging service
axon run program.axon --trace
cat program.trace.json | \
  jq -c '.events[]' | \
  while read event; do
    curl -X POST https://logs.example.com/api/v1/logs \
      -H "Content-Type: application/json" \
      -d "$event"
  done

Troubleshooting

Invalid JSON

✗ Invalid JSON: Unexpected token at position 123

Cause: Corrupted trace file. Solution: Regenerate the trace:

axon run program.axon --trace

File Not Found

✗ File not found: program.trace.json

Solution: Ensure --trace was used during execution:

axon run program.axon --trace  # Generates .trace.json

Empty Trace

Cause: Execution failed before trace capture. Solution: Check execution errors first:

axon run program.axon  # Without --trace

run

Generate traces with —trace flag

Debugging Guide

Learn debugging techniques

Advanced Usage

Custom Trace Processing

Create a Python script to analyze traces:

import json
import sys

with open(sys.argv[1]) as f:
    trace = json.load(f)

# Extract key metrics
model_calls = [e for e in trace['events'] if e['type'] == 'model_call']
total_tokens = sum(
    e['data'].get('prompt_tokens', 0) + 
    e['data'].get('completion_tokens', 0) 
    for e in model_calls
)

print(f"Total API calls: {len(model_calls)}")
print(f"Total tokens: {total_tokens}")
print(f"Duration: {trace['_meta']['duration_ms']}ms")

Run it:

python analyze_trace.py program.trace.json

Commands

Configuration

​Synopsis

​Description

​Arguments

​Options

​Exit Codes

​Output Format

​Trace Timeline

​Event Color Coding

​Trace Structure

​Event Types

​Execution Events

​Model Interaction

​Validation & Anchors

​Retry & Refinement

​Memory Operations

​Epistemic Checks

​Examples

​Basic Trace Visualization

​Non-Interactive Output

​Filtering with jq

​Comparing Traces

​Debugging Failures

​Trace Analysis

​Performance Profiling

​Token Usage Analysis

​Retry Pattern Detection

​Anchor Effectiveness

​Integration Examples

​CI/CD Trace Collection

​Automated Performance Testing

​Log Aggregation

​Troubleshooting

​Invalid JSON

​File Not Found

​Empty Trace

​Related Commands

run

Debugging Guide

​Advanced Usage

​Custom Trace Processing

Build docs developers (and LLMs) love

Synopsis

Description

Arguments

Options

Exit Codes

Output Format

Trace Timeline

Event Color Coding

Trace Structure

Event Types

Execution Events

Model Interaction

Validation & Anchors

Retry & Refinement

Memory Operations

Epistemic Checks

Examples

Basic Trace Visualization

Non-Interactive Output

Filtering with jq

Comparing Traces

Debugging Failures

Trace Analysis

Performance Profiling

Token Usage Analysis

Retry Pattern Detection

Anchor Effectiveness

Integration Examples

CI/CD Trace Collection

Automated Performance Testing

Log Aggregation

Troubleshooting

Invalid JSON

File Not Found

Empty Trace

Related Commands

Advanced Usage

Custom Trace Processing