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

telemetry_dev-0.2.3/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.1 → telemetry_dev-0.2.3}/PKG-INFO

@@ -1,10 +1,11 @@
 Metadata-Version: 2.4
 Name: telemetry-dev
-Version: 0.2.1
+Version: 0.2.3
 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
@@ -80,9 +81,17 @@ 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.
 
+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 |
@@ -137,11 +146,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.3}/README.md

@@ -57,9 +57,17 @@ 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.
 
+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 |
@@ -114,11 +122,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.3}/pyproject.toml

@@ -1,9 +1,10 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.1"
+version = "0.2.3"
 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.1 → telemetry_dev-0.2.3}/pyproject.toml.orig

@@ -1,9 +1,10 @@
 [project]
 name = "telemetry-dev"
-version = "0.2.1"
+version = "0.2.3"
 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.1 → telemetry_dev-0.2.3}/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.1 → telemetry_dev-0.2.3}/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
 
@@ -26,17 +27,20 @@ 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 (
     SDK_VERSION,
     LogLevelOption,
     ResolvedConfig,
+    SessionMode,
     configure_logger,
     logger,
     report_error,
     resolve_config,
 )
+from ._context import SessionSampler
 from ._metrics import GuardedOTLPMetricExporter, MetricsRecorder
 from ._processor import ExportMode, StampingSpanProcessor
 from ._semconv import SCOPE_NAME
@@ -121,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,
@@ -128,6 +133,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,
@@ -142,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
 
@@ -170,12 +179,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.
@@ -311,6 +322,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",
@@ -319,6 +331,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,
@@ -342,9 +355,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,
@@ -352,6 +368,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.3}/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.1 → telemetry_dev-0.2.3}/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):
@@ -33,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(
     *,
@@ -99,3 +151,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.3}/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.1 → telemetry_dev-0.2.3}/src/telemetry_dev/_spans.py

@@ -17,7 +17,13 @@ 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,
+    context_with_propagated_attributes,
+    propagated_attributes,
+    traceparent_of,
+    with_session_parent,
+)
 from ._semconv import (
     ATTR_AGENT_ID,
     ATTR_AGENT_NAME,
@@ -30,6 +36,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 +152,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 +227,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)
 
@@ -305,10 +318,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
 
@@ -468,7 +488,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]:
@@ -538,19 +560,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 +589,41 @@ 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)
+        )
+        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
+        )
+        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, ctx)
+        # 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)