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

telemetry_dev-0.2.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 telemetry.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.2
+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
 License-Expression: MIT
+License-File: LICENSE
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: Programming Language :: Python :: 3
@@ -18,7 +19,7 @@ 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
+Project-URL: Repository, https://github.com/telemetry-dev/sdks
 Description-Content-Type: text/markdown
 
 # telemetry-dev
@@ -85,6 +86,12 @@ routed to the `on_error` hook / `telemetry_dev` logger — never raised into you
 
 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
 
 | Name | Description |
@@ -92,7 +99,7 @@ Explicit `init()` arguments take precedence over environment variables.
 | `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`). |
@@ -101,6 +108,18 @@ Explicit `init()` arguments take precedence over environment variables.
 | `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`:
@@ -153,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.2 → telemetry_dev-0.2.4}/README.md

@@ -62,6 +62,12 @@ routed to the `on_error` hook / `telemetry_dev` logger — never raised into you
 
 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
 
 | Name | Description |
@@ -69,7 +75,7 @@ Explicit `init()` arguments take precedence over environment variables.
 | `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`). |
@@ -78,6 +84,18 @@ Explicit `init()` arguments take precedence over environment variables.
 | `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`:
@@ -130,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.2 → telemetry_dev-0.2.4}/pyproject.toml

@@ -1,9 +1,10 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.2"
+version = "0.2.4"
 description = "telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics"
 readme = "README.md"
 license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.10"
 keywords = [
     "telemetry",
@@ -34,7 +35,7 @@ name = "telemetry.dev"
 
 [project.urls]
 Homepage = "https://telemetry.dev"
-Repository = "https://github.com/telemetry-dev/telemetry.dev"
+Repository = "https://github.com/telemetry-dev/sdks"
 
 [dependency-groups]
 dev = [

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

@@ -1,9 +1,10 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.2"
+version = "0.2.4"
 description = "telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics"
 readme = "README.md"
 license = "MIT"
+license-files = ["LICENSE"]
 requires-python = ">=3.10"
 authors = [{ name = "telemetry.dev" }]
 keywords = ["telemetry", "opentelemetry", "llm", "genai", "tracing", "observability"]
@@ -25,7 +26,7 @@ dependencies = [
 
 [project.urls]
 Homepage = "https://telemetry.dev"
-Repository = "https://github.com/telemetry-dev/telemetry.dev"
+Repository = "https://github.com/telemetry-dev/sdks"
 
 [dependency-groups]
 dev = [

{telemetry_dev-0.2.2 → telemetry_dev-0.2.4}/src/telemetry_dev/_capture.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from collections.abc import Iterable
+from itertools import chain
 from typing import Final, cast
 
 _DEFAULT_MAX_BYTES: Final = 64 * 1024
@@ -133,33 +134,7 @@ class CaptureBudget:
                 mapping = cast("dict[object, object]", attributes)
 
         if mapping is not None:
-            for key, child in mapping.items():
-                measured = cls._measure(
-                    key,
-                    remaining_bytes=remaining_bytes - byte_count,
-                    remaining_items=remaining_items - item_count,
-                    depth=depth + 1,
-                    seen=seen,
-                )
-                if measured is None:
-                    return None
-                child_bytes, child_items = measured
-                byte_count += child_bytes
-                item_count += child_items
-
-                measured = cls._measure(
-                    child,
-                    remaining_bytes=remaining_bytes - byte_count,
-                    remaining_items=remaining_items - item_count,
-                    depth=depth + 1,
-                    seen=seen,
-                )
-                if measured is None:
-                    return None
-                child_bytes, child_items = measured
-                byte_count += child_bytes
-                item_count += child_items
-            return byte_count, item_count
+            children = chain.from_iterable(mapping.items())
 
         for child in children:
             measured = cls._measure(

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

@@ -2,6 +2,7 @@ from __future__ import annotations
 
 import atexit
 import threading
+import uuid
 from collections.abc import Callable
 from typing import Any
 
@@ -33,13 +34,14 @@ from ._config import (
     SDK_VERSION,
     LogLevelOption,
     ResolvedConfig,
+    SessionMode,
     configure_logger,
     logger,
     report_error,
     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
@@ -123,6 +125,7 @@ class Client:
         *,
         config: ResolvedConfig,
         enabled: bool,
+        session_mode: SessionMode = "explicit",
         register_global: bool = False,
         export_mode: ExportMode = "batched",
         capture_input: bool = True,
@@ -145,6 +148,9 @@ class Client:
         self.mask = mask
         self.max_attribute_length = max_attribute_length
         self.on_error = on_error
+        self._process_session_id: str | None = (
+            str(uuid.uuid4()) if enabled and session_mode == "process" else None
+        )
         self._shutdown = False
         self._atexit_registered = False
 
@@ -154,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
@@ -185,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,
@@ -193,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
             )
@@ -202,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(
@@ -316,6 +327,7 @@ def init(
     environment: str | None = None,
     service_name: str | None = None,
     enabled: bool = True,
+    session_mode: SessionMode = "explicit",
     register_global: bool = False,
     export_mode: ExportMode = "batched",
     log_level: LogLevelOption = "warn",
@@ -348,9 +360,12 @@ def init(
         logger.debug("telemetry-dev disabled: no API key")
 
     try:
+        if session_mode not in ("explicit", "process"):
+            raise ValueError(f"invalid session_mode: {session_mode!r}")
         client = Client(
             config=config,
             enabled=effective_enabled,
+            session_mode=session_mode,
             register_global=register_global,
             export_mode=export_mode,
             capture_input=capture_input,

{telemetry_dev-0.2.2 → telemetry_dev-0.2.4}/src/telemetry_dev/_config.py

@@ -22,6 +22,7 @@ def _resolve_version() -> str:
 SDK_VERSION = _resolve_version()
 
 LogLevelOption = Literal["debug", "info", "warn", "error", "silent"]
+SessionMode = Literal["explicit", "process"]
 
 logger = logging.getLogger("telemetry_dev")
 

{telemetry_dev-0.2.2 → telemetry_dev-0.2.4}/src/telemetry_dev/_context.py

@@ -78,6 +78,13 @@ def propagated_attributes(context: Context | None = None) -> dict[str, Attribute
     return {}
 
 
+def context_with_propagated_attributes(
+    attributes: Mapping[str, AttributeValue], context: Context | None = None
+) -> Context:
+    base = context if context is not None else otel_context.get_current()
+    return otel_context.set_value(_PROPAGATED_KEY, attributes, context=base)
+
+
 @contextmanager
 def propagate_attributes(
     *,

{telemetry_dev-0.2.2 → telemetry_dev-0.2.4}/src/telemetry_dev/_logs.py

@@ -7,8 +7,8 @@ from opentelemetry._logs import SeverityNumber
 
 from ._client import get_client
 from ._config import logger
-from ._context import propagated_attributes
-from ._semconv import SEVERITY, LogLevel
+from ._context import context_with_propagated_attributes, propagated_attributes
+from ._semconv import ATTR_SESSION_ID, SEVERITY, LogLevel
 from ._serialize import AttributeValue, coerce_attr_value
 
 
@@ -41,9 +41,21 @@ def log(
                 )
                 if attr is not None:
                     attrs[key] = attr
+        propagated = propagated_attributes()
+        process_session_id = client._process_session_id  # pyright: ignore[reportPrivateUsage]
+        explicit_session = attributes is not None and ATTR_SESSION_ID in attributes
+        if (
+            not explicit_session
+            and ATTR_SESSION_ID not in propagated
+            and process_session_id is not None
+        ):
+            propagated[ATTR_SESSION_ID] = process_session_id
+        context = otel_context.get_current()
+        if propagated:
+            context = context_with_propagated_attributes(propagated, context)
         # Propagated correlation attrs win on key collisions, matching the span-processor
         # stamping model and the TypeScript SDK.
-        for key, value in propagated_attributes().items():
+        for key, value in propagated.items():
             attr = coerce_attr_value(
                 value,
                 max_len=client.max_attribute_length,
@@ -54,7 +66,7 @@ def log(
                 attrs[key] = attr
         body = client.serialize(message, "log.message") or ""
         client.otel_logger.emit(
-            context=otel_context.get_current(),
+            context=context,
             severity_number=SeverityNumber(severity),
             severity_text=normalized.upper(),
             body=body,

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.2 → 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
@@ -19,6 +23,7 @@ from ._client import Client, get_client
 from ._config import logger
 from ._context import (
     context_from_parent,
+    context_with_propagated_attributes,
     propagated_attributes,
     traceparent_of,
     with_session_parent,
@@ -41,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,
@@ -85,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:
@@ -317,10 +356,17 @@ class SpanHandle:
     """Handle around an OTel span. Use as a context manager to activate the span in the
     current context, or keep it detached and call .end() manually."""
 
-    def __init__(self, span: Span, client: Client | None, state: _SpanState | None) -> None:
+    def __init__(
+        self,
+        span: Span,
+        client: Client | None,
+        state: _SpanState | None,
+        context: Context | None = None,
+    ) -> None:
         self.span = span
         self._client = client
         self._state = state
+        self._context = context
         self._context_token: Token[Context] | None = None
         self._ended = False
 
@@ -405,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,
         *,
@@ -472,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:
@@ -480,7 +568,9 @@ class SpanHandle:
 
     def __enter__(self) -> SpanHandle:
         if self._client is not None and self._state is not None:
-            self._context_token = otel_context.attach(trace.set_span_in_context(self.span))
+            self._context_token = otel_context.attach(
+                trace.set_span_in_context(self.span, self._context)
+            )
         return self
 
     def __exit__(self, exc_type: Any, exc: Any, tb: Any) -> Literal[False]:
@@ -593,6 +683,11 @@ def start_span(
             if isinstance(explicit_session_id, str)
             else propagated.get(ATTR_SESSION_ID)
         )
+        if not isinstance(session_id, str):
+            session_id = client._process_session_id  # pyright: ignore[reportPrivateUsage]
+        if isinstance(session_id, str):
+            propagated[ATTR_SESSION_ID] = session_id
+            ctx = context_with_propagated_attributes(propagated, ctx)
         ctx = with_session_parent(
             ctx, session_id if isinstance(session_id, str) else None, client.config.api_key
         )
@@ -605,7 +700,7 @@ def start_span(
             start_time=_to_ns(start_time),
         )
         _SPAN_STATES[span] = state
-        handle = SpanHandle(span, client, state)
+        handle = SpanHandle(span, client, state, ctx)
         # The processor stamps propagation on start; explicit fields still win.
         if attrs:
             span.set_attributes(attrs)

telemetry_dev-0.2.2/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)