telemetry-dev

telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics. Thin ergonomic functions over OTel spans (gen_ai.* semantic conventions), exported as OTLP protobuf to the telemetry.dev ingest.

Install

pip install telemetry-dev
# or
uv add telemetry-dev

Requires Python >= 3.10.

Quickstart

import telemetry_dev
from telemetry_dev import log, observe, propagate_attributes, start_span, update_current_span

telemetry_dev.init()  # reads TELEMETRY_DEV_API_KEY from the environment

@observe  # arguments -> input, return value -> output, errors captured + re-raised
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"}],
    ):
        log("calling the model")
        update_current_span(
            output=[{"role": "assistant", "content": "Here you go..."}],
            usage={"input_tokens": 11, "output_tokens": 7},
            finish_reason="stop",
        )

    lookup_weather("Kyoto")

telemetry_dev.flush()

The SDK fails open: without an API key every call is a silent no-op, and internal errors are routed to the on_error hook / telemetry_dev logger — never raised into your code.

Environment variables

Explicit init() arguments take precedence over environment variables.

Root spans remain independent by default. telemetry_dev.init(session_mode="process") groups otherwise uncorrelated spans and logs using a fresh opaque UUID for each enabled SDK initialization. Explicit and propagated session IDs take precedence, and valid parent trace context is preserved. The generated session ends when the client is shut down or replaced; a later init() generates a new ID. It is not persisted across processes.

API reference

Span types

type= maps to gen_ai.operation.name:

Span fields (start/update/end)

input, output, model, provider, system_instructions, response_model, response_id, output_type, finish_reason, usage (dict with exactly input_tokens, output_tokens, total_tokens, cache_read_input_tokens, cache_creation_input_tokens, reasoning_output_tokens), cost_usd, temperature, top_p, top_k, max_tokens, stop_sequences, seed, frequency_penalty, presence_penalty, time_to_first_chunk_ms, tool_name, tool_call_id, tool_description, agent_name, agent_id, metadata (→ td.metadata.*, this span only), attributes (raw escape hatch, merged last), error. start_span additionally accepts parent (traceparent string, OTel Context, or SpanContext), start_time, and per-call capture_input / capture_output overrides; end() additionally accepts end_time.

init() options

Session roots share trace IDs from the API key and session ID. The hash matches the TypeScript SDK. The SDK uses the configured OTel sampling policy, not the synthetic parent's flags. For example, init(sampler=ParentBased(TraceIdRatioBased(0.1))) samples sessions with OTel's ratio sampler. These classes come from opentelemetry.sdk.trace.sampling. The built-in Python and TypeScript ratio samplers can select different sessions because the OTel algorithms differ.

Auto-metrics

Ended spans automatically record two histograms (DELTA temporality, exported every 60s):

• gen_ai.client.operation.duration (unit s) for chat, invoke_agent, embeddings, execute_tool
• gen_ai.client.token.usage (unit {token}, attribute gen_ai.token.type=input|output) for chat, invoke_agent, embeddings

Plain spans (function) record no metrics. Quiet intervals produce zero metric requests.

Serverless

Use export_mode="immediate" and/or call telemetry_dev.flush() before the runtime freezes:

telemetry_dev.init(export_mode="immediate")
...
telemetry_dev.flush()  # force-flush traces + logs + metrics

Bring your own OTel (telemetry_dev.otel)

If you already run an OpenTelemetry SDK, attach the telemetry.dev processor to your provider instead of calling init():

from telemetry_dev.otel import TelemetrySpanProcessor

your_tracer_provider.add_span_processor(TelemetrySpanProcessor())  # reads TELEMETRY_DEV_API_KEY

If you need to wire your own span processor stack, create the telemetry.dev exporter directly:

from opentelemetry.sdk.trace.export import BatchSpanProcessor
from telemetry_dev.otel import create_telemetry_span_exporter

span_exporter = create_telemetry_span_exporter()
your_tracer_provider.add_span_processor(BatchSpanProcessor(span_exporter))

TelemetrySpanProcessor remains available from the package root for compatibility:

from telemetry_dev import TelemetrySpanProcessor

Without an API key and without span_exporter, TelemetrySpanProcessor() is an inert no-op: safe to attach unconditionally, with only a debug log. Auto-metrics are on by default for exported GenAI spans, use the service_name / environment resource settings above, and are skipped without an API key.

Limitations

• register_global=True cannot be undone on shutdown(): OpenTelemetry Python has no public API to unregister a global TracerProvider, so a later init(register_global=True) in the same process cannot reclaim the global slot. Prefer the isolated default (or the BYO processor) for processes that re-initialize.

Development

Uses uv:

uv sync                 # install (writes uv.lock)
uv run pytest           # tests
uv run ruff format .    # format
uv run ruff check .     # lint
uv run pyright          # type-check
uv build                # build wheel + sdist

examples/quickstart.py is runnable against a real ingest: TELEMETRY_DEV_API_KEY=td_live_... uv run examples/quickstart.py.