Trace Every Decision. Debug Any Agent. Control All Costs.

English / 简体中文 / 日本語 / 한국어 / Español

Best Practices · Report Bug · Request Feature

---

Table of Contents

• 👋🏻 What is traceweave?
• 🚀 Key Features
• 🆚 Why traceweave?
• 🏁 Quick Start
• 🔌 Integrations
• 📊 Dashboards
• 📁 Examples
• 🏗️ Architecture
• 🤝 Contributing
• ⭐ Star History
• 📄 License

---

👋🏻 What is traceweave?

traceweave is the Datadog for AI Agents — an open-source distributed tracing and observability platform built specifically for multi-agent AI systems.

Add 2 lines of code to see exactly what your agents are doing: every LLM call, every tool invocation, every decision — with token counts, cost tracking, and beautiful visualizations.

📍 Trace: customer-support-pipeline  id=a3f2c1d8...
├── ✅ 🔗 customer-support-pipeline     ██████████████████████░░ 5.3s   tokens: 3.1k   cost: $0.05
│   ├── ✅ 🔧 email-reader              █░░░░░░░░░░░░░░░░░░░░░  0.2s   tokens: -      cost: -
│   ├── ✅ 🤖 triage-agent              ████░░░░░░░░░░░░░░░░░░  1.2s   tokens: 704    cost: $0.0004
│   │   ├── ✅ 🧠 classify-email        █░░░░░░░░░░░░░░░░░░░░░  0.2s   tokens: 704    cost: $0.0004
│   │   │        (claude-4-haiku)
│   │   ├── ❌ 🔧 sentiment-api         █░░░░░░░░░░░░░░░░░░░░░  0.4s   ⚠ TIMEOUT
│   │   └── ❌ 🔧 sentiment-api         █░░░░░░░░░░░░░░░░░░░░░  0.4s   ⚠ RETRY FAILED
│   ├── ✅ 🤖 research-agent            ███░░░░░░░░░░░░░░░░░░░  1.0s   tokens: 628    cost: $0.004
│   │   ├── ✅ 🔧 vector-search         █░░░░░░░░░░░░░░░░░░░░░  0.3s   (3 docs, top=0.94)
│   │   ├── ✅ 🔧 sql-query             █░░░░░░░░░░░░░░░░░░░░░  0.2s   (customer: enterprise)
│   │   └── ✅ 🧠 analyze-issue         ██░░░░░░░░░░░░░░░░░░░░  0.6s   tokens: 628    cost: $0.004
│   │            (claude-4-sonnet)
│   ├── ✅ 🤖 resolution-agent          ██░░░░░░░░░░░░░░░░░░░░  0.6s
│   │   ├── ✅ 🔧 rate-limit-override   █░░░░░░░░░░░░░░░░░░░░░  0.4s   (limit: 10K→20K)
│   │   ├── ✅ 🔧 ticket-update         █░░░░░░░░░░░░░░░░░░░░░  0.1s
│   │   └── ✅ 🔧 slack-notify          █░░░░░░░░░░░░░░░░░░░░░  0.1s   (#support-escalations)
│   └── ✅ 🤖 response-agent            ████████░░░░░░░░░░░░░░  2.3s   tokens: 1.7k   cost: $0.047
│       ├── ✅ 🧠 draft-response        ███░░░░░░░░░░░░░░░░░░░  0.9s   tokens: 861    cost: $0.04
│       │        (claude-4-opus)
│       ├── ✅ 🧠 review-response       ███░░░░░░░░░░░░░░░░░░░  1.0s   tokens: 868    cost: $0.007
│       │        (claude-4-sonnet)
│       ├── ✅ 🔧 send-email            █░░░░░░░░░░░░░░░░░░░░░  0.2s
│       └── ✅ 🔧 ticket-update         █░░░░░░░░░░░░░░░░░░░░░  0.2s   (status: resolved)
╰── Summary ───────────────────────────────────────────────────────────────
    ⏱  5.3s │ 🔢 19 spans │ 📊 3,061 tokens │ 💰 $0.047 │ ❌ 2 errors (handled)

💡 This trace was generated by our Showcase Demo — a full AI customer support pipeline with 4 agents, 10 tool calls, 5 LLM calls, error handling & retry. Zero API keys needed.

---

🚀 Key Features

1. 🎯 Zero-Config Instrumentation — Auto-trace OpenAI, Anthropic, LangChain with instrument_all(). No code changes at call sites.

2. 🤖 Elegant Decorator API — @trace_agent, @trace_tool, @trace_llm — trace any function with one line. Supports sync & async.

3. 💰 Token & Cost Tracking — Automatic token counting and cost estimation for all major models. See exactly where your budget goes.

4. 🖥️ Beautiful Visualizations — Stunning terminal dashboard (Rich TUI) + dark-themed web dashboard. Screenshot-worthy output.

5. ❌ Error Tracing & Debugging — Errors are captured with full stack traces. See exactly which agent/tool failed and why.

6. 📤 Export Anywhere — JSON, Chrome DevTools (chrome://tracing), and more. Integrate with your existing observability stack.

7. 🔗 Deep Nesting Support — Unlimited span nesting with automatic parent-child tracking via contextvars. No manual context passing.

8. ⚡ Lightweight & Fast — Pure Python, ~3K lines, zero heavy dependencies. Adds <1ms overhead per span.

---

🆚 Why traceweave?

Who is this for?

Target Users	Roles	Pain Points
AI Agent Developers	Building with LangChain, CrewAI, AutoGen, custom agents	Can't see what agents are doing; debugging is guesswork
LLM Application Teams	Production AI apps with multiple LLM calls	Token costs spiral out of control with no visibility
AI Platform Engineers	Operating multi-agent infrastructure at scale	No observability standard for AI — existing APM tools don't understand agents

Compared to alternatives

Capability	traceweave	LangSmith	Weights & Biases	OpenTelemetry
Open source	✅ MIT	❌ Proprietary	❌ Proprietary	✅ Apache-2.0
Agent-native spans	✅ AGENT, TOOL, LLM	✅	⚠️ Generic	❌ Generic
Zero-config instrumentation	✅ instrument_all()	⚠️ Requires SDK changes	❌ Manual	❌ Manual
Token & cost tracking	✅ Built-in	✅	⚠️ Partial	❌ No
Beautiful TUI	✅ Rich terminal UI	❌ Web only	❌ Web only	❌ No UI
Self-hosted / offline	✅ 100% local	❌ Cloud required	❌ Cloud required	✅ Self-hosted
Lightweight	✅ ~3K lines, pure Python	❌ Heavy SDK	❌ Heavy SDK	⚠️ Complex setup
Decorator API	✅ @trace_agent	❌	❌	❌

🎯 traceweave's sweet spot: You want LangSmith-level agent observability, but open-source, self-hosted, and without vendor lock-in.

---

🏁 Quick Start

1. Install

pip install traceweave

2. Instrument your code

from agent_trace import tracer, trace_agent, trace_tool
from agent_trace.dashboard.tui import print_trace

@trace_tool("web-search")
def search(query: str) -> list[str]:
    return ["result 1", "result 2"]

@trace_agent("researcher")
def research(topic: str) -> str:
    results = search(topic)
    return f"Found {len(results)} results about {topic}"

# Trace everything
with tracer.start_trace("my-task"):
    answer = research("AI agents")

# Visualize — beautiful terminal output!
print_trace(tracer.get_all_traces()[-1])

3. Or auto-instrument existing code (zero changes!)

from agent_trace.integrations import instrument_all
instrument_all()  # ← That's it! All OpenAI/Anthropic calls are now traced.

# Your existing code works unchanged
client = openai.OpenAI()
response = client.chat.completions.create(model="gpt-4", messages=[...])
# ^ This call is automatically traced with token counts & cost!

4. Explore dashboards

traceweave tui        # Terminal dashboard (live-updating)
traceweave dashboard  # Web dashboard at http://localhost:8420
traceweave demo       # Run the built-in demo

---

🔌 Integrations

Auto-instrument popular AI frameworks with a single function call:

Framework	Integration	Setup
OpenAI	instrument_openai()	pip install traceweave[openai]
Anthropic	instrument_anthropic()	pip install traceweave[anthropic]
LangChain	AgentTraceCallbackHandler	pip install traceweave[langchain]
All at once	instrument_all()	pip install traceweave[all]

OpenAI example

from agent_trace.integrations.openai_integration import instrument_openai
instrument_openai()

client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)
# Automatically traced: model, tokens, cost, latency, input/output

Anthropic example

from agent_trace.integrations.anthropic_integration import instrument_anthropic
instrument_anthropic()

client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-3-sonnet-20240229",
    messages=[{"role": "user", "content": "Hello!"}]
)

LangChain example

from agent_trace.integrations.langchain_integration import AgentTraceCallbackHandler

handler = AgentTraceCallbackHandler()
chain = prompt | llm | output_parser
chain.invoke({"input": "..."}, config={"callbacks": [handler]})

---

📊 Dashboards

Terminal Dashboard (TUI)

traceweave tui

Real-time, Rich-powered terminal dashboard with:

• 🌲 Interactive trace tree with color-coded span types
• 📊 Token usage waterfall bars
• 💰 Per-span cost breakdown
• ❌ Error highlighting with stack traces

Web Dashboard

traceweave dashboard  # → http://localhost:8420

Self-hosted, dark-themed web UI with:

• Interactive trace tree visualization
• Token usage analytics
• Cost breakdown per agent/tool
• Timeline waterfall view
• No external dependencies — single embedded HTML

Export to Chrome DevTools

from agent_trace.exporters import export_chrome
export_chrome(trace, "my-trace.chrome.json")
# Open chrome://tracing → Load → Interactive flame graph!

---

📁 Examples

Example	Description	Complexity
Simple Demo	Minimal trace in 10 lines	⭐
Multi-Agent Research	4-agent team with tools & LLM calls	⭐⭐
Showcase: AI Support Pipeline	Full production simulation: 4 agents, RAG, error handling, 3 models	⭐⭐⭐
DeepSeek Agent (Real API)	Real DeepSeek-powered agent with live tracing, TUI & web dashboard	⭐⭐⭐

# Run the showcase demo (no API keys needed!)
python examples/showcase_demo.py

# Run the real DeepSeek agent demo (requires API key)
python examples/deepseek_agent_demo.py --dashboard

---

🔑 Key Concepts

Concept	Description
Trace	A complete end-to-end operation. Contains a tree of spans.
Span	A single unit of work — an agent call, tool invocation, or LLM request.
SpanKind	Categorizes spans: AGENT 🤖, TOOL 🔧, LLM 🧠, CHAIN 🔗, RETRIEVER 📚
TokenUsage	Per-span token counts + cost estimation with model-specific pricing.
Decorator API	@trace_agent, @trace_tool, @trace_llm — one-line instrumentation.

---

🏗️ Architecture

traceweave/
├── agent_trace/
│   ├── core/               # Core tracing engine
│   │   ├── models.py       # Pydantic v2 data models (Span, Trace, TokenUsage)
│   │   ├── tracer.py       # AgentTracer — context management & event system
│   │   ├── span.py         # Span context manager with fluent API
│   │   ├── context.py      # Thread-safe context propagation (contextvars)
│   │   └── decorators.py   # @trace_agent, @trace_tool, @trace_llm
│   ├── integrations/       # Zero-config framework auto-instrumentation
│   │   ├── openai_integration.py
│   │   ├── anthropic_integration.py
│   │   └── langchain_integration.py
│   ├── dashboard/           # Visualization layer
│   │   ├── tui.py           # Rich terminal dashboard (TUI)
│   │   └── server.py        # Web dashboard (self-contained HTML)
│   ├── exporters/           # Export to JSON, Chrome Trace, etc.
│   └── cli.py               # CLI: traceweave tui|dashboard|demo|export
├── examples/                # Demo scripts (no API keys needed)
└── tests/                   # 39 tests, 100% passing

Technology	Purpose
Pydantic v2	Data models with validation & serialization
Rich	Beautiful terminal rendering (TUI dashboard)
Click	CLI framework
contextvars	Thread & async-safe trace propagation
orjson	Fast JSON serialization for exports

---

🤝 Contributing

Contributions welcome! Whether it's a bug report, feature request, or pull request — we appreciate it all.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing)
3. Run tests: pytest tests/ -v
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing)
6. Open a Pull Request

---

⭐ Star History

If you find traceweave useful, please give us a star! It helps others discover the project.

---

📄 License

MIT License — see LICENSE for details.

---

Built with ❤️ for the AI agent community