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.

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

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.