Python SDK

About the Python SDK

telemetry-dev brings GenAI tracing, logs, and metrics to any Python app. It's a thin ergonomic layer over OpenTelemetry spans using the gen_ai.* semantic conventions, exported as OTLP protobuf. Requires Python >= 3.10, and it's the foundation for the OpenAI, Anthropic, Gemini, Bedrock, and LiteLLM instrumentation packages.

Key features

• @observe decorator: Wrap sync or async functions (generators too) — arguments become span input, return values become output, exceptions are captured and re-raised.
• Typed span API: start_span(type="generation", model=..., provider=..., input=...) as a context manager or detached handle, plus update_current_span for in-flight updates.
• User and session correlation: propagate_attributes(user_id=..., session_id=...) stamps every span and log record in scope — across threads and asyncio.
• Logs and metrics included: log() emits trace-correlated OTLP log records; GenAI histograms are recorded automatically.
• Bring your own OTel: TelemetrySpanProcessor attaches to an existing provider without adopting the SDK runtime.
• Fail-open: Without an API key every call is a silent no-op; internal errors are never raised into your code.

Get started

import telemetry_dev
from telemetry_dev import observe, propagate_attributes, start_span

telemetry_dev.init()  # reads TELEMETRY_DEV_API_KEY

@observe
def lookup_weather(city: str) -> dict:
    return {"forecast": "sunny"}

with propagate_attributes(user_id="user_123", session_id="session_456"):
    with start_span(
        "chat gpt-4o",
        type="generation",
        model="gpt-4o",
        provider="openai",
        input=[{"role": "user", "content": "Plan a day trip"}],
    ):
        lookup_weather("Kyoto")

telemetry_dev.flush()

Install with pip install telemetry-dev or uv add telemetry-dev. Cost is computed server-side from usage and current model pricing.