telemetry-dev 0.1.0__py3-none-any.whl

telemetry_dev/otel.py

@@ -0,0 +1,186 @@
+"""Bring-your-own-OpenTelemetry surface for telemetry.dev.
+
+Attach ``TelemetrySpanProcessor`` to your own ``TracerProvider`` (OTel SDK,
+opentelemetry-distro, ...) to ship its spans to telemetry.dev without calling
+``telemetry_dev.init()``.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+
+from opentelemetry.context import Context
+from opentelemetry.exporter.otlp.proto.http import Compression
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.metrics import Histogram, MeterProvider
+from opentelemetry.sdk.metrics.export import (
+    AggregationTemporality,
+    PeriodicExportingMetricReader,
+)
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+
+from ._config import SDK_VERSION, logger, report_error, resolve_config
+from ._metrics import GuardedOTLPMetricExporter, MetricsRecorder
+from ._processor import ExportMode, StampingSpanProcessor
+from ._semconv import SCOPE_NAME
+
+__all__ = ["ExportMode", "TelemetrySpanProcessor", "create_telemetry_span_exporter"]
+
+_EXPORTER_TIMEOUT_S = 10.0
+_BATCHED_METRIC_INTERVAL_MILLIS = 60_000
+_DORMANT_METRIC_INTERVAL_MILLIS = 2**31 - 1
+
+
+class _NoOpSpanExporter(SpanExporter):
+    def export(self, spans: Sequence[ReadableSpan]) -> SpanExportResult:
+        return SpanExportResult.SUCCESS
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
+def create_telemetry_span_exporter(
+    *,
+    api_key: str | None = None,
+    base_url: str | None = None,
+    timeout: float = _EXPORTER_TIMEOUT_S,
+) -> SpanExporter:
+    """Build a telemetry.dev OTLP span exporter, or a no-op exporter without an API key."""
+    config = resolve_config(api_key=api_key, base_url=base_url)
+    if config.api_key is None:
+        logger.debug(
+            "telemetry-dev: no API key (api_key option or TELEMETRY_DEV_API_KEY); "
+            "span exporter is a no-op"
+        )
+        return _NoOpSpanExporter()
+    return OTLPSpanExporter(
+        endpoint=f"{config.base_url}/v1/traces",
+        headers={"Authorization": f"Bearer {config.api_key}"},
+        compression=Compression.Gzip,
+        timeout=timeout,
+    )
+
+
+class TelemetrySpanProcessor(SpanProcessor):
+    """Span processor for BYO OpenTelemetry SDK setups.
+
+    Builds telemetry.dev exporters when an API key is configured; otherwise no-ops unless
+    ``span_exporter`` is supplied.
+    """
+
+    def __init__(
+        self,
+        span_exporter: SpanExporter | None = None,
+        *,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        export_mode: ExportMode = "batched",
+        max_export_batch_size: int = 64,
+        schedule_delay_millis: float = 1000,
+        max_queue_size: int = 2048,
+        export_timeout_millis: float = 30000,
+        span_filter: Callable[[ReadableSpan], bool] | None = None,
+        metrics: bool = True,
+        service_name: str | None = None,
+        environment: str | None = None,
+        metrics_recorder: MetricsRecorder | None = None,
+        on_error: Callable[[BaseException], None] | None = None,
+    ) -> None:
+        self._inner: StampingSpanProcessor | None = None
+        self._meter_provider: MeterProvider | None = None
+        self._on_error = on_error
+        config = resolve_config(
+            api_key=api_key,
+            base_url=base_url,
+            environment=environment,
+            service_name=service_name,
+        )
+
+        if span_exporter is None:
+            span_exporter = create_telemetry_span_exporter(
+                api_key=config.api_key,
+                base_url=config.base_url,
+            )
+            if isinstance(span_exporter, _NoOpSpanExporter):
+                return
+
+        if metrics_recorder is None and metrics and config.api_key is not None:
+            resource = Resource.create(
+                {
+                    "service.name": config.service_name,
+                    "deployment.environment.name": config.environment,
+                }
+            )
+            metric_exporter = GuardedOTLPMetricExporter(
+                endpoint=f"{config.base_url}/v1/metrics",
+                headers={"Authorization": f"Bearer {config.api_key}"},
+                compression=Compression.Gzip,
+                timeout=_EXPORTER_TIMEOUT_S,
+                preferred_temporality={Histogram: AggregationTemporality.DELTA},
+            )
+            reader = PeriodicExportingMetricReader(
+                metric_exporter,
+                export_interval_millis=(
+                    _BATCHED_METRIC_INTERVAL_MILLIS
+                    if export_mode == "batched"
+                    else _DORMANT_METRIC_INTERVAL_MILLIS
+                ),
+            )
+            self._meter_provider = MeterProvider(
+                metric_readers=[reader], resource=resource, shutdown_on_exit=False
+            )
+            meter = self._meter_provider.get_meter(SCOPE_NAME, SDK_VERSION)
+            metrics_recorder = MetricsRecorder(meter, on_error=on_error)
+
+        self._inner = StampingSpanProcessor(
+            span_exporter,
+            export_mode=export_mode,
+            max_export_batch_size=max_export_batch_size,
+            schedule_delay_millis=schedule_delay_millis,
+            max_queue_size=max_queue_size,
+            export_timeout_millis=export_timeout_millis,
+            span_filter=span_filter,
+            metrics_recorder=metrics_recorder,
+            on_error=on_error,
+        )
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        if self._inner is not None:
+            self._inner.on_start(span, parent_context)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        if self._inner is not None:
+            self._inner.on_end(span)
+
+    def shutdown(self) -> None:
+        if self._inner is not None:
+            try:
+                self._inner.shutdown()
+            except BaseException as exc:
+                report_error(self._on_error, "span processor shutdown failed", exc)
+        if self._meter_provider is not None:
+            try:
+                self._meter_provider.shutdown(timeout_millis=30_000)
+            except BaseException as exc:
+                report_error(self._on_error, "metric provider shutdown failed", exc)
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        ok = True
+        if self._inner is not None:
+            try:
+                ok = self._inner.force_flush(timeout_millis)
+            except BaseException as exc:
+                report_error(self._on_error, "span processor force_flush failed", exc)
+                ok = False
+        if self._meter_provider is not None:
+            try:
+                ok = self._meter_provider.force_flush(timeout_millis=timeout_millis) and ok
+            except BaseException as exc:
+                report_error(self._on_error, "metric provider force_flush failed", exc)
+                ok = False
+        return ok

telemetry_dev-0.1.0.dist-info/METADATA

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: telemetry-dev
+Version: 0.1.0
+Summary: telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics
+Keywords: telemetry,opentelemetry,llm,genai,tracing,observability
+Author: telemetry.dev
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Dist: opentelemetry-api>=1.35.0,<2
+Requires-Dist: opentelemetry-sdk>=1.35.0,<2
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.35.0,<2
+Requires-Python: >=3.10
+Project-URL: Homepage, https://telemetry.dev
+Project-URL: Repository, https://github.com/telemetry-dev/telemetry.dev
+Description-Content-Type: text/markdown
+
+# 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
+
+```sh
+pip install telemetry-dev
+# or
+uv add telemetry-dev
+```
+
+Requires Python >= 3.10.
+
+## Quickstart
+
+```python
+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
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `TELEMETRY_DEV_API_KEY` | — | Ingest key (`td_live_...`). Absent = SDK is a no-op. |
+| `TELEMETRY_DEV_BASE_URL` | `https://ingest.telemetry.dev` | Ingest base URL (trailing slashes stripped). |
+| `TELEMETRY_DEV_ENVIRONMENT` | `production` | Deployment environment label. |
+| `OTEL_SERVICE_NAME` | `unknown_service` | Service name on every trace. |
+
+Explicit `init()` arguments take precedence over environment variables.
+
+## API reference
+
+| Name | Description |
+| --- | --- |
+| `init(**options) -> Client` | Initialize the SDK (see options below). Calling again replaces the previous client. |
+| `@observe` / `@observe(name=, type=, capture_input=, capture_output=, attributes=)` | Wrap a sync/async function (or generator) in a span. Arguments become `input` (param-name dict, `self`/`cls` dropped), the return value becomes `output`, exceptions are captured and re-raised. |
+| `start_span(name, *, type="span", ...) -> SpanHandle` | Start a span. `with` activates it in the current context; without `with` it is a detached handle you must `.end()`. |
+| `SpanHandle.update(**fields)` / `.end(**fields, end_time=)` / `.traceparent()` | Update attributes, end (accepts the full update field set), or read the W3C traceparent. |
+| `update_current_span(**fields)` | Apply the update field set to the currently active span (no-op without one). |
+| `propagate_attributes(*, user_id=, session_id=, metadata=)` | Context manager stamping `user.id` / `gen_ai.conversation.id` / `td.metadata.*` on every span and log record started inside (threads/asyncio included via contextvars). |
+| `log(message, *, level="info", event_name=None, attributes=None)` | Emit an OTLP log record to `/v1/logs`, correlated with the current trace. Levels: `debug`/`info`/`warn`/`error` (`"warning"` is accepted as an alias of `warn`). |
+| `get_traceparent() -> str \| None` | W3C traceparent of the current context. |
+| `flush(timeout_s=10.0)` / `shutdown(timeout_s=10.0)` | Force-flush / tear down traces + logs + metrics. Shutdown also runs atexit unless `disable_atexit=True`. |
+| `TelemetrySpanProcessor` / `telemetry_dev.otel.create_telemetry_span_exporter` | Bring-your-own-OTel helpers (below). |
+| `MaskContext`, `Usage`, `SpanHandle`, `Client`, `NOT_GIVEN` | Supporting types. |
+
+### Span types
+
+`type=` maps to `gen_ai.operation.name`:
+
+| `type` | operation | input / output attributes |
+| --- | --- | --- |
+| `"span"` (default) | `function` | `gen_ai.input.messages` / `gen_ai.output.messages` |
+| `"generation"` | `chat` | `gen_ai.input.messages` / `gen_ai.output.messages` |
+| `"tool"` | `execute_tool` | `gen_ai.tool.call.arguments` / `gen_ai.tool.call.result` |
+| `"agent"` | `invoke_agent` | `gen_ai.input.messages` / `gen_ai.output.messages` |
+| `"embedding"` | `embeddings` | `gen_ai.input.messages` / `gen_ai.output.messages` |
+
+### 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
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `api_key`, `base_url`, `environment`, `service_name` | env vars | Connection + resource settings. |
+| `enabled` | `True` | `False` = hard kill switch (tests). |
+| `register_global` | `False` | Also register the tracer provider globally. Applies a default export filter (only `telemetry_dev`-scoped spans are exported); pass `span_filter=lambda s: True` to export everything. |
+| `export_mode` | `"batched"` | `"immediate"` exports synchronously per span/log (serverless). |
+| `log_level` | `"warn"` | SDK diagnostics level: `debug`/`info`/`warn`/`error`/`silent`. |
+| `capture_input`, `capture_output` | `True` | Global content-capture defaults. |
+| `mask` | `None` | `Callable[[Any, MaskContext], Any]` redaction hook, runs before JSON serialization on input/output/log messages (`MaskContext.key` is the attribute being written). Not applied to correlation identifiers. |
+| `max_attribute_length` | `65536` | Per-content-attribute cap; truncated values get an ASCII `...[truncated]` marker appended. |
+| `span_filter` | `None` | Export predicate `Callable[[ReadableSpan], bool]`. |
+| `on_error` | `None` | Receives every internal SDK error; the SDK never raises. |
+| `disable_atexit` | `False` | Skip the automatic atexit shutdown. |
+| `timeout` | `10.0` | OTLP HTTP timeout in seconds. |
+| `span_exporter`, `log_exporter`, `metric_reader` | `None` | Test seams / offline mode; any of them enables the client without an API key. |
+
+## 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:
+
+```python
+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()`:
+
+```python
+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:
+
+```python
+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:
+
+```python
+from telemetry_dev import TelemetrySpanProcessor
+```
+
+| Option | Default | Purpose |
+| --- | --- | --- |
+| `api_key` | `TELEMETRY_DEV_API_KEY` | Ingest key. Absent with no `span_exporter` = inert no-op. |
+| `base_url` | `TELEMETRY_DEV_BASE_URL` or `https://ingest.telemetry.dev` | Ingest base URL; trailing slashes are stripped. |
+| `export_mode` | `"batched"` | `"batched"` or `"immediate"` span export. |
+| `max_export_batch_size` | `64` | BatchSpanProcessor export batch size. |
+| `schedule_delay_millis` | `1000` | BatchSpanProcessor schedule delay. |
+| `max_queue_size` | `2048` | BatchSpanProcessor queue size. |
+| `export_timeout_millis` | `30000` | BatchSpanProcessor export timeout. |
+| `span_filter` | `None` | Export predicate `Callable[[ReadableSpan], bool]`; failures export the span. |
+| `metrics` | `True` | Auto-record GenAI duration/token histograms for exported spans when an API key is available. |
+| `service_name` | `OTEL_SERVICE_NAME` or `unknown_service` | `service.name` on the metrics resource. |
+| `environment` | `TELEMETRY_DEV_ENVIRONMENT` or `production` | `deployment.environment.name` on the metrics resource. |
+| `on_error` | `None` | Receives internal processor errors; errors are never raised into your code. |
+| `span_exporter` | `None` | Advanced/test seam replacing the telemetry.dev OTLP trace exporter. |
+
+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](https://docs.astral.sh/uv/):
+
+```sh
+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`.

telemetry_dev-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+telemetry_dev/__init__.py,sha256=JGFuWI0jUkefVN3rK9e3WP_NxvpcZnXkCTlqsmgfPls,1376
+telemetry_dev/_client.py,sha256=Af--G2mutbHlyiWnH_WuXmawlCVwm8E1AJzDuOAjJ3w,14317
+telemetry_dev/_config.py,sha256=sRpZ_teq80TjNtkwFrgipGGnyPFHZg6hrb634PZaLlw,2341
+telemetry_dev/_context.py,sha256=pqbWF9khWZMLc3UnEe1fl2O4I6TThAl_HoWgx1d0M4E,3595
+telemetry_dev/_logs.py,sha256=ZHGZ155l7iMEQwVziBFbp4Mu8k_dTte2sl5f8IQvQmY,2437
+telemetry_dev/_metrics.py,sha256=IBicRcLB4hUi0RGRaoNX88CHgBx-Dr6FCVK2reiVGwo,4713
+telemetry_dev/_observe.py,sha256=gN1P3EgcUeXvG-xZfE6BL78o42106CwqCHq2Ot9B6TM,4824
+telemetry_dev/_processor.py,sha256=yZpF7tONVLU7jDLOI-CFi8TGGo8y3A9oOeh2FPufDFU,2893
+telemetry_dev/_semconv.py,sha256=nEav6No-jkJbqKSmSvnoidzU47EIBH_nK28ZnBbuQbs,3576
+telemetry_dev/_serialize.py,sha256=wIUdzeqKrTcKv6c1nw86b9s_UNdJHOf7MmKJfIFP028,3504
+telemetry_dev/_spans.py,sha256=z2__yb9mZmz3ypPq1hUjariZGuC8oeJHuKC0mKrP2Fw,23079
+telemetry_dev/otel.py,sha256=nxFyDqboIYogwYxKSR_JVPrGfyr_6RfVXOfaWws6X6Q,7109
+telemetry_dev/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+telemetry_dev-0.1.0.dist-info/WHEEL,sha256=bu7Cckf7DKpj8ztfOQHBiWtXM4xigujiTkrhvV6U2aU,81
+telemetry_dev-0.1.0.dist-info/METADATA,sha256=oJ8jurkZjRClG0gnRJiclNp_1nmEYgDnH2Kzxy_aZcA,11585
+telemetry_dev-0.1.0.dist-info/RECORD,,

telemetry_dev-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.11.27
+Root-Is-Purelib: true
+Tag: py3-none-any