telemetry-dev 0.2.3__tar.gz → 0.2.4__tar.gz

{telemetry_dev-0.2.3 → telemetry_dev-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.3
+Version: 0.2.4
 Summary: telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics
 Keywords: telemetry,opentelemetry,llm,genai,tracing,observability
 Author: telemetry.dev
@@ -99,7 +99,7 @@ later `init()` generates a new ID. It is not persisted across processes.
 | `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. |
+| `SpanHandle.update(**fields)` / `.end(**fields, end_time=)` / `.record_output_chunk(timestamp_ms=None)` / `.traceparent()` | Update attributes, end, record arrival of a non-empty output chunk, 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`). |
@@ -108,6 +108,18 @@ later `init()` generates a new ID. It is not persisted across processes.
 | `TelemetrySpanProcessor` / `telemetry_dev.otel.create_telemetry_span_exporter` | Bring-your-own-OTel helpers (below). |
 | `MaskContext`, `Usage`, `SpanHandle`, `Client`, `NOT_GIVEN` | Supporting types. |
 
+`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`:
@@ -160,12 +172,17 @@ The built-in Python and TypeScript ratio samplers can select different sessions
 
 ## Auto-metrics
 
-Ended spans automatically record two histograms (DELTA temporality, exported every 60s):
+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.
 

{telemetry_dev-0.2.3 → telemetry_dev-0.2.4}/README.md

@@ -75,7 +75,7 @@ later `init()` generates a new ID. It is not persisted across processes.
 | `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. |
+| `SpanHandle.update(**fields)` / `.end(**fields, end_time=)` / `.record_output_chunk(timestamp_ms=None)` / `.traceparent()` | Update attributes, end, record arrival of a non-empty output chunk, 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`). |
@@ -84,6 +84,18 @@ later `init()` generates a new ID. It is not persisted across processes.
 | `TelemetrySpanProcessor` / `telemetry_dev.otel.create_telemetry_span_exporter` | Bring-your-own-OTel helpers (below). |
 | `MaskContext`, `Usage`, `SpanHandle`, `Client`, `NOT_GIVEN` | Supporting types. |
 
+`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`:
@@ -136,12 +148,17 @@ The built-in Python and TypeScript ratio samplers can select different sessions
 
 ## Auto-metrics
 
-Ended spans automatically record two histograms (DELTA temporality, exported every 60s):
+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.
 

{telemetry_dev-0.2.3 → telemetry_dev-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.3"
+version = "0.2.4"
 description = "telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics"
 readme = "README.md"
 license = "MIT"

{telemetry_dev-0.2.3 → telemetry_dev-0.2.4}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.3"
+version = "0.2.4"
 description = "telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics"
 readme = "README.md"
 license = "MIT"

{telemetry_dev-0.2.3 → telemetry_dev-0.2.4}/src/telemetry_dev/_client.py

@@ -41,7 +41,7 @@ from ._config import (
     resolve_config,
 )
 from ._context import SessionSampler
-from ._metrics import GuardedOTLPMetricExporter, MetricsRecorder
+from ._metrics import GuardedOTLPMetricExporter, MetricsRecorder, OutputChunkAggregation
 from ._processor import ExportMode, StampingSpanProcessor
 from ._semconv import SCOPE_NAME
 from ._serialize import Mask, serialize_content
@@ -160,6 +160,7 @@ class Client:
         self._tracer_provider: TracerProvider | None = None
         self._logger_provider: LoggerProvider | None = None
         self._meter_provider: MeterProvider | None = None
+        self._output_chunks: OutputChunkAggregation | None = None
 
         if not enabled:
             return
@@ -191,6 +192,7 @@ class Client:
         # Without an api key (enabled via a test seam), never construct real network
         # exporters — they would POST to the ingest with a bogus Authorization header.
         if metric_reader is None and config.api_key is not None:
+            self._output_chunks = OutputChunkAggregation()
             metric_exporter = GuardedOTLPMetricExporter(
                 endpoint=f"{config.base_url}/v1/metrics",
                 headers=headers,
@@ -199,6 +201,7 @@ class Client:
                 preferred_temporality={Histogram: AggregationTemporality.DELTA},
                 on_error=on_error,
             )
+            metric_exporter.output_chunks = self._output_chunks
             metric_reader = PeriodicExportingMetricReader(
                 metric_exporter, export_interval_millis=60_000
             )
@@ -208,7 +211,9 @@ class Client:
                 metric_readers=[metric_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)
+            metrics_recorder = MetricsRecorder(
+                meter, on_error=on_error, output_chunks=self._output_chunks
+            )
 
         if span_exporter is None:
             span_exporter = _ReportingSpanExporter(

telemetry_dev-0.2.4/src/telemetry_dev/_metrics.py

@@ -0,0 +1,280 @@
+from __future__ import annotations
+
+import math
+import threading
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+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 (
+    AggregationTemporality,
+    Histogram,
+    HistogramDataPoint,
+    Metric,
+    MetricExportResult,
+    MetricsData,
+    ResourceMetrics,
+    ScopeMetrics,
+)
+from opentelemetry.sdk.trace import ReadableSpan
+from opentelemetry.trace import INVALID_SPAN_CONTEXT, NonRecordingSpan, set_span_in_context
+
+from ._config import report_error
+from ._semconv import (
+    ATTR_ERROR_TYPE,
+    ATTR_TIME_TO_FIRST_CHUNK,
+    DURATION_BUCKETS,
+    DURATION_METRIC_OPERATIONS,
+    METRIC_ATTR_KEYS,
+    SCOPE_NAME,
+    TOKEN_BUCKETS,
+    TOKEN_METRIC_OPERATIONS,
+    USAGE_ATTRS,
+)
+
+_INPUT_TOKENS_ATTR = USAGE_ATTRS["input_tokens"]
+_OUTPUT_TOKENS_ATTR = USAGE_ATTRS["output_tokens"]
+_MAX_CHUNK_ATTRIBUTE_SETS = 2000
+_CHUNK_METRIC_NAME = "gen_ai.client.operation.time_per_output_chunk"
+
+
+@dataclass
+class _ChunkAggregate:
+    count: int
+    sum: float
+    min: float
+    max: float
+    buckets: list[int]
+
+
+class OutputChunkAggregation:
+    def __init__(self, max_attribute_sets: int = _MAX_CHUNK_ATTRIBUTE_SETS) -> None:
+        self._max_attribute_sets = max_attribute_sets
+        self._values: dict[tuple[tuple[str, Any], ...], _ChunkAggregate] = {}
+        self._lock = threading.Lock()
+        self._collection_start = time.time_ns()
+
+    def add(
+        self,
+        attributes: dict[str, Any],
+        aggregate: tuple[int, float, float, float, tuple[int, ...]],
+    ) -> None:
+        key = tuple(sorted(attributes.items()))
+        with self._lock:
+            if key not in self._values and len(self._values) >= self._max_attribute_sets - 1:
+                key = (("otel.metric.overflow", True),)
+            count, total, minimum, maximum, buckets = aggregate
+            existing = self._values.get(key)
+            if existing is None:
+                self._values[key] = _ChunkAggregate(count, total, minimum, maximum, list(buckets))
+                return
+            existing.count += count
+            existing.sum += total
+            existing.min = min(existing.min, minimum)
+            existing.max = max(existing.max, maximum)
+            for index, value in enumerate(buckets):
+                existing.buckets[index] += value
+
+    def drain_points(self) -> tuple[HistogramDataPoint, ...]:
+        with self._lock:
+            values, self._values = self._values, {}
+            now = time.time_ns()
+            start, self._collection_start = self._collection_start, now
+        return tuple(
+            HistogramDataPoint(
+                attributes=dict(key),
+                start_time_unix_nano=start,
+                time_unix_nano=now,
+                count=value.count,
+                sum=value.sum,
+                bucket_counts=tuple(value.buckets),
+                explicit_bounds=tuple(DURATION_BUCKETS),
+                min=value.min,
+                max=value.max,
+                exemplars=(),
+            )
+            for key, value in values.items()
+        )
+
+
+def _with_output_chunks(
+    metrics_data: MetricsData, aggregation: OutputChunkAggregation
+) -> MetricsData:
+    resource_metrics = list(metrics_data.resource_metrics)
+    target = next(
+        (
+            (resource_index, scope_index)
+            for resource_index, resource in enumerate(resource_metrics)
+            for scope_index, scope in enumerate(resource.scope_metrics)
+            if scope.scope.name == SCOPE_NAME
+        ),
+        None,
+    )
+    if target is None:
+        return metrics_data
+    points = aggregation.drain_points()
+    if not points:
+        return metrics_data
+    metric = Metric(
+        name=_CHUNK_METRIC_NAME,
+        description="Time between consecutive non-empty GenAI output chunks",
+        unit="s",
+        data=Histogram(points, AggregationTemporality.DELTA),
+    )
+    resource_index, scope_index = target
+    resource = resource_metrics[resource_index]
+    scopes = list(resource.scope_metrics)
+    scope = scopes[scope_index]
+    scopes[scope_index] = ScopeMetrics(scope.scope, [*scope.metrics, metric], scope.schema_url)
+    resource_metrics[resource_index] = ResourceMetrics(
+        resource.resource, scopes, resource.schema_url
+    )
+    return MetricsData(resource_metrics)
+
+
+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
+        self.output_chunks: OutputChunkAggregation | None = None
+
+    def export(
+        self,
+        metrics_data: MetricsData,
+        timeout_millis: float | None = 10_000,
+        **kwargs: Any,
+    ) -> MetricExportResult:
+        if self.output_chunks is not None:
+            metrics_data = _with_output_chunks(metrics_data, self.output_chunks)
+        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,
+        output_chunks: OutputChunkAggregation | None = None,
+    ) -> None:
+        self._on_error = on_error
+        self._output_chunks = output_chunks
+        self._custom_reader_limitation_reported = False
+        self._custom_reader_limitation_lock = threading.Lock()
+        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,
+        )
+        self._first_chunk = meter.create_histogram(
+            "gen_ai.client.operation.time_to_first_chunk",
+            unit="s",
+            explicit_bucket_boundaries_advisory=DURATION_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 operation == "chat":
+                from ._spans import output_chunk_aggregate
+
+                chunk_aggregate = output_chunk_aggregate(span)
+                if chunk_aggregate is not None:
+                    if self._output_chunks is not None:
+                        self._output_chunks.add(metric_attrs, chunk_aggregate)
+                    else:
+                        with self._custom_reader_limitation_lock:
+                            should_report = not self._custom_reader_limitation_reported
+                            self._custom_reader_limitation_reported = True
+                        if should_report:
+                            report_error(
+                                self._on_error,
+                                "output chunk interval metric is unavailable with a custom "
+                                "metric_reader",
+                                RuntimeError(
+                                    "gen_ai.client.operation.time_per_output_chunk requires the "
+                                    "built-in OTLP metric exporter; ordinary auto-metrics remain "
+                                    "enabled"
+                                ),
+                            )
+            context = set_span_in_context(NonRecordingSpan(span.context or INVALID_SPAN_CONTEXT))
+            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, context=context)
+            first_chunk_seconds = attributes.get(ATTR_TIME_TO_FIRST_CHUNK)
+            if (
+                operation == "chat"
+                and isinstance(first_chunk_seconds, (int, float))
+                and not isinstance(first_chunk_seconds, bool)
+                and math.isfinite(first_chunk_seconds)
+                and first_chunk_seconds >= 0
+            ):
+                self._first_chunk.record(first_chunk_seconds, metric_attrs, context=context)
+            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"}, context=context
+                )
+            output_tokens = attributes.get(_OUTPUT_TOKENS_ATTR)
+            if isinstance(output_tokens, int):
+                self._tokens.record(
+                    output_tokens, {**metric_attrs, "gen_ai.token.type": "output"}, context=context
+                )
+        except BaseException as exc:
+            report_error(self._on_error, "failed to record auto-metrics for span", exc)

{telemetry_dev-0.2.3 → telemetry_dev-0.2.4}/src/telemetry_dev/_spans.py

@@ -1,12 +1,16 @@
 from __future__ import annotations
 
+import math
+import threading
+import time
 import traceback
+from bisect import bisect_left
 from collections.abc import Callable, Mapping, Sequence
 from contextvars import Token
 from dataclasses import dataclass
 from datetime import datetime
 from typing import Any, Literal, TypedDict
-from weakref import WeakKeyDictionary
+from weakref import WeakKeyDictionary, WeakValueDictionary
 
 from opentelemetry import context as otel_context
 from opentelemetry import trace
@@ -42,6 +46,7 @@ from ._semconv import (
     ATTR_TOOL_CALL_ID,
     ATTR_TOOL_DESCRIPTION,
     ATTR_TOOL_NAME,
+    DURATION_BUCKETS,
     METADATA_PREFIX,
     RESERVED_METADATA_KEYS,
     SAMPLING_ATTRS,
@@ -86,9 +91,42 @@ class _SpanState:
     operation: str
     capture_input: bool
     capture_output: bool
+    output_chunk_last_ms: float | None = None
+    output_chunk_count: int = 0
+    output_chunk_sum_s: float = 0
+    output_chunk_min_s: float | None = None
+    output_chunk_max_s: float | None = None
+    output_chunk_buckets: list[int] | None = None
 
 
 _SPAN_STATES: WeakKeyDictionary[Span, _SpanState] = WeakKeyDictionary()
+_OUTPUT_CHUNK_STATES: WeakValueDictionary[tuple[int, int], _SpanState] = WeakValueDictionary()
+_OUTPUT_CHUNK_STATES_LOCK = threading.Lock()
+
+
+def _span_key(span: Any) -> tuple[int, int]:
+    context = span.get_span_context() if hasattr(span, "get_span_context") else span.context
+    return context.trace_id, context.span_id
+
+
+def output_chunk_aggregate(span: Any) -> tuple[int, float, float, float, tuple[int, ...]] | None:
+    with _OUTPUT_CHUNK_STATES_LOCK:
+        state = _OUTPUT_CHUNK_STATES.pop(_span_key(span), None)
+        if (
+            state is None
+            or state.output_chunk_count == 0
+            or state.output_chunk_min_s is None
+            or state.output_chunk_max_s is None
+            or state.output_chunk_buckets is None
+        ):
+            return None
+        return (
+            state.output_chunk_count,
+            state.output_chunk_sum_s,
+            state.output_chunk_min_s,
+            state.output_chunk_max_s,
+            tuple(state.output_chunk_buckets),
+        )
 
 
 def _to_ns(value: TimeInput) -> int | None:
@@ -413,6 +451,45 @@ class SpanHandle:
             self._client.report("SpanHandle.update failed", exc)
         return self
 
+    def record_output_chunk(self, timestamp_ms: float | None = None) -> SpanHandle:
+        """Record arrival of a non-empty output chunk using a monotonic millisecond timestamp."""
+        if not self._recording():
+            return self
+        assert self._state is not None and self._client is not None
+        try:
+            now = time.perf_counter() * 1000 if timestamp_ms is None else float(timestamp_ms)
+            if not math.isfinite(now):
+                return self
+            with _OUTPUT_CHUNK_STATES_LOCK:
+                if not self._recording():
+                    return self
+                previous = self._state.output_chunk_last_ms
+                if previous is not None and now < previous:
+                    return self
+                self._state.output_chunk_last_ms = now
+                _OUTPUT_CHUNK_STATES[_span_key(self.span)] = self._state
+                if previous is None:
+                    return self
+                interval_s = max(now - previous, 0) / 1000
+                self._state.output_chunk_count += 1
+                self._state.output_chunk_sum_s += interval_s
+                self._state.output_chunk_min_s = (
+                    interval_s
+                    if self._state.output_chunk_min_s is None
+                    else min(self._state.output_chunk_min_s, interval_s)
+                )
+                self._state.output_chunk_max_s = (
+                    interval_s
+                    if self._state.output_chunk_max_s is None
+                    else max(self._state.output_chunk_max_s, interval_s)
+                )
+                if self._state.output_chunk_buckets is None:
+                    self._state.output_chunk_buckets = [0] * (len(DURATION_BUCKETS) + 1)
+                self._state.output_chunk_buckets[bisect_left(DURATION_BUCKETS, interval_s)] += 1
+        except BaseException as exc:
+            self._client.report("SpanHandle.record_output_chunk failed", exc)
+        return self
+
     def end(
         self,
         *,
@@ -480,7 +557,10 @@ class SpanHandle:
             attributes=attributes,
             error=error,
         )
-        self._ended = True
+        with _OUTPUT_CHUNK_STATES_LOCK:
+            if self._ended:
+                return
+            self._ended = True
         self.span.end(_to_ns(end_time))
 
     def traceparent(self) -> str | None:

telemetry_dev-0.2.3/src/telemetry_dev/_metrics.py

@@ -1,120 +0,0 @@
-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)