spanforge · Developer Tool · In Development

See inside every agent run.

SpanForge Debug ships developer tools for inspecting, replaying, and visualising SpanForge traces. Span trees, execution timelines, tool-call analysis, cost attribution, and side-by-side trace diffs — via a Python API or a single CLI command.

SpanForge SDK →Validate events →

Installation

Install in seconds.

Requires Python ≥ 3.9 and spanforge >= 1.0.8.

pip install spanforge

Quickstart · CLI

Start from the terminal.

All SpanForge Debug functionality is accessible from the spanforge CLI. Point it at any JSONL file produced by the SpanForge SDK.

bash

TRACE="4bf92f3577b34da6a3ce929d0e0e4736"

# Inspect a single event by event_id
spanforge inspect events.jsonl --event-id $TRACE

# Print span counts and time range
spanforge stats events.jsonl

# Generate a static HTML trace report
spanforge report events.jsonl

# Start a local HTTP trace viewer at /traces
spanforge serve events.jsonl

# Open trace viewer in browser
spanforge ui events.jsonl

Quickstart · Python API

Or use it programmatically.

Import spanforge.debug and call the same functions from your test suite, notebooks, or automation scripts.

python

from spanforge.debug import print_tree, summary, visualize
from spanforge._store import TraceStore

store = TraceStore.load("events.jsonl")
trace = store.get_trace("4bf92f3577b34da6a3ce929d0e0e4736")

# Print span hierarchy tree
print_tree(trace)

# Compact summary: span count, cost, duration, model, status
summary(trace)

# Open visual trace viewer
visualize(trace)

API Reference

All functions at a glance.

Every function accepts a trace_id string and a stream (the output of load_events()). Output format defaults to text; pass output_format="json" for machine-readable output.

replay(trace, stream)Step-by-step interactive replay of an agent run. Prints each span in chronological order.

inspect_trace(trace, stream)Compact summary of a trace: span count, total cost, duration, model, and status breakdown.

print_trace_tree(trace, stream)Renders the parent–child span hierarchy as an indented tree.

timeline(trace, stream)ASCII timeline of span start/end across wall-clock time. Accepts from_ms / to_ms filters.

show_tools(trace, stream)Lists every tool call in the trace with name, arguments, result, latency, and any errors.

show_decisions(trace, stream)Decision-point summary: decision name, confidence score, outcome, and associated span.

cost_summary(trace, stream)Token usage and USD cost totals across the trace, broken down by model.

cost_attribution(trace, stream)Per-span cost and latency table with percentile breakdowns.

batch_report(path)Summarises every trace in a JSONL file — counts, totals, error rates.

diff_traces(trace_a, trace_b, stream)Side-by-side structural diff of two traces. Highlights added/removed/changed spans.

CLI Reference

spanforge debug commands.

Command	Arguments	Description
inspect	events.jsonl --event-id <id>	Pretty-print a single event by event_id.
stats	events.jsonl	Print event-type counts, trace count, and time range.
report	events.jsonl	Generate a static HTML trace report.
serve	events.jsonl [--port 8888]	Start a local HTTP trace viewer at /traces.
ui	events.jsonl	Open trace viewer in your browser.
audit-chain	events.jsonl [--key-file <k>]	Verify HMAC-SHA256 signing chain integrity.
scan	events.jsonl	Scan for PII using built-in regex detectors.
compliance	events.jsonl [--framework <f>]	Generate HMAC-signed compliance evidence packages.

Next steps

Confident events are compliant events.

Use SpanForge Validate to enforce schema compliance in CI, catch drift at build time, and verify HMAC chains before shipping.

SpanForge Validate →Back to the SDK →

← Python SDK SpanForge Validate →