telemetry-dev 0.1.0__py3-none-any.whl

telemetry_dev/_metrics.py

@@ -0,0 +1,120 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter
+from opentelemetry.metrics import Meter
+from opentelemetry.sdk.metrics.export import MetricExportResult, MetricsData
+from opentelemetry.sdk.trace import ReadableSpan
+
+from ._config import report_error
+from ._semconv import (
+    ATTR_ERROR_TYPE,
+    DURATION_BUCKETS,
+    DURATION_METRIC_OPERATIONS,
+    METRIC_ATTR_KEYS,
+    TOKEN_BUCKETS,
+    TOKEN_METRIC_OPERATIONS,
+    USAGE_ATTRS,
+)
+
+_INPUT_TOKENS_ATTR = USAGE_ATTRS["input_tokens"]
+_OUTPUT_TOKENS_ATTR = USAGE_ATTRS["output_tokens"]
+
+
+def _has_data_points(metrics_data: MetricsData) -> bool:
+    for resource_metrics in metrics_data.resource_metrics:
+        for scope_metrics in resource_metrics.scope_metrics:
+            for metric in scope_metrics.metrics:
+                if len(metric.data.data_points) > 0:
+                    return True
+    return False
+
+
+class GuardedOTLPMetricExporter(OTLPMetricExporter):
+    """OTLP metric exporter that skips POSTs for collections with zero data points
+    (mirrors the TS emitter's empty-datapoint guard) and surfaces failures to on_error."""
+
+    def __init__(
+        self,
+        *args: Any,
+        on_error: Callable[[BaseException], None] | None = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(*args, **kwargs)  # pyright: ignore[reportUnknownMemberType]
+        self._td_on_error = on_error
+
+    def export(
+        self,
+        metrics_data: MetricsData,
+        timeout_millis: float | None = 10_000,
+        **kwargs: Any,
+    ) -> MetricExportResult:
+        if not _has_data_points(metrics_data):
+            return MetricExportResult.SUCCESS
+        try:
+            result = super().export(  # pyright: ignore[reportUnknownMemberType]
+                metrics_data, timeout_millis=timeout_millis, **kwargs
+            )
+        except BaseException as exc:
+            report_error(self._td_on_error, "metric export failed", exc)
+            return MetricExportResult.FAILURE
+        if result is MetricExportResult.FAILURE:
+            report_error(
+                self._td_on_error,
+                "metric export failed",
+                RuntimeError("OTLP metric export failed (check the API key and ingest URL)"),
+            )
+        return result
+
+
+class MetricsRecorder:
+    """Records the auto GenAI histograms from ended spans (called by the span processor)."""
+
+    def __init__(
+        self,
+        meter: Meter,
+        *,
+        on_error: Callable[[BaseException], None] | None = None,
+    ) -> None:
+        self._on_error = on_error
+        self._duration = meter.create_histogram(
+            "gen_ai.client.operation.duration",
+            unit="s",
+            description="Duration of GenAI client operations",
+            explicit_bucket_boundaries_advisory=DURATION_BUCKETS,
+        )
+        self._tokens = meter.create_histogram(
+            "gen_ai.client.token.usage",
+            unit="{token}",
+            description="Number of input and output tokens used by GenAI clients",
+            explicit_bucket_boundaries_advisory=TOKEN_BUCKETS,
+        )
+
+    def record_span(self, span: ReadableSpan) -> None:
+        try:
+            attributes = span.attributes or {}
+            operation = attributes.get("gen_ai.operation.name")
+            if not isinstance(operation, str) or operation not in DURATION_METRIC_OPERATIONS:
+                return
+            metric_attrs = {key: attributes[key] for key in METRIC_ATTR_KEYS if key in attributes}
+            if span.end_time is not None and span.start_time is not None:
+                duration_s = max(span.end_time - span.start_time, 0) / 1e9
+                error_type = attributes.get(ATTR_ERROR_TYPE)
+                duration_attrs = (
+                    {**metric_attrs, ATTR_ERROR_TYPE: error_type}
+                    if isinstance(error_type, str)
+                    else metric_attrs
+                )
+                self._duration.record(duration_s, duration_attrs)
+            if operation not in TOKEN_METRIC_OPERATIONS:
+                return
+            input_tokens = attributes.get(_INPUT_TOKENS_ATTR)
+            if isinstance(input_tokens, int):
+                self._tokens.record(input_tokens, {**metric_attrs, "gen_ai.token.type": "input"})
+            output_tokens = attributes.get(_OUTPUT_TOKENS_ATTR)
+            if isinstance(output_tokens, int):
+                self._tokens.record(output_tokens, {**metric_attrs, "gen_ai.token.type": "output"})
+        except BaseException as exc:
+            report_error(self._on_error, "failed to record auto-metrics for span", exc)

telemetry_dev/_observe.py

@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable, Mapping
+from typing import Any, TypeVar, overload
+
+from ._client import get_client
+from ._semconv import SpanType
+from ._serialize import AttributeValue
+from ._spans import start_span
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _bound_input(fn: Callable[..., Any], args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+    try:
+        bound = inspect.signature(fn).bind(*args, **kwargs)
+        arguments = dict(bound.arguments)
+        arguments.pop("self", None)
+        arguments.pop("cls", None)
+        return arguments
+    except BaseException:
+        return {"args": list(args), "kwargs": kwargs}
+
+
+@overload
+def observe(func: F) -> F: ...
+@overload
+def observe(
+    func: None = None,
+    *,
+    name: str | None = None,
+    type: SpanType = "span",
+    capture_input: bool | None = None,
+    capture_output: bool | None = None,
+    attributes: Mapping[str, AttributeValue] | None = None,
+) -> Callable[[F], F]: ...
+
+
+def observe(
+    func: F | None = None,
+    *,
+    name: str | None = None,
+    type: SpanType = "span",
+    capture_input: bool | None = None,
+    capture_output: bool | None = None,
+    attributes: Mapping[str, AttributeValue] | None = None,
+) -> F | Callable[[F], F]:
+    """Wrap a function in a span: arguments become `input` (param-name dict, self/cls dropped),
+    the return value becomes `output`, exceptions are captured and re-raised. Supports sync,
+    async, sync-generator, and async-generator functions; activates the span context for
+    sync/async functions."""
+
+    def decorate(fn: F) -> F:
+        span_name = name or getattr(fn, "__qualname__", None) or getattr(fn, "__name__", "observe")
+
+        def open_span(args: tuple[Any, ...], kwargs: dict[str, Any]) -> Any:
+            return start_span(
+                span_name,
+                type=type,
+                input=_bound_input(fn, args, kwargs),
+                attributes=attributes,
+                capture_input=capture_input,
+                capture_output=capture_output,
+            )
+
+        if inspect.iscoroutinefunction(fn):
+
+            @functools.wraps(fn)
+            async def async_wrapper(*args: Any, **kwargs: Any) -> Any:
+                client = get_client()
+                if client is None or not client.enabled:
+                    return await fn(*args, **kwargs)
+                with open_span(args, kwargs) as handle:
+                    result = await fn(*args, **kwargs)
+                    handle.update(output=result)
+                    return result
+
+            return async_wrapper  # type: ignore[return-value]
+
+        if inspect.isasyncgenfunction(fn):
+
+            @functools.wraps(fn)
+            async def async_gen_wrapper(*args: Any, **kwargs: Any) -> Any:
+                client = get_client()
+                if client is None or not client.enabled:
+                    async for item in fn(*args, **kwargs):
+                        yield item
+                    return
+                handle = open_span(args, kwargs)
+                try:
+                    async for item in fn(*args, **kwargs):
+                        yield item
+                except GeneratorExit:
+                    handle.end()
+                    raise
+                except BaseException as exc:
+                    handle.end(error=exc)
+                    raise
+                else:
+                    handle.end()
+
+            return async_gen_wrapper  # type: ignore[return-value]
+
+        if inspect.isgeneratorfunction(fn):
+
+            @functools.wraps(fn)
+            def gen_wrapper(*args: Any, **kwargs: Any) -> Any:
+                client = get_client()
+                if client is None or not client.enabled:
+                    yield from fn(*args, **kwargs)
+                    return
+                handle = open_span(args, kwargs)
+                try:
+                    yield from fn(*args, **kwargs)
+                except GeneratorExit:
+                    handle.end()
+                    raise
+                except BaseException as exc:
+                    handle.end(error=exc)
+                    raise
+                else:
+                    handle.end()
+
+            return gen_wrapper  # type: ignore[return-value]
+
+        @functools.wraps(fn)
+        def sync_wrapper(*args: Any, **kwargs: Any) -> Any:
+            client = get_client()
+            if client is None or not client.enabled:
+                return fn(*args, **kwargs)
+            with open_span(args, kwargs) as handle:
+                result = fn(*args, **kwargs)
+                handle.update(output=result)
+                return result
+
+        return sync_wrapper  # type: ignore[return-value]
+
+    if func is not None:
+        return decorate(func)
+    return decorate

telemetry_dev/_processor.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Literal
+
+from opentelemetry.context import Context
+from opentelemetry.sdk.trace import ReadableSpan, Span, SpanProcessor
+from opentelemetry.sdk.trace.export import (
+    BatchSpanProcessor,
+    SimpleSpanProcessor,
+    SpanExporter,
+)
+
+from ._config import report_error
+from ._context import propagated_attributes
+from ._metrics import MetricsRecorder
+
+ExportMode = Literal["batched", "immediate"]
+
+
+class StampingSpanProcessor(SpanProcessor):
+    """Stamps propagated attributes, filters spans, records metrics, then exports."""
+
+    def __init__(
+        self,
+        span_exporter: SpanExporter,
+        *,
+        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_recorder: MetricsRecorder | None = None,
+        on_error: Callable[[BaseException], None] | None = None,
+    ) -> None:
+        self._span_filter = span_filter
+        self._metrics_recorder = metrics_recorder
+        self._on_error = on_error
+        if export_mode == "immediate":
+            self._inner: SpanProcessor = SimpleSpanProcessor(span_exporter)
+        else:
+            self._inner = BatchSpanProcessor(
+                span_exporter,
+                max_queue_size=max_queue_size,
+                schedule_delay_millis=schedule_delay_millis,
+                max_export_batch_size=max_export_batch_size,
+                export_timeout_millis=export_timeout_millis,
+            )
+
+    def on_start(self, span: Span, parent_context: Context | None = None) -> None:
+        try:
+            attrs = propagated_attributes(parent_context)
+            if attrs:
+                span.set_attributes(attrs)
+        except BaseException as exc:
+            report_error(self._on_error, "failed to stamp propagated attributes", exc)
+        self._inner.on_start(span, parent_context)
+
+    def on_end(self, span: ReadableSpan) -> None:
+        if self._span_filter is not None:
+            try:
+                if not self._span_filter(span):
+                    return
+            except BaseException as exc:
+                # Fail open: a broken filter must not drop telemetry.
+                report_error(self._on_error, "span_filter raised; exporting span anyway", exc)
+        # Metrics are recorded only for exported spans (after the filter), matching the TS SDK.
+        if self._metrics_recorder is not None:
+            self._metrics_recorder.record_span(span)
+        self._inner.on_end(span)
+
+    def shutdown(self) -> None:
+        self._inner.shutdown()
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return self._inner.force_flush(timeout_millis)

telemetry_dev/_semconv.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+from typing import Literal
+
+SCOPE_NAME = "telemetry_dev"
+
+SpanType = Literal["span", "generation", "tool", "agent", "embedding"]
+LogLevel = Literal["debug", "info", "warn", "warning", "error"]
+
+# Plain spans ALWAYS map to "function" — an operation-less span carrying a propagated
+# gen_ai.conversation.id would otherwise be classified as "llm" by the ingest heuristic.
+SPAN_TYPE_TO_OPERATION: dict[str, str] = {
+    "span": "function",
+    "generation": "chat",
+    "tool": "execute_tool",
+    "agent": "invoke_agent",
+    "embedding": "embeddings",
+}
+
+DURATION_METRIC_OPERATIONS = frozenset({"chat", "invoke_agent", "embeddings", "execute_tool"})
+TOKEN_METRIC_OPERATIONS = frozenset({"chat", "invoke_agent", "embeddings"})
+
+# Buckets verbatim from packages/ai/src/otel.ts (OTel GenAI semconv recommendations).
+DURATION_BUCKETS = [
+    0.01,
+    0.02,
+    0.04,
+    0.08,
+    0.16,
+    0.32,
+    0.64,
+    1.28,
+    2.56,
+    5.12,
+    10.24,
+    20.48,
+    40.96,
+    81.92,
+]
+TOKEN_BUCKETS = [
+    1,
+    4,
+    16,
+    64,
+    256,
+    1024,
+    4096,
+    16384,
+    65536,
+    262144,
+    1048576,
+    4194304,
+    16777216,
+    67108864,
+]
+
+SEVERITY: dict[str, int] = {"debug": 5, "info": 9, "warn": 13, "error": 17}
+
+RESERVED_METADATA_KEYS = frozenset({"userId", "sessionId", "user_id", "session_id"})
+
+ATTR_OPERATION = "gen_ai.operation.name"
+ATTR_PROVIDER = "gen_ai.provider.name"
+ATTR_REQUEST_MODEL = "gen_ai.request.model"
+ATTR_RESPONSE_MODEL = "gen_ai.response.model"
+ATTR_RESPONSE_ID = "gen_ai.response.id"
+ATTR_OUTPUT_TYPE = "gen_ai.output.type"
+ATTR_FINISH_REASONS = "gen_ai.response.finish_reasons"
+ATTR_SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions"
+ATTR_INPUT_MESSAGES = "gen_ai.input.messages"
+ATTR_OUTPUT_MESSAGES = "gen_ai.output.messages"
+ATTR_TOOL_NAME = "gen_ai.tool.name"
+ATTR_TOOL_CALL_ID = "gen_ai.tool.call.id"
+ATTR_TOOL_DESCRIPTION = "gen_ai.tool.description"
+ATTR_TOOL_ARGUMENTS = "gen_ai.tool.call.arguments"
+ATTR_TOOL_RESULT = "gen_ai.tool.call.result"
+ATTR_AGENT_NAME = "gen_ai.agent.name"
+ATTR_AGENT_ID = "gen_ai.agent.id"
+ATTR_COST = "gen_ai.usage.cost"
+ATTR_USER_ID = "user.id"
+ATTR_SESSION_ID = "gen_ai.conversation.id"
+ATTR_ERROR_TYPE = "error.type"
+# Emitted in SECONDS — the ingest multiplies non-"ms" duration keys by 1000.
+ATTR_TIME_TO_FIRST_CHUNK = "gen_ai.response.time_to_first_chunk"
+
+METADATA_PREFIX = "td.metadata."
+
+USAGE_ATTRS: dict[str, str] = {
+    "input_tokens": "gen_ai.usage.input_tokens",
+    "output_tokens": "gen_ai.usage.output_tokens",
+    "total_tokens": "gen_ai.usage.total_tokens",
+    "cache_read_input_tokens": "gen_ai.usage.cache_read.input_tokens",
+    "cache_creation_input_tokens": "gen_ai.usage.cache_creation.input_tokens",
+    "reasoning_output_tokens": "gen_ai.usage.reasoning.output_tokens",
+}
+
+SAMPLING_ATTRS: dict[str, str] = {
+    "temperature": "gen_ai.request.temperature",
+    "top_p": "gen_ai.request.top_p",
+    "top_k": "gen_ai.request.top_k",
+    "max_tokens": "gen_ai.request.max_tokens",
+    "stop_sequences": "gen_ai.request.stop_sequences",
+    "seed": "gen_ai.request.seed",
+    "frequency_penalty": "gen_ai.request.frequency_penalty",
+    "presence_penalty": "gen_ai.request.presence_penalty",
+}
+
+METRIC_ATTR_KEYS = (ATTR_OPERATION, ATTR_PROVIDER, ATTR_REQUEST_MODEL, ATTR_RESPONSE_MODEL)
+
+
+def input_key(operation: str) -> str:
+    return ATTR_TOOL_ARGUMENTS if operation == "execute_tool" else ATTR_INPUT_MESSAGES
+
+
+def output_key(operation: str) -> str:
+    return ATTR_TOOL_RESULT if operation == "execute_tool" else ATTR_OUTPUT_MESSAGES

telemetry_dev/_serialize.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from typing import Any, cast
+
+from ._config import report_error
+
+TRUNCATION_MARKER = "...[truncated]"
+DEFAULT_MAX_ATTRIBUTE_LENGTH = 65536
+
+AttributeValue = (
+    str | bool | int | float | Sequence[str] | Sequence[bool] | Sequence[int] | Sequence[float]
+)
+
+
+@dataclass(frozen=True)
+class MaskContext:
+    key: str
+
+
+Mask = Callable[[Any, MaskContext], Any]
+
+
+def truncate(text: str, max_len: int) -> str:
+    # The cap counts UTF-16 code units (JavaScript's String.length) so both SDKs truncate
+    # identical payloads at the same point; a slice landing mid-surrogate-pair backs off one unit.
+    if len(text) * 2 <= max_len:
+        return text
+    encoded = text.encode("utf-16-le")
+    if len(encoded) <= max_len * 2:
+        return text
+    # Total stays within max_len so the provider's attribute_value_length_limit backstop,
+    # set to the same cap, never slices the marker off.
+    head = encoded[: max(max_len - len(TRUNCATION_MARKER), 0) * 2]
+    try:
+        return head.decode("utf-16-le") + TRUNCATION_MARKER
+    except UnicodeDecodeError:
+        return head[:-2].decode("utf-16-le") + TRUNCATION_MARKER
+
+
+def stringify(value: Any) -> str:
+    if isinstance(value, str):
+        return value
+    return json.dumps(value, default=repr, ensure_ascii=False)
+
+
+def serialize_content(
+    value: Any,
+    *,
+    key: str,
+    mask: Mask | None,
+    max_len: int,
+    on_error: Callable[[BaseException], None] | None = None,
+) -> str | None:
+    """The single content funnel: mask -> JSON stringify -> truncate.
+
+    Returns None (content dropped, matching the TypeScript SDK) when the mask hook raises
+    or the value cannot be stringified.
+    """
+    if mask is not None:
+        try:
+            value = mask(value, MaskContext(key=key))
+        except BaseException as exc:
+            report_error(on_error, f"mask hook raised for attribute '{key}'", exc)
+            return None
+    try:
+        text = stringify(value)
+    except BaseException as exc:
+        report_error(on_error, f"failed to serialize attribute '{key}'", exc)
+        return None
+    return truncate(text, max_len)
+
+
+def coerce_attr_value(
+    value: Any,
+    *,
+    max_len: int = DEFAULT_MAX_ATTRIBUTE_LENGTH,
+    key: str | None = None,
+    on_error: Callable[[BaseException], None] | None = None,
+) -> AttributeValue | None:
+    """Pass scalars and homogeneous scalar sequences through; JSON-stringify everything else."""
+    try:
+        if isinstance(value, bool | int | float):
+            return value
+        if isinstance(value, str):
+            return truncate(value, max_len)
+        if isinstance(value, Sequence) and not isinstance(value, Mapping):
+            items: list[Any] = list(cast("Sequence[Any]", value))
+            if items and all(isinstance(item, str) for item in items):
+                return [truncate(item, max_len) for item in items]
+            if items and all(isinstance(item, bool) for item in items):
+                return items
+            if items and all(
+                isinstance(item, int | float) and not isinstance(item, bool) for item in items
+            ):
+                return items
+        return truncate(stringify(value), max_len)
+    except BaseException as exc:
+        suffix = f" '{key}'" if key is not None else ""
+        report_error(on_error, f"failed to serialize attribute{suffix}", exc)
+        return None