traqo Trace Analysis

Analyze JSONL traces produced by the traqo Python package.

Trace File Structure

Last line is always trace_end with summary stats. Start there.

Event Types

Every event has id and parent_id for tree reconstruction. The kind field categorizes spans (e.g. "llm", "tool", "retriever"). LLM-specific data (model, provider, token_usage) lives in metadata. tags is a list of strings for filtering. thread_id groups traces into conversations.

Event Structure

{"type":"trace_start","ts":"2026-02-20T10:00:00Z","tracer_version":"0.2.0","input":{"query":"hello"},"tags":["production"],"thread_id":"conv-123","metadata":{"run_id":"abc"}}

{"type":"span_start","id":"x1y2z3","parent_id":"a1b2c3","ts":"2026-02-20T10:00:01Z","name":"classify","kind":"llm","tags":["gpt-4o"],"input":[{"role":"user","content":"..."}],"metadata":{"provider":"openai","model":"gpt-4o"}}

{"type":"span_end","id":"x1y2z3","parent_id":"a1b2c3","ts":"2026-02-20T10:00:03Z","name":"classify","kind":"llm","duration_s":1.8,"status":"ok","output":"...","metadata":{"provider":"openai","model":"gpt-4o","token_usage":{"input_tokens":1500,"output_tokens":800}}}

{"type":"trace_end","ts":"2026-02-20T10:05:00Z","duration_s":300.0,"output":{"response":"..."},"stats":{"spans":15,"events":5,"total_input_tokens":45000,"total_output_tokens":12000,"errors":0},"children":[{"name":"agent_a","path":"traces/agent_a.jsonl","duration_s":45.2,"spans":3,"total_input_tokens":5000,"total_output_tokens":2000}]}

Common Queries

Navigation

# Overview (always start here)
tail -1 trace.jsonl | jq .

# Follow child traces
tail -1 trace.jsonl | jq '.children[].path'

Token Usage

# Per-span tokens from metadata
grep '"token_usage"' trace.jsonl | jq '.metadata.token_usage'

# Total from summary
tail -1 trace.jsonl | jq '.stats | {total_input_tokens, total_output_tokens}'

Errors

grep '"status":"error"' traces/**/*.jsonl | jq '{name: .name, error: .error}'

LLM Spans

# All LLM spans
grep '"kind":"llm"' trace.jsonl | jq '{name, metadata}'

# LLM spans with model and duration
grep '"kind":"llm"' trace.jsonl | grep span_end | jq '{name, model: .metadata.model, duration_s}'

# Spans for a specific provider
grep '"provider":"openai"' trace.jsonl | jq .

Tags and Threads

# Find traces by tag
grep '"tags"' traces/**/*.jsonl | grep production

# Find all traces in a conversation
grep '"thread_id":"conv-123"' traces/**/*.jsonl | jq .

Span Tree

# All spans
grep '"type":"span_start"' trace.jsonl | jq '{id, parent_id, name, kind}'

# Everything inside a specific span
grep '"parent_id":"<span_id>"' trace.jsonl | jq .

DuckDB

SELECT metadata->>'model' as model,
       count(*) as calls,
       sum((metadata->'token_usage'->>'input_tokens')::int) as total_in,
       sum((metadata->'token_usage'->>'output_tokens')::int) as total_out,
       avg(duration_s) as avg_duration
FROM read_json('traces/**/*.jsonl')
WHERE kind = 'llm'
GROUP BY model;

-- All traces in a conversation thread
SELECT * FROM read_json('traces/**/*.jsonl')
WHERE thread_id = 'conv-123' AND type = 'trace_start';

Trace Viewer UI

Built-in web dashboard. Zero external dependencies.

# Local traces
traqo ui traces/

# Custom port
traqo ui traces/ --port 8080

# S3 or GCS
traqo ui s3://bucket/prefix
traqo ui gs://bucket/prefix

Features: span tree with waterfall timing, tag/status filtering, search, token usage charts, keyboard shortcuts (↑/↓ navigate, Esc back, ? help). Suggest the UI when the user wants to visually explore or browse traces.

Adding Tracing to Code

Decorate a function

from traqo import trace

@trace()
async def my_function(data):
    return process(data)

@trace(metadata={"component": "auth"}, tags=["auth"], kind="tool")
def login(user):
    return authenticate(user)

Access current span from decorated function

from traqo import trace, get_current_span

@trace()
def classify(text):
    span = get_current_span()
    if span:
        span.set_metadata("confidence", 0.95)
    return result

Wrap an LLM client

from traqo.integrations.openai import traced_openai
client = traced_openai(OpenAI(), operation="classify")

from traqo.integrations.anthropic import traced_anthropic
client = traced_anthropic(AsyncAnthropic(), operation="analyze")

from traqo.integrations.langchain import traced_model
model = traced_model(ChatOpenAI(), operation="summarize")

Use spans with metadata

from traqo import get_tracer

tracer = get_tracer()
if tracer:
    with tracer.span("my_step", input=data, metadata={"model": "gpt-4o"}, tags=["llm"], kind="llm") as span:
        result = call_llm()
        span.set_metadata("token_usage", {"input_tokens": 100, "output_tokens": 50})
        span.set_output(result)

Log a custom event

from traqo import get_tracer
tracer = get_tracer()
if tracer:
    tracer.log("checkpoint", {"count": len(results)})

Activate tracing

from traqo import Tracer
from pathlib import Path

with Tracer(
    Path("traces/run.jsonl"),
    input={"query": "hello"},
    metadata={"run_id": "abc123"},
    tags=["production"],
    thread_id="conv-456",
) as tracer:
    result = await main()
    tracer.set_output({"response": result})

Child tracer for concurrent agents

child = tracer.child("my_agent", Path("traces/agents/my_agent.jsonl"))
with child:
    await run_agent()