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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.1
+Version: 0.2.2
 Summary: telemetry.dev SDK for Python — OpenTelemetry-native GenAI tracing, logs, and metrics
 Keywords: telemetry,opentelemetry,llm,genai,tracing,observability
 Author: telemetry.dev
@@ -80,6 +80,8 @@ routed to the `on_error` hook / `telemetry_dev` logger — never raised into you
 | `TELEMETRY_DEV_BASE_URL` | `https://ingest.telemetry.dev` | Ingest base URL (trailing slashes stripped). |
 | `TELEMETRY_DEV_ENVIRONMENT` | `production` | Deployment environment label. |
 | `OTEL_SERVICE_NAME` | `unknown_service` | Service name on every trace. |
+| `OTEL_TRACES_SAMPLER` | `parentbased_always_on` | OTel trace sampling policy, which includes session roots. |
+| `OTEL_TRACES_SAMPLER_ARG` | `1.0` | Probability for `traceidratio` / `parentbased_traceidratio`. |
 
 Explicit `init()` arguments take precedence over environment variables.
 
@@ -137,11 +139,18 @@ Explicit `init()` arguments take precedence over environment variables.
 | `mask` | `None` | `Callable[[Any, MaskContext], Any]` redaction hook, runs before JSON serialization on input/output/log messages (`MaskContext.key` is the attribute being written). Not applied to correlation identifiers. |
 | `max_attribute_length` | `65536` | Per-content-attribute cap; truncated values get an ASCII `...[truncated]` marker appended. |
 | `span_filter` | `None` | Export predicate `Callable[[ReadableSpan], bool]`. |
+| `sampler` | OTel environment configuration | OTel `Sampler` that overrides environment settings. Session roots use its root policy. Real parents keep their sampling decisions. |
 | `on_error` | `None` | Receives every internal SDK error; the SDK never raises. |
 | `disable_atexit` | `False` | Skip the automatic atexit shutdown. |
 | `timeout` | `10.0` | OTLP HTTP timeout in seconds. |
 | `span_exporter`, `log_exporter`, `metric_reader` | `None` | Test seams / offline mode; any of them enables the client without an API key. |
 
+Session roots share trace IDs from the API key and session ID. The hash matches the TypeScript SDK.
+The SDK uses the configured OTel sampling policy, not the synthetic parent's flags.
+For example, `init(sampler=ParentBased(TraceIdRatioBased(0.1)))` samples sessions with OTel's ratio sampler.
+These classes come from `opentelemetry.sdk.trace.sampling`.
+The built-in Python and TypeScript ratio samplers can select different sessions because the OTel algorithms differ.
+
 ## Auto-metrics
 
 Ended spans automatically record two histograms (DELTA temporality, exported every 60s):

{telemetry_dev-0.2.1 → telemetry_dev-0.2.2}/README.md

@@ -57,6 +57,8 @@ routed to the `on_error` hook / `telemetry_dev` logger — never raised into you
 | `TELEMETRY_DEV_BASE_URL` | `https://ingest.telemetry.dev` | Ingest base URL (trailing slashes stripped). |
 | `TELEMETRY_DEV_ENVIRONMENT` | `production` | Deployment environment label. |
 | `OTEL_SERVICE_NAME` | `unknown_service` | Service name on every trace. |
+| `OTEL_TRACES_SAMPLER` | `parentbased_always_on` | OTel trace sampling policy, which includes session roots. |
+| `OTEL_TRACES_SAMPLER_ARG` | `1.0` | Probability for `traceidratio` / `parentbased_traceidratio`. |
 
 Explicit `init()` arguments take precedence over environment variables.
 
@@ -114,11 +116,18 @@ Explicit `init()` arguments take precedence over environment variables.
 | `mask` | `None` | `Callable[[Any, MaskContext], Any]` redaction hook, runs before JSON serialization on input/output/log messages (`MaskContext.key` is the attribute being written). Not applied to correlation identifiers. |
 | `max_attribute_length` | `65536` | Per-content-attribute cap; truncated values get an ASCII `...[truncated]` marker appended. |
 | `span_filter` | `None` | Export predicate `Callable[[ReadableSpan], bool]`. |
+| `sampler` | OTel environment configuration | OTel `Sampler` that overrides environment settings. Session roots use its root policy. Real parents keep their sampling decisions. |
 | `on_error` | `None` | Receives every internal SDK error; the SDK never raises. |
 | `disable_atexit` | `False` | Skip the automatic atexit shutdown. |
 | `timeout` | `10.0` | OTLP HTTP timeout in seconds. |
 | `span_exporter`, `log_exporter`, `metric_reader` | `None` | Test seams / offline mode; any of them enables the client without an API key. |
 
+Session roots share trace IDs from the API key and session ID. The hash matches the TypeScript SDK.
+The SDK uses the configured OTel sampling policy, not the synthetic parent's flags.
+For example, `init(sampler=ParentBased(TraceIdRatioBased(0.1)))` samples sessions with OTel's ratio sampler.
+These classes come from `opentelemetry.sdk.trace.sampling`.
+The built-in Python and TypeScript ratio samplers can select different sessions because the OTel algorithms differ.
+
 ## Auto-metrics
 
 Ended spans automatically record two histograms (DELTA temporality, exported every 60s):

{telemetry_dev-0.2.1 → telemetry_dev-0.2.2}/pyproject.toml

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

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

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

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

@@ -26,6 +26,7 @@ from opentelemetry.sdk.metrics.export import (
 from opentelemetry.sdk.resources import Resource
 from opentelemetry.sdk.trace import ReadableSpan, SpanLimits, TracerProvider
 from opentelemetry.sdk.trace.export import SpanExporter, SpanExportResult
+from opentelemetry.sdk.trace.sampling import Sampler
 from opentelemetry.trace import Tracer
 
 from ._config import (
@@ -37,6 +38,7 @@ from ._config import (
     report_error,
     resolve_config,
 )
+from ._context import SessionSampler
 from ._metrics import GuardedOTLPMetricExporter, MetricsRecorder
 from ._processor import ExportMode, StampingSpanProcessor
 from ._semconv import SCOPE_NAME
@@ -128,6 +130,7 @@ class Client:
         mask: Mask | None = None,
         max_attribute_length: int = 65536,
         span_filter: Callable[[ReadableSpan], bool] | None = None,
+        sampler: Sampler | None = None,
         on_error: Callable[[BaseException], None] | None = None,
         disable_atexit: bool = False,
         timeout: float = 10.0,
@@ -170,12 +173,14 @@ class Client:
         # the backstop can use the same cap for raw attributes set outside the funnel.
         self._tracer_provider = TracerProvider(
             resource=resource,
+            sampler=sampler,
             shutdown_on_exit=False,
             span_limits=SpanLimits(
                 max_attribute_length=max_attribute_length,
                 max_span_attribute_length=max_attribute_length,
             ),
         )
+        self._tracer_provider.sampler = SessionSampler(self._tracer_provider.sampler)
 
         # 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.
@@ -319,6 +324,7 @@ def init(
     mask: Mask | None = None,
     max_attribute_length: int = 65536,
     span_filter: Callable[[ReadableSpan], bool] | None = None,
+    sampler: Sampler | None = None,
     on_error: Callable[[BaseException], None] | None = None,
     disable_atexit: bool = False,
     timeout: float = 10.0,
@@ -352,6 +358,7 @@ def init(
             mask=mask,
             max_attribute_length=max_attribute_length,
             span_filter=span_filter,
+            sampler=sampler,
             on_error=on_error,
             disable_atexit=disable_atexit,
             timeout=timeout,

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

@@ -1,14 +1,24 @@
 from __future__ import annotations
 
-from collections.abc import Generator, Mapping
+import hashlib
+from collections.abc import Generator, Mapping, Sequence
 from contextlib import contextmanager
 from typing import Any, cast
 
 from opentelemetry import context as otel_context
 from opentelemetry import trace
 from opentelemetry.context import Context
-from opentelemetry.trace import NonRecordingSpan, SpanContext
+from opentelemetry.sdk.trace.sampling import Sampler, SamplingResult
+from opentelemetry.trace import (
+    Link,
+    NonRecordingSpan,
+    SpanContext,
+    SpanKind,
+    TraceFlags,
+    TraceState,
+)
 from opentelemetry.trace.propagation.tracecontext import TraceContextTextMapPropagator
+from opentelemetry.util.types import Attributes
 
 from ._config import logger
 from ._semconv import (
@@ -26,6 +36,41 @@ _PROPAGATOR = TraceContextTextMapPropagator()
 ParentInput = str | Context | SpanContext | None
 
 
+class _SessionParent(NonRecordingSpan):
+    def __init__(self, span_context: SpanContext, context: Context) -> None:
+        super().__init__(span_context)
+        self.parent_context = context
+
+
+class SessionSampler(Sampler):
+    """Pair with with_session_parent to sample roots using the provider's real policy."""
+
+    def __init__(self, inner: Sampler) -> None:
+        self.inner = inner
+
+    def should_sample(
+        self,
+        parent_context: Context | None,
+        trace_id: int,
+        name: str,
+        kind: SpanKind | None = None,
+        attributes: Attributes = None,
+        links: Sequence[Link] | None = None,
+        trace_state: TraceState | None = None,
+    ) -> SamplingResult:
+        parent = trace.get_current_span(parent_context)
+        if isinstance(parent, _SessionParent):
+            parent_context = trace.set_span_in_context(
+                trace.get_current_span(parent.parent_context), parent_context
+            )
+        return self.inner.should_sample(
+            parent_context, trace_id, name, kind, attributes, links, trace_state
+        )
+
+    def get_description(self) -> str:
+        return f"SessionSampler{{{self.inner.get_description()}}}"
+
+
 def propagated_attributes(context: Context | None = None) -> dict[str, AttributeValue]:
     value = otel_context.get_value(_PROPAGATED_KEY, context=context)
     if isinstance(value, Mapping):
@@ -99,3 +144,33 @@ def context_from_parent(parent: ParentInput) -> Context | None:
         if ambient:
             ctx = otel_context.set_value(_PROPAGATED_KEY, ambient, context=ctx)
     return ctx
+
+
+def session_span_context(api_key: str | None, session_id: str) -> SpanContext:
+    """Deterministic remote parent for a session, byte-identical to the TS `sessionSpanContext`:
+    trace id = SHA-256(api_key ‖ 0x00 ‖ session_id)[0:16], parent span id = digest[16:24].
+    The flags are not a sampling decision; pair with_session_parent with SessionSampler."""
+    text = f"{api_key or ''}\0{session_id}"
+    # Match TextEncoder: surrogate pairs combine, lone surrogates become U+FFFD.
+    text = text.encode("utf-16-le", "surrogatepass").decode("utf-16-le", "replace")
+    digest = hashlib.sha256(text.encode()).digest()
+    return SpanContext(
+        trace_id=int.from_bytes(digest[:16], "big"),
+        span_id=int.from_bytes(digest[16:24], "big"),
+        is_remote=True,
+        trace_flags=TraceFlags(TraceFlags.DEFAULT),
+    )
+
+
+def with_session_parent(
+    context: Context | None, session_id: str | None, api_key: str | None
+) -> Context | None:
+    """Parent a root under the session; requires SessionSampler on the provider."""
+    if not api_key or not session_id:
+        return context
+    if trace.get_current_span(context).get_span_context().is_valid:
+        return context
+    base = context if context is not None else otel_context.get_current()
+    return trace.set_span_in_context(
+        _SessionParent(session_span_context(api_key, session_id), base), base
+    )

{telemetry_dev-0.2.1 → telemetry_dev-0.2.2}/src/telemetry_dev/_spans.py

@@ -17,7 +17,12 @@ from opentelemetry.util import types as otel_types
 
 from ._client import Client, get_client
 from ._config import logger
-from ._context import context_from_parent, traceparent_of
+from ._context import (
+    context_from_parent,
+    propagated_attributes,
+    traceparent_of,
+    with_session_parent,
+)
 from ._semconv import (
     ATTR_AGENT_ID,
     ATTR_AGENT_NAME,
@@ -30,6 +35,7 @@ from ._semconv import (
     ATTR_REQUEST_MODEL,
     ATTR_RESPONSE_ID,
     ATTR_RESPONSE_MODEL,
+    ATTR_SESSION_ID,
     ATTR_SYSTEM_INSTRUCTIONS,
     ATTR_TIME_TO_FIRST_CHUNK,
     ATTR_TOOL_CALL_ID,
@@ -145,14 +151,12 @@ def _usage_attrs(usage: Mapping[str, Any]) -> dict[str, AttributeValue]:
     return attrs
 
 
-def _apply_fields(client: Client, span: Span, state: _SpanState, fields: dict[str, Any]) -> None:
+def _fields_to_attributes(
+    client: Client, state: _SpanState, fields: dict[str, Any]
+) -> dict[str, otel_types.AttributeValue]:
     """Map the shared snake_case field set onto gen_ai.* attributes; raw `attributes` merge last."""
     attrs: dict[str, otel_types.AttributeValue] = {}
 
-    name = fields.get("name")
-    if name is not None:
-        span.update_name(name)
-
     for field, attr in (
         ("model", ATTR_REQUEST_MODEL),
         ("provider", ATTR_PROVIDER),
@@ -222,6 +226,14 @@ def _apply_fields(client: Client, span: Span, state: _SpanState, fields: dict[st
             if attr is not None:
                 attrs[key] = attr
 
+    return attrs
+
+
+def _apply_fields(client: Client, span: Span, state: _SpanState, fields: dict[str, Any]) -> None:
+    name = fields.get("name")
+    if name is not None:
+        span.update_name(name)
+    attrs = _fields_to_attributes(client, state, fields)
     if attrs:
         span.set_attributes(attrs)
 
@@ -538,19 +550,6 @@ def start_span(
             capture_input=client.capture_input if capture_input is None else capture_input,
             capture_output=client.capture_output if capture_output is None else capture_output,
         )
-        initial: dict[str, otel_types.AttributeValue] = {ATTR_OPERATION: operation}
-        if operation == "execute_tool":
-            initial[ATTR_TOOL_NAME] = name
-        elif operation == "invoke_agent":
-            initial[ATTR_AGENT_NAME] = name
-        span = client.tracer.start_span(
-            name,
-            context=context_from_parent(parent),
-            attributes=initial,
-            start_time=_to_ns(start_time),
-        )
-        _SPAN_STATES[span] = state
-        handle = SpanHandle(span, client, state)
         fields = _collect_fields(
             input=input,
             output=output,
@@ -580,8 +579,36 @@ def start_span(
             metadata=metadata,
             attributes=attributes,
         )
-        if fields:
-            _apply_fields(client, span, state, fields)
+        attrs = _fields_to_attributes(client, state, fields)
+        initial: dict[str, otel_types.AttributeValue] = {ATTR_OPERATION: operation}
+        if operation == "execute_tool":
+            initial[ATTR_TOOL_NAME] = name
+        elif operation == "invoke_agent":
+            initial[ATTR_AGENT_NAME] = name
+        ctx = context_from_parent(parent)
+        propagated = propagated_attributes(ctx)
+        explicit_session_id = (attributes or {}).get(ATTR_SESSION_ID)
+        session_id = (
+            explicit_session_id
+            if isinstance(explicit_session_id, str)
+            else propagated.get(ATTR_SESSION_ID)
+        )
+        ctx = with_session_parent(
+            ctx, session_id if isinstance(session_id, str) else None, client.config.api_key
+        )
+        initial.update(propagated)
+        initial.update(attrs)
+        span = client.tracer.start_span(
+            name,
+            context=ctx,
+            attributes=initial,
+            start_time=_to_ns(start_time),
+        )
+        _SPAN_STATES[span] = state
+        handle = SpanHandle(span, client, state)
+        # The processor stamps propagation on start; explicit fields still win.
+        if attrs:
+            span.set_attributes(attrs)
         return handle
     except BaseException as exc:
         client.report("start_span failed", exc)