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.

Docs: https://telemetry.dev/docs/sdk/python

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

record_output_chunk() measures intervals at the point the consumer pulls each chunk. If a consumer waits between pulls, that delay is included and cannot be separated from provider latency. The exact gen_ai.client.operation.time_per_output_chunk histogram is supported by the built-in OTLP metric exporter. OpenTelemetry Python does not expose an aggregate-input API for arbitrary metric readers, so supplying metric_reader= disables this histogram. Duration, token usage, and time-to-first-chunk metrics remain available; the first accepted streamed span with two or more recorded chunks reports this limitation once through on_error and the SDK logger.

Provider integrations feature-detect record_output_chunk. Older core SDKs without that method continue delivering streams and tracing normally, but do not emit chunk-interval metrics. Upgrade the core SDK with provider integrations to enable the new metric.

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 input_tokens, output_tokens, total_tokens, cache_read_input_tokens, cache_creation_input_tokens, reasoning_output_tokens, text_input_tokens, text_output_tokens, image_input_tokens, image_output_tokens, audio_input_tokens, audio_output_tokens, text_cache_read_input_tokens, image_cache_read_input_tokens, and audio_cache_read_input_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

capture_input=False and capture_output=False omit captured content. Provider integrations may still record non-content metadata such as response IDs and models, finish reasons, usage, timing, and errors. Capture flags do not gate stop sequences, tool descriptions and definitions (gen_ai.tool.description, gen_ai.tool.definitions), caller-supplied metadata or raw attributes, or exception messages and stack traces; redact those separately when needed.

mask receives input and output content, system instructions, log messages, and content that integrations pass to SpanHandle.serialize_content. MaskContext.key names the attribute being written. It does not receive span or propagated metadata, raw attributes, log attributes, or exception messages and stack traces; redact those separately.

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 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
• gen_ai.client.operation.time_to_first_chunk (unit s) for chat when a finite, non-negative first-chunk timing is available.
• gen_ai.client.operation.time_per_output_chunk (unit s) for chat with two or more recorded output chunks, using the built-in OTLP exporter. Filtering applies before either streaming metric is emitted, including streams interrupted after receiving output.

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.

Native Claude SDK spans

The Python anthropic SDK 1.14.0 and later emits OpenTelemetry spans natively. The Claude SDK uses the global tracer provider of the application. To send these spans to telemetry.dev, register a global tracer provider with TelemetrySpanProcessor:

pip install telemetry-dev "anthropic>=1.14.0"

from anthropic import Anthropic
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from telemetry_dev.otel import TelemetrySpanProcessor

provider = TracerProvider()
provider.add_span_processor(TelemetrySpanProcessor())
trace.set_tracer_provider(provider)

client = Anthropic()
client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=256,
    messages=[{"role": "user", "content": "Say hello."}],
)

provider.shutdown()

If you use telemetry_dev.init(register_global=True), also pass span_filter=lambda span: True. The default filter of that mode exports only the spans of this SDK.

By default, the spans contain metadata only. To also send prompts and responses, set ANTHROPIC_OPEN_TELEMETRY_TRACES_CONTENT_MODE=content. The client reads this variable one time, when you make the client.

Do not use the native spans and telemetry-dev-anthropic together. If you use the two, each request has two spans.

You can also send the native spans without this package. Use an OTLP/HTTP protobuf exporter:

pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http

import os

from opentelemetry import trace
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor

exporter = OTLPSpanExporter(
    endpoint="https://ingest.telemetry.dev/v1/traces",
    headers={"Authorization": f"Bearer {os.environ['TELEMETRY_DEV_API_KEY']}"},
)
provider = TracerProvider()
provider.add_span_processor(BatchSpanProcessor(exporter))
trace.set_tracer_provider(provider)

The Claude API can also send server-side spans to telemetry.dev through a Console destination. Set the endpoint to https://ingest.telemetry.dev. Set the Authorization header to Bearer <telemetry.dev API key>. For more information, refer to Claude Platform.

When the SDK and the Claude API send the spans of a request to the same telemetry.dev project, telemetry.dev counts the tokens of the request one time, from the API span. The SDK span stays in the trace with no tokens. telemetry.dev matches the two spans by the request ID or the response ID, so the API span does not have to be a child of the SDK span. If the Console destination uses an API key that is scoped to one environment, its API spans take over only the SDK spans of that environment.

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.

License

MIT. See LICENSE.