traceweave 0.1.2

Distributed tracing and observability for AI agents. Datadog for AI Agents.

🔍 traceweave

Distributed Tracing & Observability for AI Agents

See exactly what your AI agents are doing. Debug multi-agent systems like a pro.

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

Quick Start · Features · Integrations · Dashboard · Examples

---

Think of it as Datadog for AI Agents. Trace every agent decision, tool call, and LLM interaction with beautiful visualizations and zero-config instrumentation.

📍 Trace: multi-agent-research  id=a3f2c1d8...
├── ✅ 🔗 multi-agent-research           ██████████████████████░░ 12.3s   tokens: 8.2k   cost: $0.15
│   ├── ✅ 🤖 planner                    ████████░░░░░░░░░░░░░░  3.2s    tokens: 2.1k   cost: $0.04
│   │   └── ✅ 🧠 plan-generation        ██████░░░░░░░░░░░░░░░░  2.1s    tokens: 1.8k   cost: $0.03
│   ├── ✅ 🤖 researcher                 ████████████░░░░░░░░░░  5.1s    tokens: 3.4k   cost: $0.06
│   │   ├── ✅ 🔧 web-search             ██░░░░░░░░░░░░░░░░░░░░  0.6s    tokens: -      cost: -
│   │   ├── ✅ 🔧 arxiv-search           █░░░░░░░░░░░░░░░░░░░░░  0.3s    tokens: -      cost: -
│   │   └── ✅ 🧠 analyze-results        ████████░░░░░░░░░░░░░░  3.1s    tokens: 2.8k   cost: $0.05
│   ├── ✅ 🤖 writer                     ██████████░░░░░░░░░░░░  4.8s    tokens: 1.9k   cost: $0.04
│   │   └── ✅ 🧠 write-report           ██████████░░░░░░░░░░░░  4.2s    tokens: 1.9k   cost: $0.04
│   └── ✅ 🤖 reviewer                   ██████░░░░░░░░░░░░░░░░  2.4s    tokens: 0.8k   cost: $0.01
│       └── ✅ 🧠 review-report          ██████░░░░░░░░░░░░░░░░  2.1s    tokens: 0.8k   cost: $0.01
╰── Summary ─────────────────────────────────────────────────────
    ⏱  Duration: 12.3s │ 🔢 Spans: 11 │ 📊 Tokens: 8.2k │ 💰 Cost: $0.15

Why traceweave?

Building with AI agents? You've probably experienced:

• 🤯 "Why did my agent do that?" — No visibility into agent reasoning chains
• 💸 "Where are my tokens going?" — Can't track costs across nested agent calls
• 🐛 "Which step failed?" — Debugging multi-agent pipelines is a nightmare
• 📊 "How long does each step take?" — No performance profiling for agents

traceweave solves all of this with 2 lines of code.

🚀 Quick Start

pip install traceweave

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

@trace_tool("calculator")
def add(a: int, b: int) -> int:
    return a + b

@trace_agent("math-agent")
def math_agent(question: str) -> int:
    return add(2, 3)

# Trace everything
with tracer.start_trace("math-task"):
    answer = math_agent("What is 2 + 3?")

# Visualize
print_trace(tracer.get_all_traces()[-1])

✨ Features

🎯 Zero-Config Auto-Instrumentation

Automatically trace OpenAI, Anthropic, and LangChain with a single line:

from agent_trace.integrations import instrument_all
instrument_all()  # That's it! All LLM calls are now traced.

🤖 Elegant Decorators

@trace_agent("researcher")    # Trace agent functions
@trace_tool("web-search")     # Trace tool calls
@trace_llm(model="gpt-4")     # Trace LLM calls with token tracking

📊 Token & Cost Tracking

Automatic token counting and cost estimation for all major models:

with tracer.start_span("my-llm-call", SpanKind.LLM) as span:
    response = call_llm(prompt)
    span.set_token_usage(
        prompt_tokens=1500,
        completion_tokens=500,
        model="claude-3-sonnet",
        prompt_cost_per_1k=0.003,
        completion_cost_per_1k=0.015,
    )

🖥️ Beautiful Terminal Dashboard

traceweave tui  # Live-updating terminal dashboard

🌐 Web Dashboard

traceweave dashboard  # Opens at http://localhost:8420

Dark-themed, real-time web dashboard with:

• Interactive trace tree visualization
• Token usage analytics
• Cost breakdown per agent/tool
• Timeline waterfall view

📤 Export Anywhere

from agent_trace.exporters import export_json, export_chrome

# Save as JSON
export_json(trace, "my-trace.json")

# Export to Chrome DevTools format (open in chrome://tracing)
export_chrome(trace, "my-trace.chrome.json")

🔌 Integrations

OpenAI

from agent_trace.integrations.openai_integration import instrument_openai
instrument_openai()

# All OpenAI calls are now traced automatically!
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}]
)

Anthropic

from agent_trace.integrations.anthropic_integration import instrument_anthropic
instrument_anthropic()

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

LangChain

from agent_trace.integrations.langchain_integration import AgentTraceCallbackHandler

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

📁 Examples

Example	Description
Simple Demo	Minimal example — trace in 10 lines
Multi-Agent Research	4-agent team with tools, LLM calls, and cost tracking

Run the built-in demo:

traceweave demo

🏗️ Architecture

traceweave/
├── agent_trace/
│   ├── core/           # Core tracing engine
│   │   ├── models.py   # Pydantic data models (Span, Trace, TokenUsage)
│   │   ├── tracer.py   # Main tracer with context management
│   │   ├── span.py     # Span context manager
│   │   ├── context.py  # Thread-safe context propagation
│   │   └── decorators.py # @trace_agent, @trace_tool, @trace_llm
│   ├── integrations/   # Framework auto-instrumentation
│   │   ├── openai_integration.py
│   │   ├── anthropic_integration.py
│   │   └── langchain_integration.py
│   ├── dashboard/      # Visualization
│   │   ├── tui.py      # Rich terminal dashboard
│   │   └── server.py   # Web dashboard (single HTML, no build step)
│   ├── exporters/      # Export formats
│   │   ├── json_exporter.py
│   │   └── chrome_exporter.py
│   └── cli.py          # CLI commands
└── examples/           # Demo scripts

🔑 Key Concepts

Concept	Description
Trace	A complete operation (e.g., "research task"). Contains a tree of spans.
Span	A single unit of work (agent call, tool use, LLM request).
SpanKind	Type of span: AGENT, TOOL, LLM, CHAIN, RETRIEVER
TokenUsage	Token counts + cost estimation per LLM call

📦 Installation

# Core only
pip install traceweave

# With specific integrations
pip install traceweave[openai]
pip install traceweave[anthropic]
pip install traceweave[langchain]

# Everything
pip install traceweave[all]

Requirements: Python 3.9+

🤝 Contributing

Contributions welcome! Please feel free to submit a Pull Request.

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

📄 License

MIT License — see LICENSE for details.

---

Built with ❤️ for the AI agent community

If you find traceweave useful, please ⭐ star the repo!