🔍 Episodic Trace Logger

When your agent fails, you need to know why. Most solutions are cloud-based and heavyweight. This one lives on your disk.

The Problem

Agent debugging usually means reading logs and guessing. There’s no lightweight, local-first way to capture exactly what your agent did — tool calls, LLM queries, reasoning steps, costs — and replay it afterward.

Enterprise deployments also need compliance: who accessed what, when, with PII scrubbed.

The Solution

Episodic Trace Logger captures every step of agent execution into SQLite. No cloud. No lock-in. Zero dependencies.

Captures:

• Every tool call (name, args, output, latency, cost)
• Every LLM call (model, prompt, response, tokens)
• Reasoning annotations
• Error details and stack types
• Full timing and cost attribution

Built-in features:

• 🔒 PII redaction (10 patterns: email, phone, SSN, credit card, IP, JWT, AWS key, Bearer token…)
• 📤 Compliance exports (JSON, CSV, NDJSON)
• 📊 Analytics: cost by user/tool/model, slow traces, error summary
• 🎬 Replay viewer: step-by-step CLI playback
• 🗑️ Retention policies: auto-prune old data

Usage

from trace_logger import TraceLogger

logger = TraceLogger("traces.db", agent_name="my-agent")

with logger.trace(task="answer question", user_id="alice") as trace:
    with trace.tool_call("web_search", {"query": "cats"}) as step:
        results = search("cats")
        step.set_output(results, tokens_input=10)

    with trace.llm_call("claude-sonnet-4-5", prompt="Summarize:") as step:
        answer = llm(results)
        step.set_response(answer, tokens_input=200, tokens_output=100, cost_usd=0.002)

    trace.complete(output=answer)

trace-log inspect <trace-id>   # Step-by-step detail
trace-log replay <trace-id>    # Execution replay
trace-log stats --days 30      # Cost summary
trace-log tools                # Tool usage breakdown

Status

✅ Complete — 102/102 tests passing

No external dependencies. Python 3.9+. MIT License.