Auto-Instrumentation¶

Add Pisama failure detection to any LLM application with one line of code. No trace construction, no SDK hooks, no configuration needed.

Install¶

pip install "pisama[auto]"

This is the recommended install because it keeps the Pisama CLI, local detectors, and instrumentation layer on a compatible dependency path. Direct pip install pisama-auto remains supported for instrumentation-only applications.

Quick Start¶

import pisama_auto
pisama_auto.init()

# All subsequent LLM calls are automatically traced
import anthropic
client = anthropic.Anthropic()
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello"}],
)
# This call is traced with OTEL gen_ai.* semantic conventions.

How It Works¶

pisama_auto.init() does two things:

1. Sets up an OTEL tracer that exports spans to Pisama (or console for local debugging)
2. Monkey-patches LLM SDKs to wrap API calls with OTEL spans

Each LLM call emits a span with:

• gen_ai.system — provider (anthropic, openai)
• gen_ai.request.model — model name
• gen_ai.usage.input_tokens / output_tokens / total_tokens — token counts
• gen_ai.response.stop_reason — why the model stopped
• Error attributes on failure

Supported Libraries¶

Configuration¶

Export to Pisama Platform¶

Get your API key at pisama.ai/settings/api-keys (sign up at pisama.ai/sign-up first).

pisama_auto.init(api_key="pisama_...")

Or set the PISAMA_API_KEY environment variable:

export PISAMA_API_KEY=pisama_your_key_here
python my_app.py

Custom Endpoint¶

pisama_auto.init(
    api_key="pisama_...",
    endpoint="https://api.pisama.ai/api/v1/traces/ingest",
)

Or set PISAMA_ENDPOINT.

Local-Only (No Export)¶

pisama_auto.init()  # No API key — traces go to console only

Selective Patching¶

pisama_auto.init(auto_patch=False)  # Don't patch anything automatically

from pisama_auto.patches import patch
patch("anthropic")  # Only patch Anthropic SDK

Integration with Detection¶

Traces exported by pisama-auto flow through the standard Pisama detection pipeline:

1. Spans arrive at the OTEL ingestion endpoint
2. The OTEL parser extracts states from gen_ai.* attributes
3. Detectors analyze the trace for failures
4. Results appear in the dashboard

This works with all core detectors and the full tiered detection pipeline.