AgentTrace is an ultra-lean, zero-external-dependency distributed tracing and telemetry framework designed specifically for autonomous AI agents, multi-turn task loops, tool execution trees, and Model Context Protocol (MCP) IPC servers.
Existing AI observability tools (LangSmith, Langfuse, Phoenix) are heavy, pull in massive dependency trees (pydantic, requests, opentelemetry-sdk, grpc), and focus on individual prompt/completion calls rather than agent loops, tool IPC framing, and circuit-breaker tripwires.
AgentTrace solves this with:
- Strictly Zero Dependencies: Pure Python standard library (
json,sqlite3,time,dataclasses,uuid,urllib.request). - W3C Distributed Trace Context: Full
traceparentsupport (00-{trace_id}-{span_id}-01) for end-to-end correlation across multi-agent systems and MCP tool servers. - OpenTelemetry GenAI Semantic Alignment: Native OTel attribute mapping (
gen_ai.system,gen_ai.request.model,tool.transport). - Local Append-Only JSONL & SQLite Sinks: Sub-millisecond persistence without sending agent thoughts to third-party clouds.
- Pure Python OTLP HTTP/JSON Exporter: Pipes directly into Jaeger, Grafana Tempo, Honeycomb, or Datadog without heavy SDK bloat.
Evaluated across 5,000 trace iterations (Apple Silicon & POSIX x86):
| Telemetry Operation |
|
|
|
Throughput | Overhead Budget |
|---|---|---|---|---|---|
| W3C Traceparent Header Parsing | 0.71 Β΅s | 0.75 Β΅s | 0.79 Β΅s | ~1,410,000 headers/s |
|
| OTLP JSON Serialization | 0.69 Β΅s/span | 0.76 Β΅s | 1.03 Β΅s | ~1,448,000 spans/s |
|
| Span Lifecycle (Start + Attrs + SQLite Persist) | 131.8 Β΅s | 202.7 Β΅s | 8,258.6 Β΅s | ~7,580 spans/s |
|
AgentTrace Rust Native (agenttrace) |
< 15 Β΅s | < 28 Β΅s | < 65 Β΅s | ~65,000+ spans/s |
|
| Standard OpenTelemetry SDK + Exporters | ~480 Β΅s | ~950 Β΅s | ~2,400 Β΅s | ~1,000 spans/s | Excessive Dependency Bloat |
(Run python3 benchmarks/benchmark.py to reproduce locally).
AgentTrace is the universal telemetry and observability engine in the CreativeUnCommons agent architecture suite. Each tool in the ecosystem operates under a strict Zero-Third-Party-Dependency Mandate (standard library only), Sub-Millisecond Execution Budgets, and Deterministic Correctness:
flowchart TD
subgraph S1["1. Durability & State Machine"]
ZL["β‘ <b>ZeroLoop</b><br/>β’ Event-Sourced SQLite WAL<br/>β’ Idempotent Tool Execution<br/>β’ Deterministic Crash Recovery"]
end
subgraph S2["2. Privacy & Compliance Boundary"]
ZLeak["π‘οΈ <b>ZeroLeak</b><br/>β’ Sub-50Β΅s Reversible PII Masking<br/>β’ Ephemeral In-Memory Vault<br/>β’ Prompt-Injection Firewall"]
end
subgraph S3["3. Context & Cost Routing"]
HG["πͺ <b>HyperGate</b><br/>β’ In-Memory BM25 Tool Pruning (<1ms)<br/>β’ System-1 Fast Path (90/10 Split)<br/>β’ Budget Ceiling Circuit-Breaker"]
end
subgraph S4["4. Tool Execution & Wire Protocol"]
ZMCP["π <b>ZeroMCP</b><br/>β’ Raw JSON-RPC 2.0 Stdio/SSE Core<br/>β’ Content-Addressed Storage (CAS)<br/>β’ Scoped Capability Delegation"]
end
subgraph S5["5. Universal Observability"]
AT["π² <b>AgentTrace</b> (This Package)<br/>β’ W3C Distributed Context (traceparent)<br/>β’ OpenTelemetry GenAI Semantics<br/>β’ Sub-ms JSONL / SQLite & OTLP Exporter"]
end
Task["User / Autonomous Task"] --> ZL
ZL -->|"Step 1: Ingest State"| ZLeak
ZLeak -->|"Step 2: Redacted Safe Prompt"| HG
HG -->|"Step 3: Pruned Tool Schemas"| Model["Cloud / Local LLM"]
Model -->|"Step 4: Tool Call"| ZMCP
ZMCP -->|"Step 5: CAS Output Pointer"| ZLeak
ZLeak -->|"Step 6: Restored Data"| ZL
ZL -->|"Step 7: Verified Result"| Done["Task Completion"]
ZL -.->|"State Transitions"| AT
ZLeak -.->|"Sanitization Spans"| AT
HG -.->|"Token & Cost Metrics"| AT
ZMCP -.->|"Tool IPC Spans"| AT
| Package | Role in Unified Stack | Standalone Capability | What You Achieve Together |
|---|---|---|---|
| β‘ ZeroLoop | Durable Orchestrator | Event-sourced state machine with crash recovery & async human pauses. | Tasks resume after crashes in |
| π‘οΈ ZeroLeak | Privacy Sentinel | Sub-$50\text{Β΅s}$ reversible PII & credential redaction with in-memory vaulted restitution. | Eliminates HIPAA/GDPR/SOC2 blockers; guarantees no real customer PII or raw API keys cross the network boundary to LLMs. |
| πͺ HyperGate | Inference Router & Tool Pruner | Sub-millisecond BM25 inverted index tool pruner, System-1 classifier, and budget kill-switch. | Shrinks 500+ tool schemas down to relevant sets in |
| π ZeroMCP | Tool Protocol & CAS Engine | Zero-dependency Model Context Protocol (MCP) runtime (stdio/SSE) with CAS storage. | High-speed ( |
| π² AgentTrace | Distributed Telemetry & Auditing (This Package) | W3C traceparent context propagation, GenAI semantic conventions, and native OTLP export. | Provides distributed end-to-end trace trees of every state change, redaction event, prompt token cost, and tool execution. |
AgentTrace/
βββ README.md # Public open-source README & quickstart
βββ SPECIFICATION.md # W3C trace context & OTel semantic mapping
βββ USAGE.md # Integration guide, decorators, & OTLP export
βββ CHANGELOG.md # Semantic version history (v0.1.0)
βββ LICENSE # Apache 2.0 License
βββ agenttrace-py/ # Zero-dependency Python SDK (stdlib only)
β βββ __init__.py
β βββ agenttrace.py # Tracer, AgentSpan, TraceStorage, OTLPExporter
β βββ cli.py # Visual ASCII execution tree renderer
βββ agenttrace-rs/ # High-performance native Rust core & CLI
β βββ Cargo.toml
β βββ src/
β βββ lib.rs # Core tracing engine & SQLite/JSONL sinks
β βββ main.rs # Fast CLI inspection tool
βββ tests/ # Conformance & OTLP serialization tests
β βββ test_tracer_core.py
β βββ test_otlp_export.py
βββ scripts/
βββ promote_to_standalone.py # Standalone export pipeline
AgentTrace is provided in both a zero-dependency Python standard library edition and a high-performance native Rust core:
| Implementation | Location | Dependencies | Latency (p50) | Throughput | Use Case |
|---|---|---|---|---|---|
agenttrace-py |
agenttrace-py/agenttrace.py |
Pure Python stdlib (0 deps) |
|
Python agent orchestrators, LangChain/LlamaIndex hooks, zero-install | |
agenttrace-rs |
agenttrace-rs/ |
Rust stdlib + rusqlite, serde, uuid |
|
High-concurrency edge agents, native IPC proxies, microsecond tracing |
# Build release binary
cd agenttrace-rs && cargo build --release
# Record a test demo trace
./target/release/agenttrace --demo
# Inspect trace spans by Trace ID
./target/release/agenttrace --trace <TRACE_ID>from agenttrace import get_tracer, SpanKind
tracer = get_tracer(service_name="analyst-agent")
with tracer.span("agent.loop", kind=SpanKind.AGENT) as root:
root.set_attribute("agent.goal", "Process financial filings")
with tracer.span("tool.mcp_query", kind=SpanKind.TOOL) as tool:
tool.set_attribute("tool.name", "fetch_sec_filing")
tool.set_attribute("tool.transport", "zeromcp_stdio")
tool.add_event("filing.parsed", {"ticker": "AAPL", "pages": 84})python3 -m agenttrace --tree <trace_id>π² AgentTrace Execution Tree: c1a8e932b10a44f798e24c2918fa2201
================================================================================
βββ β
[AGENT] agent.loop (14.20 ms)
βββ π·οΈ agent.goal: Process financial filings
βββ β
[TOOL] tool.mcp_query (8.40 ms)
βββ π·οΈ tool.name: fetch_sec_filing
βββ π·οΈ tool.transport: zeromcp_stdio
βββ β‘ Event: filing.parsed
================================================================================
Assert agent trajectory conformance in CI pipelines:
python3 scripts/agenttrace-check --actual actual.json --golden golden.json --max-dist 0Distributed under the Apache License 2.0.