traceboard 0.2.0

Local-first AI Agent observability & debugging toolkit. Supports OpenAI, Anthropic, LangChain, and LiteLLM.

English | 中文 | 日本語

TraceBoard

Local-first AI Agent observability & debugging toolkit.

TraceBoard is the SQLite of Agent tracing — zero config, fully local, instant setup. No cloud accounts, no Docker, no external databases. Just pip install and go.

---

Features

• Multi-SDK — Supports OpenAI Agents SDK, Anthropic, LangChain, and LiteLLM
• Zero Config — pip install traceboard[all] + 2 lines of code
• Local First — All data stored in a local SQLite file, zero privacy risk
• Built-in Web Dashboard — traceboard ui opens an interactive trace viewer
• Cost Tracking — Automatic per-model cost calculation for 6 providers, 100+ models
• Live Updates — WebSocket-powered real-time view with HTTP polling fallback
• Data Export — Export traces to JSON or CSV for offline analysis
• Offline — Works without any internet connection

Quick Start

Install

pip install traceboard[all]    # All SDK adapters
pip install traceboard[openai] # OpenAI Agents SDK only
pip install traceboard[anthropic] # Anthropic only
pip install traceboard[langchain] # LangChain only
pip install traceboard[litellm]   # LiteLLM only (supports 100+ providers)

OpenAI Agents SDK

import traceboard
traceboard.init()

from agents import Agent, Runner

agent = Agent(name="Assistant", instructions="You are a helpful assistant.")
result = Runner.run_sync(agent, "Hello!")
print(result.final_output)

Anthropic Claude

import traceboard
tracer = traceboard.init_anthropic()
client = tracer.instrument()  # Returns an instrumented Anthropic client

response = client.messages.create(
    model="claude-opus-4.6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}]
)

LangChain

import traceboard
handler = traceboard.init_langchain()

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(model="gpt-5", callbacks=[handler])
response = llm.invoke("Hello!")

LiteLLM (100+ providers in one)

import traceboard
traceboard.init()  # Auto-detects LiteLLM

from litellm import completion

# Works with any provider — OpenAI, Anthropic, Gemini, DeepSeek, etc.
response = completion(model="gpt-5", messages=[{"role": "user", "content": "Hello!"}])

Auto-detect all installed SDKs

import traceboard
traceboard.init()  # Automatically instruments every SDK it finds

View Traces

traceboard ui

This opens a local web dashboard at http://localhost:8745 where you can:

• Browse all traced agent runs
• Visualize execution timelines (Gantt-chart style)
• Inspect LLM prompts/responses, tool calls, and handoffs
• Track token usage and costs per model
• View aggregated metrics in real-time

How It Works

┌────────────────────┐       ┌───────────────┐       ┌──────────────────┐
│  Your Agent Code   │       │   SQLite DB   │       │  Web Dashboard   │
│                    │       │               │       │                  │
│  traceboard.init() │──────>│ traceboard.db │<──────│  traceboard ui   │
│  Agent.run(...)    │ write │               │  read │  localhost:8745  │
└────────────────────┘       └───────────────┘       └──────────────────┘

TraceBoard implements the OpenAI Agents SDK's TracingProcessor interface. When you call traceboard.init(), it registers a custom processor that captures all traces and spans (LLM calls, tool calls, handoffs, guardrails) and writes them to a local SQLite database.

The web dashboard reads from this same SQLite file and presents the data through an interactive UI. When a WebSocket connection is available, the dashboard receives near-real-time updates (~1 s latency); otherwise it falls back to HTTP polling.

CLI Commands

traceboard ui                        # Start web dashboard (default: http://localhost:8745)
traceboard ui --port 9000            # Custom port
traceboard ui --no-open              # Don't auto-open browser

traceboard export                    # Export all traces to JSON (stdout)
traceboard export -o traces.json     # Export to file
traceboard export -f csv -o data.csv # Export to CSV (traces + spans files)
traceboard export --pretty           # Pretty-print JSON

traceboard clean                     # Delete all trace data

Configuration

import traceboard

traceboard.init(
    db_path="./my_traces.db",   # Custom database path (default: ./traceboard.db)
    auto_open=False,             # Don't auto-open browser on init
)

Programmatic Export

from traceboard import TraceExporter

exporter = TraceExporter("./traceboard.db")

# Export all traces to JSON file
data = exporter.export_json("traces.json")

# Export specific traces to CSV
exporter.export_csv("output.csv", trace_ids=["trace_abc123"])

# Get data in memory (no file written)
data = exporter.export_json()
print(f"Exported {data['trace_count']} traces")

Supported Models (Cost Tracking)

TraceBoard supports cost tracking for 6 providers, 100+ model variants:

Provider	Models
OpenAI	gpt-5.2, gpt-5.1, gpt-5, gpt-5-mini, gpt-5-nano, gpt-4.1, gpt-4o, o1, o3, o4-mini, and more
Anthropic	claude-opus-4.6, claude-opus-4.5, claude-sonnet-4.5, claude-haiku-4.5, claude-opus-4, claude-sonnet-4, claude-3.5-sonnet
Google	gemini-3-pro-preview, gemini-3-flash-preview, gemini-2.5-pro, gemini-2.5-flash, gemini-2.0-flash
DeepSeek	deepseek-chat, deepseek-reasoner
Meta	llama-4-maverick, llama-4-scout, llama-3.3-70b, llama-3.1-405b
Mistral	mistral-large-latest, mistral-medium-latest, mistral-small-latest, codestral-latest

Unknown models fall back to default pricing ($2.00/$8.00 per 1M tokens). Pricing data is sourced from each provider's official pricing page and updated with each release.

Architecture

traceboard/
├── __init__.py              # Public API: init(), init_anthropic(), init_langchain(), etc.
├── cli.py                   # CLI commands (ui, clean, export)
├── config.py                # Configuration dataclass
├── cost.py                  # Model pricing & cost calculation (6 providers)
├── sdk/
│   ├── _base.py             # BaseTracer — shared trace/span write logic
│   ├── processor.py         # OpenAI Agents SDK adapter
│   ├── anthropic_tracer.py  # Anthropic SDK adapter (httpx hooks)
│   ├── langchain_handler.py # LangChain adapter (BaseCallbackHandler)
│   ├── litellm_logger.py    # LiteLLM adapter (CustomLogger)
│   └── exporter.py          # JSON & CSV export utilities
├── server/
│   ├── app.py               # FastAPI application factory
│   ├── database.py          # Async + sync SQLite wrappers
│   ├── models.py            # Pydantic data models
│   └── routes/
│       ├── traces.py        # Trace CRUD endpoints
│       ├── spans.py         # Span query endpoints
│       └── metrics.py       # Metrics + WebSocket live updates
└── dashboard/
    ├── index.html           # Single-page dashboard (Alpine.js + Tailwind)
    └── static/
        ├── app.js           # Dashboard application logic
        └── styles.css       # Custom styles

REST API

When the dashboard is running (traceboard ui), the following API endpoints are available:

Method	Endpoint	Description
GET	/api/traces	List traces (paginated, filterable)
GET	/api/traces/{id}	Get trace detail with all spans
GET	/api/traces/{id}/spans	Get flat span list for a trace
GET	/api/traces/{id}/tree	Get span tree for timeline view
GET	/api/traces/{id}/export	Export a single trace
DELETE	/api/traces	Delete all traces
GET	/api/metrics	Aggregated metrics
GET	/api/export	Export all data as JSON
WS	/api/ws/live	WebSocket for live metric updates

Development

# Clone and install in dev mode
git clone https://github.com/123zcr/traceboard.git
cd traceboard
pip install -e ".[dev]"

# Run tests
pytest

# Start dashboard in dev mode
traceboard ui --no-open

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes and add tests
4. Run pytest to ensure all tests pass
5. Submit a pull request

Requirements

• Python >= 3.10
• At least one supported SDK: openai-agents, anthropic, langchain-core, or litellm

License

MIT