sigil-telemetry 0.2.0__tar.gz

sigil_telemetry-0.2.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: sigil-telemetry
+Version: 0.2.0
+Summary: Universal AI agent telemetry for Sigil — auto-instruments any LLM SDK and exports to the Sigil collector.
+Author: Zurain Khan
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
+Requires-Dist: opentelemetry-semantic-conventions>=0.41b0
+Provides-Extra: anthropic
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30.0; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: opentelemetry-instrumentation-openai>=0.30.0; extra == "openai"
+Provides-Extra: langchain
+Requires-Dist: opentelemetry-instrumentation-langchain>=0.30.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: opentelemetry-instrumentation-crewai>=0.30.0; extra == "crewai"
+Provides-Extra: llamaindex
+Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.30.0; extra == "llamaindex"
+Provides-Extra: vertexai
+Requires-Dist: opentelemetry-instrumentation-vertexai>=0.30.0; extra == "vertexai"
+Provides-Extra: mistral
+Requires-Dist: opentelemetry-instrumentation-mistralai>=0.30.0; extra == "mistral"
+Provides-Extra: bedrock
+Requires-Dist: opentelemetry-instrumentation-bedrock>=0.30.0; extra == "bedrock"
+Provides-Extra: litellm
+Requires-Dist: openinference-instrumentation-litellm>=0.1.0; extra == "litellm"
+Provides-Extra: fastapi
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: opentelemetry-instrumentation-flask>=0.41b0; extra == "flask"
+Provides-Extra: django
+Requires-Dist: opentelemetry-instrumentation-django>=0.41b0; extra == "django"
+Provides-Extra: databricks
+Requires-Dist: databricks-sql-connector>=4.0.0; extra == "databricks"
+Provides-Extra: all
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-openai>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-langchain>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-crewai>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-vertexai>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-mistralai>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-bedrock>=0.30.0; extra == "all"
+Requires-Dist: openinference-instrumentation-litellm>=0.1.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-flask>=0.41b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-django>=0.41b0; extra == "all"
+
+# 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
+
+```bash
+pip install sigil-telemetry[all]
+```
+
+```python
+from sigil_telemetry import init
+init()
+```
+
+```bash
+# 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
+
+```python
+# 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:
+
+| Field | Example Value | Description |
+|-------|--------------|-------------|
+| `operation_Id` | `a1b2c3d4e5f6...` | Trace ID — groups all LLM calls in a single agent run |
+| `sigil.agent.id` | `sigil-agent-doc-summarizer` | Which agent made the call |
+| `sigil.agent.version` | `sha-abc1234` | Agent version (set by deploy workflow) |
+| `sigil.agent.frameworks` | `Anthropic,FastAPI` | Which SDKs and frameworks were detected |
+| `gen_ai.system` | `anthropic` | LLM provider |
+| `gen_ai.request.model` | `claude-sonnet-4-20250514` | Model used |
+| `gen_ai.usage.input_tokens` | `1250` | Tokens sent |
+| `gen_ai.usage.output_tokens` | `340` | Tokens received |
+| `duration` | `2.3s` | How long the call took |
+| `status` | `OK` or `ERROR` | Whether the call succeeded |
+| `sigil.environment` | `production` | Environment |
+| `sigil.agent.division` | `Sales` | Business division (if set) |
+| `sigil.agent.risk_classification` | `low` | Risk level (if set) |
+
+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.
+
+| SDK | Install Extra | What It Covers |
+|-----|--------------|----------------|
+| Anthropic | `[anthropic]` | Anthropic API |
+| OpenAI | `[openai]` | OpenAI API (including compatible endpoints) |
+| LangChain | `[langchain]` | LangChain, LangGraph, any LangChain-wrapped model |
+| CrewAI | `[crewai]` | CrewAI multi-agent framework |
+| LlamaIndex | `[llamaindex]` | LlamaIndex agents and pipelines |
+| Vertex AI | `[vertexai]` | Google Vertex AI, Gemini models |
+| Mistral AI | `[mistral]` | Mistral API |
+| AWS Bedrock | `[bedrock]` | Claude, Llama, Titan via AWS |
+| LiteLLM | `[litellm]` | Unified proxy across 100+ LLM providers |
+
+## Web Framework Auto-Instrumentation
+
+These are included in `[all]` and auto-detected by `init()`:
+
+| Framework | Install Extra | What It Does |
+|-----------|--------------|--------------|
+| FastAPI | `[fastapi]` | Creates root span per HTTP request — all LLM calls in that request share one trace_id |
+| Flask | `[flask]` | Same trace grouping for Flask apps |
+| Django | `[django]` | Same trace grouping for Django apps |
+
+Health check routes (`/health`, `/healthz`, `/ready`, `/alive`, `/ping`, `/startup`, `/liveness`, `/readiness`) are automatically excluded from tracing.
+
+## Configuration
+
+| Env Variable | Default | Description |
+|-------------|---------|-------------|
+| `SIGIL_AGENT_ID` | — | **Required.** Your agent's Sigil ID |
+| `SIGIL_AGENT_VERSION` | `0.1.0` | Track deployments (set automatically by deploy workflow) |
+| `SIGIL_COLLECTOR_URL` | — | **Required.** Your collector endpoint URL |
+| `SIGIL_ENVIRONMENT` | `production` | `production`, `staging`, `development` |
+| `SIGIL_CONSOLE_EXPORT` | `false` | Print spans to console for debugging |
+| `SIGIL_DIVISION` | — | Business division (e.g., `Sales`, `Engineering`) |
+| `SIGIL_RISK_CLASSIFICATION` | — | Agent risk level (`low`, `medium`, `high`) |
+| `SIGIL_HOURS_SAVED` | — | Estimated hours saved per run |
+
+Or pass config in code:
+
+```python
+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.):
+
+```python
+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
+```
+

sigil_telemetry-0.2.0/README.md

@@ -0,0 +1,182 @@
+# 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
+
+```bash
+pip install sigil-telemetry[all]
+```
+
+```python
+from sigil_telemetry import init
+init()
+```
+
+```bash
+# 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
+
+```python
+# 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:
+
+| Field | Example Value | Description |
+|-------|--------------|-------------|
+| `operation_Id` | `a1b2c3d4e5f6...` | Trace ID — groups all LLM calls in a single agent run |
+| `sigil.agent.id` | `sigil-agent-doc-summarizer` | Which agent made the call |
+| `sigil.agent.version` | `sha-abc1234` | Agent version (set by deploy workflow) |
+| `sigil.agent.frameworks` | `Anthropic,FastAPI` | Which SDKs and frameworks were detected |
+| `gen_ai.system` | `anthropic` | LLM provider |
+| `gen_ai.request.model` | `claude-sonnet-4-20250514` | Model used |
+| `gen_ai.usage.input_tokens` | `1250` | Tokens sent |
+| `gen_ai.usage.output_tokens` | `340` | Tokens received |
+| `duration` | `2.3s` | How long the call took |
+| `status` | `OK` or `ERROR` | Whether the call succeeded |
+| `sigil.environment` | `production` | Environment |
+| `sigil.agent.division` | `Sales` | Business division (if set) |
+| `sigil.agent.risk_classification` | `low` | Risk level (if set) |
+
+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.
+
+| SDK | Install Extra | What It Covers |
+|-----|--------------|----------------|
+| Anthropic | `[anthropic]` | Anthropic API |
+| OpenAI | `[openai]` | OpenAI API (including compatible endpoints) |
+| LangChain | `[langchain]` | LangChain, LangGraph, any LangChain-wrapped model |
+| CrewAI | `[crewai]` | CrewAI multi-agent framework |
+| LlamaIndex | `[llamaindex]` | LlamaIndex agents and pipelines |
+| Vertex AI | `[vertexai]` | Google Vertex AI, Gemini models |
+| Mistral AI | `[mistral]` | Mistral API |
+| AWS Bedrock | `[bedrock]` | Claude, Llama, Titan via AWS |
+| LiteLLM | `[litellm]` | Unified proxy across 100+ LLM providers |
+
+## Web Framework Auto-Instrumentation
+
+These are included in `[all]` and auto-detected by `init()`:
+
+| Framework | Install Extra | What It Does |
+|-----------|--------------|--------------|
+| FastAPI | `[fastapi]` | Creates root span per HTTP request — all LLM calls in that request share one trace_id |
+| Flask | `[flask]` | Same trace grouping for Flask apps |
+| Django | `[django]` | Same trace grouping for Django apps |
+
+Health check routes (`/health`, `/healthz`, `/ready`, `/alive`, `/ping`, `/startup`, `/liveness`, `/readiness`) are automatically excluded from tracing.
+
+## Configuration
+
+| Env Variable | Default | Description |
+|-------------|---------|-------------|
+| `SIGIL_AGENT_ID` | — | **Required.** Your agent's Sigil ID |
+| `SIGIL_AGENT_VERSION` | `0.1.0` | Track deployments (set automatically by deploy workflow) |
+| `SIGIL_COLLECTOR_URL` | — | **Required.** Your collector endpoint URL |
+| `SIGIL_ENVIRONMENT` | `production` | `production`, `staging`, `development` |
+| `SIGIL_CONSOLE_EXPORT` | `false` | Print spans to console for debugging |
+| `SIGIL_DIVISION` | — | Business division (e.g., `Sales`, `Engineering`) |
+| `SIGIL_RISK_CLASSIFICATION` | — | Agent risk level (`low`, `medium`, `high`) |
+| `SIGIL_HOURS_SAVED` | — | Estimated hours saved per run |
+
+Or pass config in code:
+
+```python
+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.):
+
+```python
+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
+```
+

sigil_telemetry-0.2.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sigil-telemetry"
+version = "0.2.0"
+description = "Universal AI agent telemetry for Sigil — auto-instruments any LLM SDK and exports to the Sigil collector."
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+    {name = "Zurain Khan"}
+]
+
+# Core dependencies — always installed
+dependencies = [
+    "opentelemetry-api>=1.20.0",
+    "opentelemetry-sdk>=1.20.0",
+    "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+    "opentelemetry-semantic-conventions>=0.41b0",
+]
+
+[project.optional-dependencies]
+# Install only the instrumentors you need
+anthropic = ["opentelemetry-instrumentation-anthropic>=0.30.0"]
+openai = ["opentelemetry-instrumentation-openai>=0.30.0"]
+langchain = ["opentelemetry-instrumentation-langchain>=0.30.0"]
+crewai = ["opentelemetry-instrumentation-crewai>=0.30.0"]
+llamaindex = ["opentelemetry-instrumentation-llamaindex>=0.30.0"]
+vertexai = ["opentelemetry-instrumentation-vertexai>=0.30.0"]
+mistral = ["opentelemetry-instrumentation-mistralai>=0.30.0"]
+bedrock = ["opentelemetry-instrumentation-bedrock>=0.30.0"]
+litellm = ["openinference-instrumentation-litellm>=0.1.0"]
+# Web framework auto-instrumentation (for trace grouping)
+fastapi = ["opentelemetry-instrumentation-fastapi>=0.41b0"]
+flask = ["opentelemetry-instrumentation-flask>=0.41b0"]
+django = ["opentelemetry-instrumentation-django>=0.41b0"]
+
+# Databricks ingestion — only needed in the notebook, not in agents
+databricks = ["databricks-sql-connector>=4.0.0"]
+
+# Install all LLM instrumentors + web framework instrumentors
+all = [
+    "opentelemetry-instrumentation-anthropic>=0.30.0",
+    "opentelemetry-instrumentation-openai>=0.30.0",
+    "opentelemetry-instrumentation-langchain>=0.30.0",
+    "opentelemetry-instrumentation-crewai>=0.30.0",
+    "opentelemetry-instrumentation-llamaindex>=0.30.0",
+    "opentelemetry-instrumentation-vertexai>=0.30.0",
+    "opentelemetry-instrumentation-mistralai>=0.30.0",
+    "opentelemetry-instrumentation-bedrock>=0.30.0",
+    "openinference-instrumentation-litellm>=0.1.0",
+    "opentelemetry-instrumentation-fastapi>=0.41b0",
+    "opentelemetry-instrumentation-flask>=0.41b0",
+    "opentelemetry-instrumentation-django>=0.41b0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

sigil_telemetry-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sigil_telemetry-0.2.0/src/sigil_telemetry/__init__.py

@@ -0,0 +1,24 @@
+"""
+Sigil Telemetry — Universal AI Agent Telemetry Package
+======================================================
+
+Usage:
+    from sigil_telemetry import init
+    init()
+
+That's it. The package auto-detects installed LLM SDKs,
+instruments them, and exports telemetry to the Sigil collector.
+
+Environment Variables:
+    SIGIL_AGENT_ID          — Required. Your agent's unique ID (e.g. sigil-agent-my-agent)
+    SIGIL_AGENT_VERSION     — Optional. Agent version for tracking deployments (default: "0.1.0")
+    SIGIL_COLLECTOR_URL     — Required. Your collector endpoint URL
+    SIGIL_ENVIRONMENT       — Optional. "production", "staging", "development" (default: "production")
+    SIGIL_CONSOLE_EXPORT    — Optional. Set "true" to also print spans to console (for debugging)
+    OTEL_SERVICE_NAME       — Optional. Override service name (defaults to SIGIL_AGENT_ID)
+"""
+
+from sigil_telemetry.core import init, SigilConfig, get_tracer, record_error
+
+__version__ = "0.2.0"
+__all__ = ["init", "SigilConfig", "get_tracer", "record_error"]

sigil_telemetry-0.2.0/src/sigil_telemetry/core.py

@@ -0,0 +1,539 @@
+"""
+Sigil Telemetry Core — auto-detect, instrument, and export.
+
+Handles:
+- Anthropic SDK
+- OpenAI SDK (including compatible endpoints)
+- LangChain / LangGraph
+- CrewAI
+- LlamaIndex
+- Google Vertex AI / Gemini
+- Mistral AI
+- AWS Bedrock
+- LiteLLM (unified LLM proxy)
+- FastAPI / Flask auto-instrumentation (trace grouping)
+- Multi-model runs (all calls share one trace/operation_Id)
+- Model failures (captured as error spans with exception details)
+- Custom span attributes for Sigil-specific metadata
+- Noise span filtering (http send spans dropped before export)
+"""
+
+import os
+import sys
+import atexit
+import logging
+import importlib
+from dataclasses import dataclass, field
+from typing import Optional
+
+from opentelemetry import trace
+from opentelemetry.sdk.trace import TracerProvider, SpanProcessor
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    ConsoleSpanExporter,
+    SpanExportResult,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.trace import StatusCode
+
+logger = logging.getLogger("sigil_telemetry")
+
+
+# ──────────────────────────────────────────────
+# Default collector endpoint — set via SIGIL_COLLECTOR_URL env var
+# ──────────────────────────────────────────────
+DEFAULT_COLLECTOR_URL = None
+
+# ──────────────────────────────────────────────
+# Noise span names to drop before export.
+# FastAPI/Flask create these on every response —
+# they carry no LLM data and pollute the collector.
+# ──────────────────────────────────────────────
+_NOISE_SPAN_NAMES = frozenset({
+    "http send",
+    "http send body",
+    "http receive",
+})
+
+# ──────────────────────────────────────────────
+# Health check paths to exclude from tracing.
+# These never need telemetry — they only add
+# cost to the collector backend.
+# ──────────────────────────────────────────────
+_HEALTH_CHECK_PATHS = "health,healthz,ready,alive,ping,startup,liveness,readiness"
+
+# ──────────────────────────────────────────────
+# Supported LLM SDK instrumentors
+# ──────────────────────────────────────────────
+INSTRUMENTORS = [
+    {
+        "name": "Anthropic",
+        "sdk_module": "anthropic",
+        "instrumentor_module": "opentelemetry.instrumentation.anthropic",
+        "instrumentor_class": "AnthropicInstrumentor",
+    },
+    {
+        "name": "OpenAI",
+        "sdk_module": "openai",
+        "instrumentor_module": "opentelemetry.instrumentation.openai",
+        "instrumentor_class": "OpenAIInstrumentor",
+    },
+    {
+        "name": "LangChain / LangGraph",
+        "sdk_module": "langchain",
+        "instrumentor_module": "opentelemetry.instrumentation.langchain",
+        "instrumentor_class": "LangchainInstrumentor",
+    },
+    {
+        "name": "CrewAI",
+        "sdk_module": "crewai",
+        "instrumentor_module": "opentelemetry.instrumentation.crewai",
+        "instrumentor_class": "CrewAIInstrumentor",
+    },
+    {
+        "name": "LlamaIndex",
+        "sdk_module": "llama_index",
+        "instrumentor_module": "opentelemetry.instrumentation.llamaindex",
+        "instrumentor_class": "LlamaIndexInstrumentor",
+    },
+    {
+        "name": "Google Vertex AI / Gemini",
+        "sdk_module": "vertexai",
+        "instrumentor_module": "opentelemetry.instrumentation.vertexai",
+        "instrumentor_class": "VertexAIInstrumentor",
+    },
+    {
+        "name": "Mistral AI",
+        "sdk_module": "mistralai",
+        "instrumentor_module": "opentelemetry.instrumentation.mistralai",
+        "instrumentor_class": "MistralAIInstrumentor",
+    },
+    {
+        "name": "AWS Bedrock",
+        "sdk_module": "boto3",
+        "instrumentor_module": "opentelemetry.instrumentation.bedrock",
+        "instrumentor_class": "BedrockInstrumentor",
+    },
+    {
+        "name": "LiteLLM",
+        "sdk_module": "litellm",
+        "instrumentor_module": "openinference.instrumentation.litellm",
+        "instrumentor_class": "LiteLLMInstrumentor",
+    },
+]
+
+# ──────────────────────────────────────────────
+# Web framework instrumentors (for trace grouping)
+# These create a root span per HTTP request so
+# all LLM calls within one request share a trace_id.
+# ──────────────────────────────────────────────
+FRAMEWORK_INSTRUMENTORS = [
+    {
+        "name": "FastAPI",
+        "sdk_module": "fastapi",
+        "instrumentor_module": "opentelemetry.instrumentation.fastapi",
+        "instrumentor_class": "FastAPIInstrumentor",
+    },
+    {
+        "name": "Flask",
+        "sdk_module": "flask",
+        "instrumentor_module": "opentelemetry.instrumentation.flask",
+        "instrumentor_class": "FlaskInstrumentor",
+    },
+    {
+        "name": "Django",
+        "sdk_module": "django",
+        "instrumentor_module": "opentelemetry.instrumentation.django",
+        "instrumentor_class": "DjangoInstrumentor",
+    },
+]
+
+
+# ──────────────────────────────────────────────
+# Filtering SpanProcessor — drops noise spans
+# before they reach the exporter, so the collector
+# never sees or bills for them.
+# ──────────────────────────────────────────────
+class _FilteringSpanProcessor(SpanProcessor):
+    """Wraps an inner SpanProcessor and silently drops spans
+    whose names match the noise set (http send, etc.)."""
+
+    def __init__(self, inner: SpanProcessor, drop_names: frozenset):
+        self._inner = inner
+        self._drop_names = drop_names
+
+    def on_start(self, span, parent_context=None):
+        self._inner.on_start(span, parent_context)
+
+    def on_end(self, span):
+        if span.name in self._drop_names:
+            return  # silently drop — never exported
+        self._inner.on_end(span)
+
+    def shutdown(self):
+        self._inner.shutdown()
+
+    def force_flush(self, timeout_millis=None):
+        self._inner.force_flush(timeout_millis)
+
+
+@dataclass
+class SigilConfig:
+    """Configuration for Sigil telemetry. All fields have sensible defaults
+    that read from environment variables, so most users never need to touch this."""
+
+    agent_id: Optional[str] = None
+    agent_version: str = "0.1.0"
+    collector_url: Optional[str] = None
+    environment: str = "production"
+    console_export: bool = False
+    service_name: Optional[str] = None
+
+    # Extra resource attributes to attach to every span
+    extra_attributes: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Resolve values from environment variables if not explicitly set."""
+        self.agent_id = self.agent_id or os.environ.get("SIGIL_AGENT_ID")
+        self.agent_version = (
+            os.environ.get("SIGIL_AGENT_VERSION") or self.agent_version
+        )
+        self.collector_url = (
+            self.collector_url
+            or os.environ.get("SIGIL_COLLECTOR_URL")
+        )
+        self.environment = (
+            os.environ.get("SIGIL_ENVIRONMENT") or self.environment
+        )
+        self.console_export = (
+            os.environ.get("SIGIL_CONSOLE_EXPORT", "").lower() == "true"
+            or self.console_export
+        )
+        self.service_name = (
+            self.service_name
+            or os.environ.get("OTEL_SERVICE_NAME")
+            or self.agent_id
+            or "sigil-agent-unknown"
+        )
+
+
+# Track initialization state
+_initialized = False
+_provider = None  # Keep reference for atexit shutdown
+
+
+def init(config: Optional[SigilConfig] = None) -> dict:
+    """
+    Initialize Sigil telemetry. Call once at application startup.
+
+    Args:
+        config: Optional SigilConfig. If None, reads everything from env vars.
+
+    Returns:
+        dict with keys:
+            - "status": "ok" or "error"
+            - "agent_id": the resolved agent ID
+            - "instrumented": list of SDK names that were instrumented
+            - "frameworks": list of web frameworks that were instrumented
+            - "skipped": list of SDK names that were skipped (not installed)
+            - "errors": list of errors encountered during instrumentation
+
+    Example:
+        from sigil_telemetry import init
+
+        # Simplest — reads everything from env vars
+        init()
+
+        # Or with explicit config
+        from sigil_telemetry import init, SigilConfig
+        init(SigilConfig(agent_id="sigil-agent-my-agent", console_export=True))
+    """
+    global _initialized, _provider
+
+    if _initialized:
+        logger.warning("Sigil telemetry already initialized — skipping re-init")
+        return {"status": "ok", "message": "already initialized"}
+
+    cfg = config or SigilConfig()
+
+    result = {
+        "status": "ok",
+        "agent_id": cfg.agent_id,
+        "instrumented": [],
+        "frameworks": [],
+        "skipped": [],
+        "errors": [],
+    }
+
+    # ── Validate ──────────────────────────────────────
+    if not cfg.agent_id:
+        logger.warning(
+            "SIGIL_AGENT_ID not set. Telemetry will work but agent "
+            "identification in Sigil will show as 'unknown'. "
+            "Set the SIGIL_AGENT_ID environment variable or pass "
+            "SigilConfig(agent_id='...')"
+        )
+
+    if not cfg.collector_url:
+        logger.error(
+            "SIGIL_COLLECTOR_URL not set. Telemetry has nowhere to send spans. "
+            "Set the SIGIL_COLLECTOR_URL environment variable or pass "
+            "SigilConfig(collector_url='https://your-collector-endpoint')"
+        )
+        result["status"] = "error"
+        result["errors"].append("No collector URL configured")
+        return result
+
+    # ── Build OTel Resource ───────────────────────────
+    resource_attrs = {
+        "service.name": cfg.service_name,
+        "service.version": cfg.agent_version,
+        "deployment.environment": cfg.environment,
+        "sigil.agent.id": cfg.agent_id or "unknown",
+        "sigil.agent.version": cfg.agent_version,
+        "sigil.environment": cfg.environment,
+    }
+
+    # Read additional Sigil governance metadata from env vars
+    for env_key, attr_key in [
+        ("SIGIL_DIVISION", "sigil.agent.division"),
+        ("SIGIL_RISK_CLASSIFICATION", "sigil.agent.risk_classification"),
+        ("SIGIL_HOURS_SAVED", "sigil.agent.hours_saved"),
+    ]:
+        val = os.environ.get(env_key)
+        if val:
+            resource_attrs[attr_key] = val
+
+    resource_attrs.update(cfg.extra_attributes)
+
+    # ── Auto-detect LLM SDKs ─────────────────────────
+    instrumented_set = set()
+    for spec in INSTRUMENTORS:
+        name = spec["name"]
+        shared = spec.get("shared_with")
+
+        # Skip if this instrumentor is shared with one already activated
+        if shared and shared in instrumented_set:
+            logger.debug(f"  {name}: shares instrumentor with {shared}, skipping")
+            continue
+
+        # Check if the target SDK is installed
+        if not _is_installed(spec["sdk_module"]):
+            result["skipped"].append(name)
+            logger.debug(f"  {name}: SDK not installed, skipping")
+            continue
+
+        # Check if the instrumentor package is installed
+        if not _is_installed(spec["instrumentor_module"]):
+            msg = (
+                f"{name} SDK detected but instrumentor not installed. "
+                f"Install with: pip install sigil-telemetry[{spec['sdk_module'].split('.')[0]}]"
+            )
+            result["errors"].append(msg)
+            logger.warning(f"  {name}: {msg}")
+            continue
+
+        # Instrument
+        try:
+            module = importlib.import_module(spec["instrumentor_module"])
+            instrumentor_cls = getattr(module, spec["instrumentor_class"])
+            instrumentor = instrumentor_cls()
+            if not instrumentor.is_instrumented_by_opentelemetry:
+                instrumentor.instrument()
+                instrumented_set.add(name)
+                result["instrumented"].append(name)
+                logger.info(f"  ✓ {name} instrumented")
+            else:
+                logger.debug(f"  {name}: already instrumented")
+                result["instrumented"].append(name)
+        except Exception as e:
+            msg = f"Failed to instrument {name}: {e}"
+            result["errors"].append(msg)
+            logger.error(f"  ✗ {msg}")
+
+    # ── Auto-detect web frameworks (for trace grouping) ──
+    for spec in FRAMEWORK_INSTRUMENTORS:
+        name = spec["name"]
+
+        if not _is_installed(spec["sdk_module"]):
+            logger.debug(f"  {name}: not installed, skipping framework instrumentation")
+            continue
+
+        if not _is_installed(spec["instrumentor_module"]):
+            logger.debug(f"  {name}: instrumentor not installed, skipping")
+            continue
+
+        try:
+            module = importlib.import_module(spec["instrumentor_module"])
+            instrumentor_cls = getattr(module, spec["instrumentor_class"])
+            instrumentor = instrumentor_cls()
+            if not instrumentor.is_instrumented_by_opentelemetry:
+                instrumentor.instrument(excluded_urls=_HEALTH_CHECK_PATHS)
+                result["frameworks"].append(name)
+                logger.info(f"  ✓ {name} framework instrumented (health checks excluded)")
+            else:
+                logger.debug(f"  {name}: already instrumented")
+                result["frameworks"].append(name)
+        except Exception as e:
+            msg = f"Failed to instrument {name} framework: {e}"
+            result["errors"].append(msg)
+            logger.error(f"  ✗ {msg}")
+
+    # ── Record detected frameworks in resource attributes ──
+    all_instrumented = result["instrumented"] + result["frameworks"]
+    if all_instrumented:
+        resource_attrs["sigil.agent.frameworks"] = ",".join(all_instrumented)
+    else:
+        resource_attrs["sigil.agent.frameworks"] = "none"
+        logger.warning(
+            "No LLM SDKs were instrumented. Install at least one supported SDK "
+            "(anthropic, openai, langchain, crewai, llama-index, vertexai, "
+            "mistralai, bedrock, litellm) and its corresponding instrumentor."
+        )
+
+    # ── Now build the Resource and TracerProvider ─────
+    resource = Resource.create(resource_attrs)
+    provider = TracerProvider(resource=resource)
+    _provider = provider
+
+    # OTLP exporter → Sigil collector
+    # Wrapped in _FilteringSpanProcessor to drop noise spans
+    # (http send, http send body) before they reach the collector.
+    otlp_endpoint = f"{cfg.collector_url}/v1/traces"
+    otlp_exporter = OTLPSpanExporter(endpoint=otlp_endpoint)
+    batch_processor = BatchSpanProcessor(otlp_exporter)
+    filtering_processor = _FilteringSpanProcessor(batch_processor, _NOISE_SPAN_NAMES)
+    provider.add_span_processor(filtering_processor)
+
+    # Optional console exporter for debugging
+    if cfg.console_export:
+        provider.add_span_processor(BatchSpanProcessor(ConsoleSpanExporter()))
+        logger.info("Console span export enabled (debug mode)")
+
+    trace.set_tracer_provider(provider)
+
+    # ── Register atexit handler to flush pending spans ──
+    atexit.register(_shutdown)
+
+    logger.info(
+        f"Sigil telemetry initialized — agent={cfg.agent_id}, "
+        f"collector={cfg.collector_url}, env={cfg.environment}, "
+        f"frameworks={resource_attrs.get('sigil.agent.frameworks')}"
+    )
+
+    if result["errors"]:
+        result["status"] = "partial"
+
+    _initialized = True
+
+    # Print a clean startup banner
+    _print_banner(cfg, result)
+
+    return result
+
+
+def get_tracer(name: str = "sigil-telemetry") -> trace.Tracer:
+    """Get an OTel tracer for creating custom spans.
+
+    Use this when you want to add custom instrumentation beyond
+    what the auto-instrumentors capture:
+
+        from sigil_telemetry import get_tracer
+
+        tracer = get_tracer()
+        with tracer.start_as_current_span("document-parsing") as span:
+            span.set_attribute("document.pages", 42)
+            span.set_attribute("document.type", "contract")
+            result = parse_document(doc)
+    """
+    return trace.get_tracer(name)
+
+
+def record_error(
+    span: trace.Span,
+    exception: Exception,
+    attributes: Optional[dict] = None,
+) -> None:
+    """Record an error on a span with Sigil-standard attributes.
+
+    Use this to capture model failures, API errors, rate limits, etc.:
+
+        from sigil_telemetry import get_tracer, record_error
+
+        tracer = get_tracer()
+        with tracer.start_as_current_span("llm-call") as span:
+            try:
+                response = client.messages.create(...)
+            except Exception as e:
+                record_error(span, e, {"retry_count": 2})
+                raise
+    """
+    span.set_status(StatusCode.ERROR, str(exception))
+    span.record_exception(exception)
+    if attributes:
+        for k, v in attributes.items():
+            span.set_attribute(f"sigil.error.{k}", v)
+
+
+def _shutdown():
+    """Flush all pending spans on process exit."""
+    global _provider
+    if _provider:
+        try:
+            _provider.shutdown()
+        except Exception:
+            pass  # Best effort — process is exiting
+
+
+def _is_installed(module_name: str) -> bool:
+    """Check if a Python module is importable."""
+    try:
+        importlib.import_module(module_name)
+        return True
+    except ImportError:
+        return False
+
+
+def _print_banner(cfg: SigilConfig, result: dict) -> None:
+    """Print a clean startup banner."""
+    lines = [
+        "",
+        "╔══════════════════════════════════════════════════╗",
+        "║           Sigil Telemetry Initialized            ║",
+        "╠══════════════════════════════════════════════════╣",
+        f"║  Agent ID  : {(cfg.agent_id or 'not set'):<35} ║",
+        f"║  Version   : {cfg.agent_version:<35} ║",
+        f"║  Env       : {cfg.environment:<35} ║",
+        f"║  Collector : {'connected':<35} ║",
+        "╠══════════════════════════════════════════════════╣",
+    ]
+
+    if result["instrumented"]:
+        lines.append(f"║  LLM SDKs:                                       ║")
+        for sdk in result["instrumented"]:
+            lines.append(f"║    ✓ {sdk:<43} ║")
+
+    if result["frameworks"]:
+        lines.append(f"║  Web Frameworks:                                  ║")
+        for fw in result["frameworks"]:
+            lines.append(f"║    ✓ {fw:<43} ║")
+
+    if not result["instrumented"] and not result["frameworks"]:
+        lines.append(f"║  ⚠ No SDKs instrumented                          ║")
+
+    if result["skipped"]:
+        lines.append(f"║  Skipped (not installed):                         ║")
+        for sdk in result["skipped"]:
+            lines.append(f"║    · {sdk:<43} ║")
+
+    if result["errors"]:
+        lines.append(f"║  Errors:                                         ║")
+        for err in result["errors"]:
+            short = err[:43]
+            lines.append(f"║    ✗ {short:<43} ║")
+
+    lines.append("╚══════════════════════════════════════════════════╝")
+    lines.append("")
+
+    print("\n".join(lines))

sigil_telemetry-0.2.0/src/sigil_telemetry.egg-info/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.4
+Name: sigil-telemetry
+Version: 0.2.0
+Summary: Universal AI agent telemetry for Sigil — auto-instruments any LLM SDK and exports to the Sigil collector.
+Author: Zurain Khan
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: opentelemetry-api>=1.20.0
+Requires-Dist: opentelemetry-sdk>=1.20.0
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.20.0
+Requires-Dist: opentelemetry-semantic-conventions>=0.41b0
+Provides-Extra: anthropic
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30.0; extra == "anthropic"
+Provides-Extra: openai
+Requires-Dist: opentelemetry-instrumentation-openai>=0.30.0; extra == "openai"
+Provides-Extra: langchain
+Requires-Dist: opentelemetry-instrumentation-langchain>=0.30.0; extra == "langchain"
+Provides-Extra: crewai
+Requires-Dist: opentelemetry-instrumentation-crewai>=0.30.0; extra == "crewai"
+Provides-Extra: llamaindex
+Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.30.0; extra == "llamaindex"
+Provides-Extra: vertexai
+Requires-Dist: opentelemetry-instrumentation-vertexai>=0.30.0; extra == "vertexai"
+Provides-Extra: mistral
+Requires-Dist: opentelemetry-instrumentation-mistralai>=0.30.0; extra == "mistral"
+Provides-Extra: bedrock
+Requires-Dist: opentelemetry-instrumentation-bedrock>=0.30.0; extra == "bedrock"
+Provides-Extra: litellm
+Requires-Dist: openinference-instrumentation-litellm>=0.1.0; extra == "litellm"
+Provides-Extra: fastapi
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "fastapi"
+Provides-Extra: flask
+Requires-Dist: opentelemetry-instrumentation-flask>=0.41b0; extra == "flask"
+Provides-Extra: django
+Requires-Dist: opentelemetry-instrumentation-django>=0.41b0; extra == "django"
+Provides-Extra: databricks
+Requires-Dist: databricks-sql-connector>=4.0.0; extra == "databricks"
+Provides-Extra: all
+Requires-Dist: opentelemetry-instrumentation-anthropic>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-openai>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-langchain>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-crewai>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-llamaindex>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-vertexai>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-mistralai>=0.30.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-bedrock>=0.30.0; extra == "all"
+Requires-Dist: openinference-instrumentation-litellm>=0.1.0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-fastapi>=0.41b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-flask>=0.41b0; extra == "all"
+Requires-Dist: opentelemetry-instrumentation-django>=0.41b0; extra == "all"
+
+# 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
+
+```bash
+pip install sigil-telemetry[all]
+```
+
+```python
+from sigil_telemetry import init
+init()
+```
+
+```bash
+# 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
+
+```python
+# 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:
+
+| Field | Example Value | Description |
+|-------|--------------|-------------|
+| `operation_Id` | `a1b2c3d4e5f6...` | Trace ID — groups all LLM calls in a single agent run |
+| `sigil.agent.id` | `sigil-agent-doc-summarizer` | Which agent made the call |
+| `sigil.agent.version` | `sha-abc1234` | Agent version (set by deploy workflow) |
+| `sigil.agent.frameworks` | `Anthropic,FastAPI` | Which SDKs and frameworks were detected |
+| `gen_ai.system` | `anthropic` | LLM provider |
+| `gen_ai.request.model` | `claude-sonnet-4-20250514` | Model used |
+| `gen_ai.usage.input_tokens` | `1250` | Tokens sent |
+| `gen_ai.usage.output_tokens` | `340` | Tokens received |
+| `duration` | `2.3s` | How long the call took |
+| `status` | `OK` or `ERROR` | Whether the call succeeded |
+| `sigil.environment` | `production` | Environment |
+| `sigil.agent.division` | `Sales` | Business division (if set) |
+| `sigil.agent.risk_classification` | `low` | Risk level (if set) |
+
+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.
+
+| SDK | Install Extra | What It Covers |
+|-----|--------------|----------------|
+| Anthropic | `[anthropic]` | Anthropic API |
+| OpenAI | `[openai]` | OpenAI API (including compatible endpoints) |
+| LangChain | `[langchain]` | LangChain, LangGraph, any LangChain-wrapped model |
+| CrewAI | `[crewai]` | CrewAI multi-agent framework |
+| LlamaIndex | `[llamaindex]` | LlamaIndex agents and pipelines |
+| Vertex AI | `[vertexai]` | Google Vertex AI, Gemini models |
+| Mistral AI | `[mistral]` | Mistral API |
+| AWS Bedrock | `[bedrock]` | Claude, Llama, Titan via AWS |
+| LiteLLM | `[litellm]` | Unified proxy across 100+ LLM providers |
+
+## Web Framework Auto-Instrumentation
+
+These are included in `[all]` and auto-detected by `init()`:
+
+| Framework | Install Extra | What It Does |
+|-----------|--------------|--------------|
+| FastAPI | `[fastapi]` | Creates root span per HTTP request — all LLM calls in that request share one trace_id |
+| Flask | `[flask]` | Same trace grouping for Flask apps |
+| Django | `[django]` | Same trace grouping for Django apps |
+
+Health check routes (`/health`, `/healthz`, `/ready`, `/alive`, `/ping`, `/startup`, `/liveness`, `/readiness`) are automatically excluded from tracing.
+
+## Configuration
+
+| Env Variable | Default | Description |
+|-------------|---------|-------------|
+| `SIGIL_AGENT_ID` | — | **Required.** Your agent's Sigil ID |
+| `SIGIL_AGENT_VERSION` | `0.1.0` | Track deployments (set automatically by deploy workflow) |
+| `SIGIL_COLLECTOR_URL` | — | **Required.** Your collector endpoint URL |
+| `SIGIL_ENVIRONMENT` | `production` | `production`, `staging`, `development` |
+| `SIGIL_CONSOLE_EXPORT` | `false` | Print spans to console for debugging |
+| `SIGIL_DIVISION` | — | Business division (e.g., `Sales`, `Engineering`) |
+| `SIGIL_RISK_CLASSIFICATION` | — | Agent risk level (`low`, `medium`, `high`) |
+| `SIGIL_HOURS_SAVED` | — | Estimated hours saved per run |
+
+Or pass config in code:
+
+```python
+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.):
+
+```python
+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
+```
+

sigil_telemetry-0.2.0/src/sigil_telemetry.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+src/sigil_telemetry/__init__.py
+src/sigil_telemetry/core.py
+src/sigil_telemetry.egg-info/PKG-INFO
+src/sigil_telemetry.egg-info/SOURCES.txt
+src/sigil_telemetry.egg-info/dependency_links.txt
+src/sigil_telemetry.egg-info/requires.txt
+src/sigil_telemetry.egg-info/top_level.txt

sigil_telemetry-0.2.0/src/sigil_telemetry.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sigil_telemetry-0.2.0/src/sigil_telemetry.egg-info/requires.txt

@@ -0,0 +1,57 @@
+opentelemetry-api>=1.20.0
+opentelemetry-sdk>=1.20.0
+opentelemetry-exporter-otlp-proto-http>=1.20.0
+opentelemetry-semantic-conventions>=0.41b0
+
+[all]
+opentelemetry-instrumentation-anthropic>=0.30.0
+opentelemetry-instrumentation-openai>=0.30.0
+opentelemetry-instrumentation-langchain>=0.30.0
+opentelemetry-instrumentation-crewai>=0.30.0
+opentelemetry-instrumentation-llamaindex>=0.30.0
+opentelemetry-instrumentation-vertexai>=0.30.0
+opentelemetry-instrumentation-mistralai>=0.30.0
+opentelemetry-instrumentation-bedrock>=0.30.0
+openinference-instrumentation-litellm>=0.1.0
+opentelemetry-instrumentation-fastapi>=0.41b0
+opentelemetry-instrumentation-flask>=0.41b0
+opentelemetry-instrumentation-django>=0.41b0
+
+[anthropic]
+opentelemetry-instrumentation-anthropic>=0.30.0
+
+[bedrock]
+opentelemetry-instrumentation-bedrock>=0.30.0
+
+[crewai]
+opentelemetry-instrumentation-crewai>=0.30.0
+
+[databricks]
+databricks-sql-connector>=4.0.0
+
+[django]
+opentelemetry-instrumentation-django>=0.41b0
+
+[fastapi]
+opentelemetry-instrumentation-fastapi>=0.41b0
+
+[flask]
+opentelemetry-instrumentation-flask>=0.41b0
+
+[langchain]
+opentelemetry-instrumentation-langchain>=0.30.0
+
+[litellm]
+openinference-instrumentation-litellm>=0.1.0
+
+[llamaindex]
+opentelemetry-instrumentation-llamaindex>=0.30.0
+
+[mistral]
+opentelemetry-instrumentation-mistralai>=0.30.0
+
+[openai]
+opentelemetry-instrumentation-openai>=0.30.0
+
+[vertexai]
+opentelemetry-instrumentation-vertexai>=0.30.0

sigil_telemetry-0.2.0/src/sigil_telemetry.egg-info/top_level.txt

@@ -0,0 +1 @@
+sigil_telemetry