tracecraft 0.2.1

Vendor-neutral LLM observability — instrument once, observe anywhere.

TraceCraft is a Python observability SDK with a built-in Terminal UI (TUI) that lets you visually explore, debug, and analyze agent traces right in your terminal — no browser, no cloud dashboard, no waiting.

The fastest path: zero code changes

If your app already uses OpenAI, Anthropic, LangChain, LlamaIndex, or any OpenTelemetry-compatible framework, TraceCraft can observe it without touching a single line of application code.

Step 1 — Install and set one environment variable:

pip install "tracecraft[receiver,tui]"

export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318

Step 2 — Start the receiver and TUI together:

tracecraft serve --tui

Step 3 — Run your existing app unchanged:

python your_app.py

Traces from any OTLP-compatible framework (OpenLLMetry, LangChain, LlamaIndex, DSPy, or any standard OpenTelemetry SDK) stream live into the TUI the moment they arrive. No init() call. No decorators. No code changes.

All your agent runs at a glance — name, duration, token usage, and status.

Hierarchical waterfall view with timing bars. See exactly where your agent spends its time. Navigate to any LLM step and press i for the prompt, o for the response, or a for attributes.

Path 2 — Config file + one line

When you want a persistent local setup — custom service name, JSONL export, PII redaction — drop a config file into your project and add one line to your app:

.tracecraft/config.yaml:

# .tracecraft/config.yaml
default:
  exporters:
    receiver: true         # stream to tracecraft serve --tui
  instrumentation:
    auto_instrument: true  # patches OpenAI, Anthropic, LangChain, LlamaIndex

Your app:

import tracecraft

tracecraft.init()  # reads .tracecraft/config.yaml automatically

Then start the TUI:

tracecraft serve --tui

Or, if you prefer to write traces to a file and open the TUI separately:

tracecraft tui

Note: Call tracecraft.init() before importing any LLM SDK. TraceCraft patches SDKs at import time — importing first means the patch won't apply.

SDK decorators

For fine-grained control — custom span names, explicit inputs/outputs, structured step hierarchies — TraceCraft provides @trace_agent, @trace_tool, @trace_llm, and @trace_retrieval decorators, plus a step() context manager for inline instrumentation. See the SDK Guide for details.

TUI Keyboard Shortcuts

Why TraceCraft?

Features

• Built-in Terminal UI: Explore, filter, compare, and debug traces without leaving your terminal
• Local-First: All traces stay on your machine — the TUI is fully offline
• Zero-Code OTLP Receiver: Set one env var, run tracecraft serve --tui, observe any OTLP app
• Auto-Instrumentation: Two lines capture all OpenAI, Anthropic, LangChain, and LlamaIndex calls automatically
• Decorators: @trace_agent, @trace_tool, @trace_llm, @trace_retrieval for custom tracing
• Dual-Dialect Schema: OTel GenAI and OpenInference conventions
• PII Redaction: Client-side redaction before data ever leaves your app
• Export Anywhere: Console, JSONL, SQLite, OTLP, MLflow, HTML reports

Installation

# OTLP receiver + TUI (zero code changes path)
pip install "tracecraft[receiver,tui]"

# TUI + auto-instrumentation
pip install "tracecraft[auto,tui]"

# With specific frameworks
pip install "tracecraft[langchain,tui]"
pip install "tracecraft[llamaindex,tui]"

# All features
pip install "tracecraft[all]"

Or with uv:

uv add "tracecraft[auto,tui]"

Framework Support

Configuration

import tracecraft

tracecraft.init(
    service_name="my-agent-service",
    jsonl=True,              # Enable JSONL output for the TUI
    console=True,            # Pretty-print to console
    auto_instrument=True,    # Auto-capture OpenAI/Anthropic calls
    enable_pii_redaction=True,
    sampling_rate=1.0,
)

Environment variables:

export TRACECRAFT_SERVICE_NAME=my-service
export TRACECRAFT_ENVIRONMENT=production
export TRACECRAFT_SAMPLING_RATE=0.1
export TRACECRAFT_OTLP_ENDPOINT=http://localhost:4317

Export to Any Backend

from tracecraft.exporters import OTLPExporter

tracecraft.init(
    jsonl=True,  # Keep local TUI access
    exporters=[
        OTLPExporter(endpoint="http://localhost:4317"),  # Jaeger, Grafana, etc.
    ],
)

Supported backends: Langfuse, Datadog, Phoenix (Arize), Jaeger, Grafana Tempo, Honeycomb, any OTLP system.

Documentation

• Full Documentation
• Terminal UI Guide
• API Reference
• Migration Guides
• Deployment Guides

Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

Development Setup

git clone https://github.com/LocalAI/tracecraft.git
cd tracecraft
uv sync --all-extras
uv run pre-commit install
uv run pytest

Security

See SECURITY.md for security concerns.

License

Apache-2.0 — See LICENSE for details.

Made with care by the TraceCraft Contributors