struct-sdk 0.3.2__tar.gz → 0.4.2__tar.gz

{struct_sdk-0.3.2 → struct_sdk-0.4.2}/.gitignore

@@ -118,3 +118,6 @@ struct-agent-key.json
 
 # Local/CI test result artifacts
 **/test-results/
+
+# Generated agent session project ledgers (data, HTML and local helper state)
+.project-ledgers/

{struct_sdk-0.3.2 → struct_sdk-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: struct-sdk
-Version: 0.3.2
+Version: 0.4.2
 Summary: Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry
 Project-URL: Homepage, https://struct.ai
 Project-URL: Documentation, https://struct.ai/docs
@@ -103,7 +103,7 @@ Description-Content-Type: text/markdown
 # struct-sdk
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
-token usage, and message events from the Anthropic SDK, the OpenAI SDK
+token usage, and message content from the Anthropic SDK, the OpenAI SDK
 (Responses API), pydantic-ai, the Claude Agent SDK, and LangChain /
 LangGraph, and exports them to [struct.ai](https://struct.ai) for observability.
 
@@ -164,7 +164,7 @@ async with struct.agent(name="checkout"):
 | Library | Span type | Notes |
 |---|---|---|
 | `anthropic` | `chat {model}` | Cache-token accounting; streaming chats with tool-use reconstruction. Bedrock and Vertex variants supported if installed. |
-| `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: per-message events (`gen_ai.system/user/assistant/tool.message`) and `gen_ai.choice`, plus `gen_ai.input.messages` / `gen_ai.output.messages` in span-content mode. Reasoning items are skipped (`encrypted_content` is never emitted). |
+| `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: in event modes, one `gen_ai.client.inference.operation.details` record per call; in span modes, `gen_ai.input.messages` / `gen_ai.output.messages` on the span. Reasoning items are skipped (`encrypted_content` is never emitted). |
 | `pydantic_ai` | `invoke_agent {agent}`, `chat {model}`, `execute_tool {tool}` | pydantic-ai's own instrumentation, turned on with Struct's tracer provider. See [pydantic-ai](#pydantic-ai). |
 | `claude_agent_sdk` | `agent`, `chat`, `execute_tool` | Telemetry comes from Claude Code itself in the subprocess; ingest credentials are propagated to it via `ClaudeAgentOptions`. Subagents inherit the configuration. |
 | `langchain_core` `BaseChatModel` | `chat {model}` | When the underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic`), the provider's span is suppressed, so there is a single span. |
@@ -227,10 +227,9 @@ calls your code makes while reading a stream keep their spans). During agent
 runs, Struct guards telemetry faults and caps content. Realtime sessions and
 direct `InstrumentedModel` exception recording are outside this guarantee.
 
-- **Content** goes on span attributes only (pydantic-ai has no message
-  events): `span_only` / `span_and_event` include prompts, answers and tool
-  arguments; `event_only` and `none` do not. Tool definitions are always
-  recorded.
+- **Content:** in event modes, each chat call's messages go to one
+  `operation.details` event. Span modes keep chat content on spans. Tool
+  arguments and results remain on `execute_tool` spans in every mode but `none`.
 - **Sessions:** on Struct's provider, a `struct.agent(session_id=...)`
   around the run wins; otherwise pydantic-ai's `conversation_id` is used.
   Instrumentation configured on your own provider keeps its conversation IDs.
@@ -411,9 +410,10 @@ struct.init(
 )
 ```
 
-- **`EVENT_ONLY`**: per-message content lands on OTel log
-  records (`gen_ai.{user,assistant,system,tool}.message`,
-  `gen_ai.choice`). Spans carry metadata only.
+- **`EVENT_ONLY`**: each model call's content lands on one OTel log record,
+  `gen_ai.client.inference.operation.details` (input and output messages,
+  system instructions, tool definitions, as structured values). Spans carry
+  metadata only.
 - **`SPAN_ONLY`**: content on span attributes (`gen_ai.input.messages`,
   `gen_ai.output.messages`).
 - **`SPAN_AND_EVENT`**: both.

{struct_sdk-0.3.2 → struct_sdk-0.4.2}/README.md

@@ -1,7 +1,7 @@
 # struct-sdk
 
 OpenTelemetry instrumentation for AI agents in Python. Captures spans,
-token usage, and message events from the Anthropic SDK, the OpenAI SDK
+token usage, and message content from the Anthropic SDK, the OpenAI SDK
 (Responses API), pydantic-ai, the Claude Agent SDK, and LangChain /
 LangGraph, and exports them to [struct.ai](https://struct.ai) for observability.
 
@@ -62,7 +62,7 @@ async with struct.agent(name="checkout"):
 | Library | Span type | Notes |
 |---|---|---|
 | `anthropic` | `chat {model}` | Cache-token accounting; streaming chats with tool-use reconstruction. Bedrock and Vertex variants supported if installed. |
-| `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: per-message events (`gen_ai.system/user/assistant/tool.message`) and `gen_ai.choice`, plus `gen_ai.input.messages` / `gen_ai.output.messages` in span-content mode. Reasoning items are skipped (`encrypted_content` is never emitted). |
+| `openai` (Responses API) | `chat {model}` | Non-streaming `responses.create` on sync and async clients (Azure clients included). Cached-token accounting from `usage.input_tokens_details`. Streaming and `chat.completions` calls pass through untraced. Message-content capture at parity with the Anthropic integration: in event modes, one `gen_ai.client.inference.operation.details` record per call; in span modes, `gen_ai.input.messages` / `gen_ai.output.messages` on the span. Reasoning items are skipped (`encrypted_content` is never emitted). |
 | `pydantic_ai` | `invoke_agent {agent}`, `chat {model}`, `execute_tool {tool}` | pydantic-ai's own instrumentation, turned on with Struct's tracer provider. See [pydantic-ai](#pydantic-ai). |
 | `claude_agent_sdk` | `agent`, `chat`, `execute_tool` | Telemetry comes from Claude Code itself in the subprocess; ingest credentials are propagated to it via `ClaudeAgentOptions`. Subagents inherit the configuration. |
 | `langchain_core` `BaseChatModel` | `chat {model}` | When the underlying provider SDK is also instrumented (e.g. `ChatAnthropic` + `anthropic`), the provider's span is suppressed, so there is a single span. |
@@ -125,10 +125,9 @@ calls your code makes while reading a stream keep their spans). During agent
 runs, Struct guards telemetry faults and caps content. Realtime sessions and
 direct `InstrumentedModel` exception recording are outside this guarantee.
 
-- **Content** goes on span attributes only (pydantic-ai has no message
-  events): `span_only` / `span_and_event` include prompts, answers and tool
-  arguments; `event_only` and `none` do not. Tool definitions are always
-  recorded.
+- **Content:** in event modes, each chat call's messages go to one
+  `operation.details` event. Span modes keep chat content on spans. Tool
+  arguments and results remain on `execute_tool` spans in every mode but `none`.
 - **Sessions:** on Struct's provider, a `struct.agent(session_id=...)`
   around the run wins; otherwise pydantic-ai's `conversation_id` is used.
   Instrumentation configured on your own provider keeps its conversation IDs.
@@ -309,9 +308,10 @@ struct.init(
 )
 ```
 
-- **`EVENT_ONLY`**: per-message content lands on OTel log
-  records (`gen_ai.{user,assistant,system,tool}.message`,
-  `gen_ai.choice`). Spans carry metadata only.
+- **`EVENT_ONLY`**: each model call's content lands on one OTel log record,
+  `gen_ai.client.inference.operation.details` (input and output messages,
+  system instructions, tool definitions, as structured values). Spans carry
+  metadata only.
 - **`SPAN_ONLY`**: content on span attributes (`gen_ai.input.messages`,
   `gen_ai.output.messages`).
 - **`SPAN_AND_EVENT`**: both.

{struct_sdk-0.3.2 → struct_sdk-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.3.2"
+version = "0.4.2"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"

{struct_sdk-0.3.2 → struct_sdk-0.4.2}/src/struct_sdk/_genai_content.py

@@ -7,11 +7,8 @@ across providers once a message/response has been mapped to the spec's
 
 - Truncation constants + helpers (``truncate_field`` / ``truncate_parts`` /
   ``truncate_and_serialize`` / ``safe_json``).
-- The low-level per-message and choice LogRecord emitters
-  (``emit_message_event`` / ``emit_choice_event``) — they take already-built
-  ``parts`` and a ``provider`` string, so the OTel logs data-model wiring
-  (``body`` = event tag, ``attributes['body']`` = JSON payload, span-context
-  from the EXPLICIT span) lives in exactly one place.
+- (Message content leaves the SDK through ``_operation_details.record_content``:
+  span attributes, or one ``operation.details`` record per call.)
 - ``propagate_user_prompt_to_parent`` — write-once parent ``gen_ai.input.messages``
   from the last user message's parts.
 
@@ -31,11 +28,9 @@ import contextlib
 import json
 import logging
 import sys
-import time
 from typing import Any, Callable, Iterator, Optional
 from urllib.parse import urlparse
 
-from opentelemetry import trace
 from opentelemetry.trace import StatusCode
 
 from struct_sdk.core import _contain_logged
@@ -181,113 +176,6 @@ def safe_json(obj: Any) -> str:
         return "[]"
 
 
-# ---------------------------------------------------------------------------
-# LogRecord emission — OTel logs data model
-# ---------------------------------------------------------------------------
-
-def emit_message_event(
-    otel_logger: Any,
-    *,
-    role: str,
-    parts: list[dict[str, Any]],
-    event_name: str,
-    provider: str,
-    message_index: int,
-    span: Optional[trace.Span] = None,
-) -> None:
-    """Emit ONE per-message LogRecord linked to ``span``.
-
-    OTel logs data-model convention:
-    - ``body`` (log record body): the event tag (``gen_ai.user.message`` etc.).
-    - ``attributes['body']``: the JSON payload ``{"role": ..., "parts": [...]}``.
-    - Other attributes: ``event.name``, ``gen_ai.provider.name``,
-      ``gen_ai.message.index``, and ``gen_ai.conversation.id`` when a session is
-      active.
-
-    Span-context is taken from the EXPLICIT ``span`` when given —
-    ``trace.get_current_span()`` can drop the active span across the generator
-    wrapper's async awaits. All work is best-effort: a failure here NEVER
-    reaches the customer's call (it becomes a ``logger.debug``).
-    """
-    try:
-        from opentelemetry._logs import LogRecord, SeverityNumber
-
-        span_ctx = (span or trace.get_current_span()).get_span_context()
-        from struct_sdk.core import _current_session_id
-        session_id = _current_session_id.get(None)
-
-        payload = json.dumps({"role": role, "parts": truncate_parts(parts)}, default=str)
-        attrs: dict[str, Any] = {
-            "event.name": event_name,
-            "body": payload,
-            "gen_ai.provider.name": provider,
-            "gen_ai.message.index": message_index,
-        }
-        if session_id:
-            attrs["gen_ai.conversation.id"] = session_id
-
-        otel_logger.emit(LogRecord(
-            timestamp=int(time.time_ns()),
-            trace_id=span_ctx.trace_id,
-            span_id=span_ctx.span_id,
-            trace_flags=span_ctx.trace_flags,
-            severity_number=SeverityNumber.INFO,
-            body=event_name,
-            attributes=attrs,
-        ))
-    except Exception:
-        logger.debug("Failed to emit message event", exc_info=True)
-
-
-def emit_choice_event(
-    otel_logger: Any,
-    *,
-    parts: list[dict[str, Any]],
-    finish_reason: str,
-    provider: str,
-    span: Optional[trace.Span] = None,
-) -> None:
-    """Emit a ``gen_ai.choice`` LogRecord for the assistant's response.
-
-    ``parts`` are already spec-shaped assistant parts and ``finish_reason`` is
-    already mapped to the spec name by the caller (mapping is provider-specific).
-    The ``choice`` event omits ``gen_ai.message.index``.
-    """
-    try:
-        from opentelemetry._logs import LogRecord, SeverityNumber
-
-        span_ctx = (span or trace.get_current_span()).get_span_context()
-        from struct_sdk.core import _current_session_id
-        session_id = _current_session_id.get(None)
-
-        choice_body = {
-            "index": 0,
-            "finish_reason": finish_reason or "stop",
-            "message": {"role": "assistant", "parts": truncate_parts(parts)},
-        }
-        payload = json.dumps(choice_body, default=str)
-        event_name = "gen_ai.choice"
-        attrs: dict[str, Any] = {
-            "event.name": event_name,
-            "body": payload,
-            "gen_ai.provider.name": provider,
-        }
-        if session_id:
-            attrs["gen_ai.conversation.id"] = session_id
-
-        otel_logger.emit(LogRecord(
-            timestamp=int(time.time_ns()),
-            trace_id=span_ctx.trace_id,
-            span_id=span_ctx.span_id,
-            trace_flags=span_ctx.trace_flags,
-            severity_number=SeverityNumber.INFO,
-            body=event_name,
-            attributes=attrs,
-        ))
-    except Exception:
-        logger.debug("Failed to emit choice event", exc_info=True)
-
-
 # ---------------------------------------------------------------------------
 # Host-boundary span lifecycle
 # ---------------------------------------------------------------------------

struct_sdk-0.4.2/src/struct_sdk/_operation_details.py

@@ -0,0 +1,293 @@
+"""Message content as OTel's per-call ``gen_ai.client.inference.operation.details`` event.
+
+Anthropic, OpenAI and LangChain build a model call's content once (``gen_ai.input.messages``,
+``gen_ai.output.messages``, ``gen_ai.system_instructions``,
+``gen_ai.tool.definitions``) and hand each attribute to :func:`record_content`.
+The content mode decides where it goes (SDK-PY-11):
+
+- span modes (``span_only``, ``span_and_event``): on the ``chat`` span, as a capped
+  JSON string, as before;
+- event modes (``event_only``, ``span_and_event``): onto the ``chat`` span object
+  itself (a private attribute, never exported). When that span ends,
+  :class:`OperationDetailsProcessor` writes ONE
+  log record for the call (SDK-PY-45): linked to the span, severity DEBUG, with the
+  span's provider, models, response id, finish reasons, usage, ``error.type`` and
+  session, and the content as structured values (the conventions require structured
+  content on events).
+
+This replaces the deprecated one-record-per-message events (``gen_ai.user.message``
+... ``gen_ai.choice``). pydantic-ai's content attributes reach the same place from
+Struct's guarded tracer (SDK-PY-46). Nothing here may fault the host's call.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import threading
+import weakref
+from typing import Any, Optional
+
+from opentelemetry.sdk.trace import Span as SdkSpan
+from opentelemetry.sdk.trace import SpanProcessor
+from opentelemetry.trace import StatusCode
+
+from struct_sdk._genai_content import truncate_and_serialize
+from struct_sdk.core import _contain_logged
+
+logger = logging.getLogger("struct_sdk._operation_details")
+
+OPERATION_DETAILS_EVENT = "gen_ai.client.inference.operation.details"
+
+CONTENT_KEYS = frozenset({
+    "gen_ai.input.messages",
+    "gen_ai.output.messages",
+    "gen_ai.system_instructions",
+    "gen_ai.tool.definitions",
+})
+
+# Span attributes copied onto the event (the convention's non-content attributes).
+_SPAN_KEYS = (
+    "gen_ai.operation.name",
+    "gen_ai.provider.name",
+    "gen_ai.request.model",
+    "gen_ai.response.model",
+    "gen_ai.response.id",
+    "gen_ai.response.finish_reasons",
+    "gen_ai.conversation.id",
+    "gen_ai.request.max_tokens",
+    "gen_ai.request.temperature",
+    "gen_ai.request.top_p",
+    "gen_ai.request.top_k",
+    "gen_ai.request.stop_sequences",
+    "gen_ai.request.frequency_penalty",
+    "gen_ai.request.presence_penalty",
+    "gen_ai.output.type",
+    "server.address",
+    "server.port",
+    "error.type",
+)
+_USAGE_PREFIX = "gen_ai.usage."
+
+# A call's content lives on its own span object until the span ends, under this
+# private attribute (state about spans Struct creates lives on them; nothing global
+# holds content). It goes when the span goes: no eviction, no fork or shutdown cleanup.
+_CONTENT_ATTR = "_struct_operation_details"
+_lock = threading.Lock()  # buffering vs. the span's end, which may run on another thread
+
+
+def _reset_after_fork() -> None:
+    """A forked child gets a fresh lock: one another thread held at fork time would
+    otherwise stay locked in the child and hang its next model call."""
+    global _lock
+    _lock = threading.Lock()
+
+
+if hasattr(os, "register_at_fork"):
+    os.register_at_fork(after_in_child=_reset_after_fork)
+
+# opentelemetry-sdk 1.40+ hands processors the live span at ``_on_ending``, before
+# ``on_end`` gets a read-only copy. Older SDKs (the floor is 1.27) only call
+# ``on_end``, so there a weak index from span id to the live span (spans only,
+# never content) lets the processor find it.
+def _log_record_has_event_name() -> bool:
+    import inspect
+
+    from opentelemetry._logs import LogRecord
+
+    try:
+        return "event_name" in inspect.signature(LogRecord.__init__).parameters
+    except (TypeError, ValueError):
+        return False
+
+
+# opentelemetry-sdk releases before LogRecord took ``event_name`` export only body and attributes.
+_LOG_RECORD_HAS_EVENT_NAME = _log_record_has_event_name()
+_ENDING_HOOK = "_on_ending" in getattr(getattr(SdkSpan.end, "__code__", None), "co_names", ())
+_live_spans: "weakref.WeakValueDictionary[tuple[int, int], Any]" = weakref.WeakValueDictionary()
+
+
+def _span_key(span: Any) -> Optional[tuple[int, int]]:
+    context = span.get_span_context()
+    if not context or not context.is_valid:
+        return None
+    return (context.trace_id, context.span_id)
+
+
+_INT64_MIN, _INT64_MAX = -(2**63), 2**63 - 1
+
+
+def _encodable(value: Any) -> Any:
+    """``value`` with what an OTLP AnyValue cannot hold made lossless: an integer
+    outside int64 becomes its decimal string, a string with a lone surrogate its
+    JSON escape. Nulls stay."""
+    if isinstance(value, bool) or value is None or isinstance(value, float):
+        return value
+    if isinstance(value, int):
+        return value if _INT64_MIN <= value <= _INT64_MAX else str(value)
+    if isinstance(value, str):
+        try:
+            value.encode("utf-8")
+        except UnicodeEncodeError:
+            return json.dumps(value)[1:-1]
+        return value
+    if isinstance(value, list):
+        return [_encodable(item) for item in value]
+    if isinstance(value, dict):
+        # Escaping a key could merge it with a key already spelled that way: keep such
+        # an object whole, as escaped JSON text (the messages around it stay structured).
+        if any(isinstance(k, str) and _encodable(k) != k for k in value):
+            return json.dumps(value)
+        return {k if isinstance(k, str) else str(k): _encodable(v) for k, v in value.items()}
+    return value
+
+
+def _structured(value: Any) -> Any:
+    """``value`` (a JSON string or a structure) as plain lists, dicts and scalars,
+    capped like span content (16,384 characters per message-part field or top-level
+    system content; 128 KiB per attribute, including tool definitions; valid JSON)
+    and encodable as OTLP AnyValues (``_encodable``). ``null`` values are kept: tool
+    arguments and schemas carry them, and the OTel log encoder accepts them."""
+    if isinstance(value, str):
+        value = json.loads(value)
+    structured = _encodable(json.loads(truncate_and_serialize(value)))
+    # Encoding can grow a value (a large integer becomes a quoted string): cap again.
+    return json.loads(truncate_and_serialize(structured))
+
+
+def _sdk_span(span: Any) -> Any:
+    """The OTel SDK span under Struct's pydantic-ai guard, or ``span`` itself."""
+    return getattr(span, "_span", span)
+
+
+def buffer_content(span: Any, key: str, value: Any) -> None:
+    """Keep ``value`` on the span for the call's ``operation.details`` event."""
+
+    def buffer() -> None:
+        target = _sdk_span(span)
+        # A sampled-out (non-recording) span never reaches a processor: nothing to keep.
+        if value is None or not target.is_recording():
+            return
+        structured = _structured(value)
+        with _lock:
+            content = getattr(target, _CONTENT_ATTR, None)
+            if content is None:
+                content = {}
+                setattr(target, _CONTENT_ATTR, content)
+                if not _ENDING_HOOK:
+                    span_key = _span_key(target)
+                    if span_key is not None:
+                        _live_spans[span_key] = target
+            content[key] = structured
+
+    _contain_logged(buffer, site="operation_details.buffer")
+
+
+def _take_content(live_span: Any) -> Optional[dict[str, Any]]:
+    with _lock:
+        content = getattr(live_span, _CONTENT_ATTR, None)
+        if content is not None:
+            setattr(live_span, _CONTENT_ATTR, None)
+        return content
+
+
+def record_content(sdk: Any, span: Any, key: str, value: Any) -> None:
+    """Route one content attribute of a model call by the content mode (SDK-PY-11).
+
+    ``value`` is the capped JSON string the span would carry, or the structure."""
+    if value is None:
+        return
+    if sdk.emit_span_content:
+        _contain_logged(
+            lambda: span.set_attribute(key, value if isinstance(value, str) else truncate_and_serialize(value)),
+            site="operation_details.span_content",
+        )
+    if sdk.emit_events:
+        buffer_content(span, key, value)
+
+
+class OperationDetailsProcessor(SpanProcessor):
+    """Writes a call's ``operation.details`` event when its span ends (SDK-PY-45).
+
+    Only spans carrying content produce an event; content is kept only in event
+    modes. Runs inside the OTel SDK's span end, so nothing may escape."""
+
+    def __init__(self, sdk: Any) -> None:
+        self._sdk = sdk
+
+    def on_start(self, span: Any, parent_context: Any = None) -> None:
+        pass
+
+    def _on_ending(self, span: Any) -> None:
+        # The live span, ended (end time and status final), before on_end's copy.
+        if _ENDING_HOOK:
+            _contain_logged(lambda: self._emit(span, _take_content(span)), site="operation_details.emit")
+
+    def on_end(self, span: Any) -> None:
+        if _ENDING_HOOK:
+            return
+
+        def emit() -> None:
+            span_key = _span_key(span)
+            live = _live_spans.pop(span_key, None) if span_key is not None else None
+            if live is not None:
+                self._emit(span, _take_content(live))
+
+        _contain_logged(emit, site="operation_details.emit")
+
+    def _emit(self, span: Any, content: Optional[dict[str, Any]]) -> None:
+        # A record needs the call's messages: tool definitions alone (a failed
+        # pydantic-ai request, whose messages pydantic-ai never wrote) say nothing.
+        if not content or not self._sdk.emit_events or not (
+            "gen_ai.input.messages" in content or "gen_ai.output.messages" in content
+        ):
+            return
+        from opentelemetry._logs import LogRecord, SeverityNumber
+
+        span_attributes = dict(span.attributes or {})
+        attributes: dict[str, Any] = {"event.name": OPERATION_DETAILS_EVENT}
+        for key in _SPAN_KEYS:
+            if key in span_attributes:
+                value = span_attributes[key]
+                attributes[key] = list(value) if isinstance(value, tuple) else value
+        for key, value in span_attributes.items():
+            if key.startswith(_USAGE_PREFIX):
+                attributes[key] = value
+        attributes.setdefault("gen_ai.operation.name", "chat")
+        status = getattr(span, "status", None)
+        if status is not None and status.status_code == StatusCode.ERROR:
+            attributes.setdefault("error.type", _error_type(span, status))
+        attributes.update(content)
+
+        context = span.get_span_context()
+        record: dict[str, Any] = {
+            "timestamp": span.end_time,
+            "trace_id": context.trace_id,
+            "span_id": context.span_id,
+            "trace_flags": context.trace_flags,
+            "severity_text": "DEBUG",
+            "severity_number": SeverityNumber.DEBUG,
+            "body": OPERATION_DETAILS_EVENT,  # Struct's readers match the body
+            "attributes": attributes,
+        }
+        if _LOG_RECORD_HAS_EVENT_NAME:  # the OTLP event name the conventions require
+            record["event_name"] = OPERATION_DETAILS_EVENT
+        self._sdk.get_logger("struct-sdk").emit(LogRecord(**record))
+
+    def shutdown(self) -> None:
+        pass
+
+    def force_flush(self, timeout_millis: int = 30000) -> bool:
+        return True
+
+
+def _error_type(span: Any, status: Any) -> str:
+    """The exception type recorded on the span, else ``_OTHER`` (the convention's
+    fallback when the error class is unknown)."""
+    for event in reversed(getattr(span, "events", None) or ()):
+        if event.name == "exception":
+            error_type = (event.attributes or {}).get("exception.type")
+            if error_type:
+                return str(error_type)
+    return "_OTHER"