sigil-telemetry

Plug-and-play telemetry for AI agents. Install it, call init(), and every LLM call your agent makes is automatically tracked in Sigil.

Quick Start

pip install sigil-telemetry[all]

from sigil_telemetry import init
init()

# Set your agent's ID and collector endpoint
SIGIL_AGENT_ID=sigil-agent-your-agent-slug
SIGIL_COLLECTOR_URL=https://your-collector-endpoint/

That's it. Every LLM API call is now captured — tokens, model, latency, errors — and sent to the Sigil collector.

What's New in v0.2.0

• Web framework auto-instrumentation — FastAPI, Flask, and Django are auto-detected and instrumented. All LLM calls within one HTTP request share a single trace_id (operation_Id), so you can count agent "runs" with COUNT(DISTINCT trace_id).
• Noise span filtering — http send / http send body spans from web frameworks are silently dropped before they leave the process. They never reach your collector, so you're not billed for them.
• Health check exclusion — Routes like /health, /healthz, /ready, /alive, /ping are excluded from tracing entirely. No spans generated, no storage cost.
• Graceful shutdown — atexit handler flushes all pending spans when the process exits, so you never lose the last batch.
• Lighter install — Removed unnecessary dependencies from the core install.

Full Example: What Actually Happens

Here's a real agent that summarizes documents using Claude. Let's walk through exactly what the telemetry captures and where it ends up.

1. The Agent Code

# document_summarizer.py
import anthropic
from sigil_telemetry import init

# Initialize telemetry — call this ONCE at startup
init()

# Your normal agent code — no changes needed
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[
        {"role": "user", "content": "Summarize this document: ..."}
    ]
)
print(response.content[0].text)

2. What Gets Captured (Per LLM Call)

Every time client.messages.create() runs, a span is automatically created with:

If the agent makes multiple LLM calls in one run (e.g., calls Claude then GPT-4), all calls share the same operation_Id so you can see the full trace.

3. How Trace Grouping Works

API agents (FastAPI/Flask/Django): The web framework instrumentor creates a root span per HTTP request. All LLM calls within that request automatically become child spans sharing the same trace_id. You don't need to do anything — init() handles it.

Worker agents (scheduled jobs, listeners): The template wraps your main() function in a root span. All LLM calls within one job or message share the same trace_id.

In both cases: COUNT(DISTINCT trace_id) = number of agent runs.

4. Where the Data Goes

Agent makes LLM call
        │
        ▼
sigil-telemetry auto-captures it as an OpenTelemetry span
(noise spans like "http send" are filtered out here)
        │
        ▼
Span is batched and sent via OTLP to:
  → Your configured collector endpoint
        │
        ▼
Collector forwards to:
  → Your observability backend (Jaeger, Zipkin, Datadog, etc.)

Supported SDKs

Use [all] to install everything. Only the SDKs your agent actually uses get activated.

Web Framework Auto-Instrumentation

These are included in [all] and auto-detected by init():

Health check routes (/health, /healthz, /ready, /alive, /ping, /startup, /liveness, /readiness) are automatically excluded from tracing.

Configuration

Or pass config in code:

from sigil_telemetry import init, SigilConfig

init(SigilConfig(
    agent_id="sigil-agent-my-agent",
    environment="development",
    console_export=True
))

Custom Spans

Track things beyond LLM calls (document parsing, tool use, etc.):

from sigil_telemetry import get_tracer, record_error

tracer = get_tracer()

with tracer.start_as_current_span("parse-contract") as span:
    span.set_attribute("document.pages", 42)
    try:
        result = parse_pdf(file)
    except Exception as e:
        record_error(span, e)
        raise