🔍 agent-trace

Lightweight OTLP-compatible tracer for AI agents. Instrument your agent with spans for LLM calls, tool invocations, and chain steps — zero dependencies, pure Python stdlib.

Complements agentlog (structured logging) and agentest (testing) — the agents trifecta: log → test → trace.

OpenTelemetry has won as the observability standard in 2026, but the official Python SDK pulls in protobuf, gRPC, and dozens of transitive deps. agent-trace gives you the OTLP data model (spans, trace IDs, attributes) in a single zero-dep library — perfect for lightweight agents, notebooks, and CI pipelines.

Features

• 🔍 Span-based tracing — LLM, tool, chain, and agent spans with OTLP-compatible IDs
• 🌲 Nested span trees — parent-child relationships, automatic trace_id inheritance
• 📤 Three exporters — Console (color-coded tree), File (JSONL), OTLP/JSON
• 🏷️ Standard attributes — llm.model, llm.tokens.*, tool.name, etc.
• 🎯 Shorthand methods — tracer.llm(), tracer.tool(), tracer.chain()
• 🎨 @trace decorator — automatic function instrumentation
• 🚫 Zero dependencies — pure stdlib, no protobuf, no gRPC
• 📊 CLI viewer — agent-trace view trace.jsonl

Quick Start

pip install agent-trace

Usage

Basic tracing

from agent_trace import Tracer, ConsoleExporter

tracer = Tracer(name="my-agent", exporter=ConsoleExporter())

with tracer.span("main", kind="agent") as root:
    root.set_attribute("agent.name", "research-bot")

    with tracer.llm("planning", model="gpt-4o", input_tokens=350) as plan:
        plan.set_attribute("llm.tokens.output", 120)
        # ... LLM call ...

    with tracer.tool("search", tool_name="web_search",
                     tool_args='{"query":"latest AI papers"}') as search:
        search.set_status("ok")

    with tracer.llm("synthesis", model="gpt-4o", input_tokens=800) as synth:
        synth.set_attribute("llm.tokens.output", 450)

tracer.flush()

Output:

○ agent main  (423.5ms)  agent.name=research-bot
  ├─ ○ llm planning  (210.2ms)  llm.model=gpt-4o, llm.tokens.input=350, llm.tokens.output=120
  ├─ ✓ tool search  (85.3ms)  tool.name=web_search
  └─ ○ llm synthesis  (128.0ms)  llm.model=gpt-4o, llm.tokens.input=800, llm.tokens.output=450

@trace decorator

from agent_trace import Tracer, trace

tracer = Tracer(name="app")

@trace(kind="llm", capture_args=True, tracer=tracer)
def call_llm(prompt: str, model: str = "gpt-4o") -> str:
    # ... your LLM call ...
    return response

result = call_llm("What is AI?", model="claude-sonnet-4-6")
tracer.flush()

Exporters

# JSONL file — for offline analysis
from agent_trace import FileExporter
tracer = Tracer(exporter=FileExporter("trace.jsonl"))

# OTLP JSON — pipe to Jaeger/Tempo/Langfuse
from agent_trace import OTLPJSONExporter
tracer = Tracer(exporter=OTLPJSONExporter())
# ... traces ...
tracer.flush()  # writes OTLP JSON to stdout

CLI

agent-trace view trace.jsonl     # Pretty-print trace tree
agent-trace stats trace.jsonl    # Show span counts, errors, token totals

Standard Attributes

Attribute	Kind	Description
llm.system	llm	Provider: openai, anthropic
llm.model	llm	Model ID: gpt-4o, claude-sonnet-4-6
llm.tokens.input	llm	Input token count
llm.tokens.output	llm	Output token count
tool.name	tool	Tool identifier
tool.args	tool	JSON-encoded arguments
agent.name	agent	Agent identifier
code.function	any	Function name (from @trace)

Development

git clone https://github.com/alvabillwu/agent-trace.git
cd agent-trace
pip install -e ".[dev]"
pytest -v

🔗 Ecosystem

Part of the alvabillwu AI/LLM DevTools suite:

• agentlog — Structured logging and replay for AI agent executions
• agentest — Lightweight test framework for AI agents
• log2trace — Convert agent logs into OTLP trace format
• agent2ci — Agent CI/CD integration harness

License

MIT © alvabillwu