Skip to content

About

Zero-Dependency Distributed Tracing & Execution Graph Telemetry for AI Agents, Tool IPC, and MCP Servers

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

Β 

History

9 Commits

Folders and files

Repository files navigation

🌲 AgentTrace: Zero-Dependency Distributed Tracing for AI Agents & Tool IPC

License Dependencies Python W3C Trace Context CI Build

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.


⚑ Why AgentTrace?

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:

  1. Strictly Zero Dependencies: Pure Python standard library (json, sqlite3, time, dataclasses, uuid, urllib.request).
  2. W3C Distributed Trace Context: Full traceparent support (00-{trace_id}-{span_id}-01) for end-to-end correlation across multi-agent systems and MCP tool servers.
  3. OpenTelemetry GenAI Semantic Alignment: Native OTel attribute mapping (gen_ai.system, gen_ai.request.model, tool.transport).
  4. Local Append-Only JSONL & SQLite Sinks: Sub-millisecond persistence without sending agent thoughts to third-party clouds.
  5. Pure Python OTLP HTTP/JSON Exporter: Pipes directly into Jaeger, Grafana Tempo, Honeycomb, or Datadog without heavy SDK bloat.

Benchmark Performance

Evaluated across 5,000 trace iterations (Apple Silicon & POSIX x86):

Telemetry Operation $p_{50}$ Latency $p_{90}$ Latency $p_{99}$ Latency Throughput Overhead Budget
W3C Traceparent Header Parsing 0.71 Β΅s 0.75 Β΅s 0.79 Β΅s ~1,410,000 headers/s $< 0.01\text{ ms}$ (βœ… 14x headroom)
OTLP JSON Serialization 0.69 Β΅s/span 0.76 Β΅s 1.03 Β΅s ~1,448,000 spans/s $< 0.05\text{ ms}$ (βœ… 72x headroom)
Span Lifecycle (Start + Attrs + SQLite Persist) 131.8 Β΅s 202.7 Β΅s 8,258.6 Β΅s ~7,580 spans/s $< 0.25\text{ ms}$ (βœ… 1.9x headroom)
AgentTrace Rust Native (agenttrace) < 15 Β΅s < 28 Β΅s < 65 Β΅s ~65,000+ spans/s $&lt; 0.05\text{ ms}$ (βœ… 3.3x headroom)
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).


🌐 The CreativeUnCommons Agent Architecture Ecosystem

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 (&lt;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
Loading

Complete Runtime Synergy

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 $&lt;5\text{ms}$ without double-charging cards, re-sending emails, or burning duplicate tokens.
πŸ›‘οΈ 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 $&lt;1\text{ms}$ (saving $70\text{--}90%$ context tokens) and hard-stops runaway agent spend.
πŸ”Œ ZeroMCP Tool Protocol & CAS Engine Zero-dependency Model Context Protocol (MCP) runtime (stdio/SSE) with CAS storage. High-speed ($&lt;25\text{Β΅s}$) tool execution; automatically offloads megabyte tool outputs to CAS so the LLM context never blows up.
🌲 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.

πŸ“¦ Project Structure

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

⚑ Multi-Language Implementations (Python & Rust)

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) $0.71\text{ Β΅s}$ parse $\sim 1,410,000\text{ ops/sec}$ Python agent orchestrators, LangChain/LlamaIndex hooks, zero-install
agenttrace-rs agenttrace-rs/ Rust stdlib + rusqlite, serde, uuid $&lt; 0.20\text{ Β΅s}$ parse $\sim 5,000,000+\text{ ops/sec}$ High-concurrency edge agents, native IPC proxies, microsecond tracing

Building and Running the Rust Core

# 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>

πŸš€ Quick Example

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})

Render Execution Tree via CLI

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
================================================================================

Golden-Path CI Trajectory Grader

Assert agent trajectory conformance in CI pipelines:

python3 scripts/agenttrace-check --actual actual.json --golden golden.json --max-dist 0

πŸ“„ License

Distributed under the Apache License 2.0.

About

Zero-Dependency Distributed Tracing & Execution Graph Telemetry for AI Agents, Tool IPC, and MCP Servers

Topics

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages