struct-sdk 0.4.14__tar.gz → 0.4.16__tar.gz

{struct_sdk-0.4.14 → struct_sdk-0.4.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: struct-sdk
-Version: 0.4.14
+Version: 0.4.16
 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
@@ -862,6 +862,12 @@ before `init()`, call the contrib instrumentor directly (for example
 | Logs | Python `logging` records that reach the root logger, with trace context. The SDK's own and OpenTelemetry's records are excluded. With the `[structlog]` extra, structlog events that structlog writes itself (its default) are exported with their fields as attributes; events structlog hands to `logging` (`structlog.stdlib.LoggerFactory`) are exported once, through the `logging` bridge. Extras and structlog fields OpenTelemetry can't take as-is are exported as strings: dicts and mixed-type lists as JSON, everything else (UUIDs, datetimes, `None`, bytes) as its `str()`. Your other handlers still see the original values. With the `[exceptions]` extra, uncaught exceptions (main thread, other threads, asyncio) are exported as log records. If your app configures no logging, its warnings still print to stderr as they would without Struct. This is separate from `content_capture`, which only governs LLM content; disable `{"logging": {"enabled": False}}` and `{"structlog": {"enabled": False}}` (which also stops copies of your logs when Struct attaches to your OpenTelemetry setup), or redact attributes, if application logs can carry sensitive data. |
 | Metrics | Instrumentor metrics (for example `http.server.duration`) and process metrics (`process.cpu.*`, `process.memory.*`, threads, file descriptors, GC). Counters and histograms use delta temporality. |
 
+AWS calls through boto3/botocore or aiobotocore become one span per API
+operation (for example `S3.PutObject`), retries included, and carry the X-Ray
+header AWS services propagate. When Struct attaches to your existing
+OpenTelemetry setup, it instruments nothing, so AWS operation spans reach
+Struct only if your setup instruments botocore itself.
+
 Each instrumentor activates only when its library is installed.
 `instrumentation_options` disables or configures one by name; other keys are
 passed to that instrumentor:
@@ -895,7 +901,13 @@ them.
 
 Under `ddtrace-run`, Struct leaves the libraries ddtrace patches to it, and
 `urllib3` beneath `requests` or `botocore`, to avoid duplicate spans and
-conflicting trace headers, and logs one INFO line listing them. Logs, process metrics, thread context, AI spans and libraries
+conflicting trace headers, and logs one INFO line listing them. AWS clients
+are the exception: Struct still records every botocore and aiobotocore
+operation, and the AWS instrumentors it turns on propagate nothing (no trace
+header, nothing in SNS message attributes or Lambda payloads), so Datadog's
+propagation is unchanged. An AWS instrumentor your own setup turns on keeps its
+propagator, and because both clients share botocore's request hook, its HTTP
+headers reach the other client's requests too. Logs, process metrics, thread context, AI spans and libraries
 ddtrace doesn't patch still go to Struct. With `DD_TRACE_OTEL_ENABLED=true`,
 ddtrace's OpenTelemetry provider isn't the OpenTelemetry SDK, so full-app
 mode attaches nothing (an INFO line says so) and only AI spans reach Struct.

{struct_sdk-0.4.14 → struct_sdk-0.4.16}/README.md

@@ -746,6 +746,12 @@ before `init()`, call the contrib instrumentor directly (for example
 | Logs | Python `logging` records that reach the root logger, with trace context. The SDK's own and OpenTelemetry's records are excluded. With the `[structlog]` extra, structlog events that structlog writes itself (its default) are exported with their fields as attributes; events structlog hands to `logging` (`structlog.stdlib.LoggerFactory`) are exported once, through the `logging` bridge. Extras and structlog fields OpenTelemetry can't take as-is are exported as strings: dicts and mixed-type lists as JSON, everything else (UUIDs, datetimes, `None`, bytes) as its `str()`. Your other handlers still see the original values. With the `[exceptions]` extra, uncaught exceptions (main thread, other threads, asyncio) are exported as log records. If your app configures no logging, its warnings still print to stderr as they would without Struct. This is separate from `content_capture`, which only governs LLM content; disable `{"logging": {"enabled": False}}` and `{"structlog": {"enabled": False}}` (which also stops copies of your logs when Struct attaches to your OpenTelemetry setup), or redact attributes, if application logs can carry sensitive data. |
 | Metrics | Instrumentor metrics (for example `http.server.duration`) and process metrics (`process.cpu.*`, `process.memory.*`, threads, file descriptors, GC). Counters and histograms use delta temporality. |
 
+AWS calls through boto3/botocore or aiobotocore become one span per API
+operation (for example `S3.PutObject`), retries included, and carry the X-Ray
+header AWS services propagate. When Struct attaches to your existing
+OpenTelemetry setup, it instruments nothing, so AWS operation spans reach
+Struct only if your setup instruments botocore itself.
+
 Each instrumentor activates only when its library is installed.
 `instrumentation_options` disables or configures one by name; other keys are
 passed to that instrumentor:
@@ -779,7 +785,13 @@ them.
 
 Under `ddtrace-run`, Struct leaves the libraries ddtrace patches to it, and
 `urllib3` beneath `requests` or `botocore`, to avoid duplicate spans and
-conflicting trace headers, and logs one INFO line listing them. Logs, process metrics, thread context, AI spans and libraries
+conflicting trace headers, and logs one INFO line listing them. AWS clients
+are the exception: Struct still records every botocore and aiobotocore
+operation, and the AWS instrumentors it turns on propagate nothing (no trace
+header, nothing in SNS message attributes or Lambda payloads), so Datadog's
+propagation is unchanged. An AWS instrumentor your own setup turns on keeps its
+propagator, and because both clients share botocore's request hook, its HTTP
+headers reach the other client's requests too. Logs, process metrics, thread context, AI spans and libraries
 ddtrace doesn't patch still go to Struct. With `DD_TRACE_OTEL_ENABLED=true`,
 ddtrace's OpenTelemetry provider isn't the OpenTelemetry SDK, so full-app
 mode attaches nothing (an INFO line says so) and only AI spans reach Struct.

{struct_sdk-0.4.14 → struct_sdk-0.4.16}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.4.14"
+version = "0.4.16"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -218,6 +218,15 @@ dev = [
     "google-cloud-bigquery>=3.30.0",
     "opentelemetry-instrumentation-grpc",
     "opentelemetry-propagator-b3",
+    # AWS client-operation suite (tests/test_aws_client_operations.py): real
+    # boto3 and aiobotocore clients, contrib's botocore instrumentor and the
+    # transport instrumentors beneath them (urllib3, aiohttp-client), against
+    # a local endpoint.
+    "boto3",
+    "aiobotocore",
+    "opentelemetry-instrumentation-botocore",
+    "opentelemetry-instrumentation-urllib3",
+    "opentelemetry-instrumentation-aiohttp-client",
 ]
 # The openai<3 suites: `uv run --no-default-groups --group openai2 pytest
 # tests/test_litellm.py tests/test_llamaindex.py` (pnpm run test:openai2).

{struct_sdk-0.4.14 → struct_sdk-0.4.16}/src/struct_sdk/_auto.py

@@ -32,7 +32,8 @@ from importlib.metadata import PackageNotFoundError, entry_points, version
 from typing import TYPE_CHECKING, Any, Callable, Mapping, Optional
 
 from opentelemetry import _logs, context, metrics, trace
-from opentelemetry.context import _SUPPRESS_INSTRUMENTATION_KEY
+from opentelemetry.context import _SUPPRESS_INSTRUMENTATION_KEY, Context
+from opentelemetry.propagators.textmap import TextMapPropagator
 from opentelemetry.sdk._logs import LoggerProvider, LogRecordProcessor
 from opentelemetry.sdk.metrics import MeterProvider
 from opentelemetry.sdk.trace import SpanProcessor, TracerProvider
@@ -132,8 +133,39 @@ _DDTRACE_INTEGRATIONS = {
 }
 
 # Transports beneath clients ddtrace patches: instrumenting one would overwrite
-# the traceparent ddtrace wrote on the same request.
-_TRANSPORT_BENEATH = {"urllib3": ("requests", "botocore")}
+# the traceparent ddtrace wrote on the same request. contrib's botocore and
+# aiobotocore instrumentors both write their X-Ray header in botocore's shared
+# Endpoint.prepare_request, so either one touches the other's requests.
+_TRANSPORT_BENEATH = {
+    "urllib3": ("requests", "botocore"),
+    "aiobotocore": ("botocore",),
+    "botocore": ("aiobotocore",),
+}
+
+# Next to ddtrace these still record spans but propagate nothing, so Datadog's
+# context stays the only one the request carries.
+_QUIET_NEXT_TO_DDTRACE = frozenset({"botocore", "aiobotocore"})
+
+# Services whose contrib extensions write the global propagator's context into
+# the Lambda Invoke payload or SNS message attributes in before_service_call,
+# outside the instrumentor's propagator; that is all their before_service_call
+# does.
+_AWS_MESSAGE_PROPAGATING_SERVICES = frozenset({"lambda", "sns"})
+
+
+class _NoPropagation(TextMapPropagator):
+    """Writes nothing and reads nothing: a quiet AWS instrumentor's fallback when
+    contrib's request hook is not where ``instrument()`` puts it."""
+
+    def extract(self, carrier: Any, context: Optional[Context] = None, getter: Any = None) -> Context:
+        return context if context is not None else Context()
+
+    def inject(self, carrier: Any, context: Optional[Context] = None, setter: Any = None) -> None:
+        pass
+
+    @property
+    def fields(self) -> set[str]:
+        return set()
 
 # Non-entry-point options handled here rather than by a contrib instrumentor.
 LOGGING = "logging"
@@ -303,18 +335,24 @@ def _instrument_libraries(
     available = {ep.name: ep for ep in _instrumentor_entry_points()}
     ddtrace_owned = _ddtrace_instrumented()
     left_to_ddtrace = []
+    beside_ddtrace: list[str] = []
     for name in SUPPORTED_INSTRUMENTATIONS:
         entry_point = available.get(name)
         if entry_point is None or not _enabled(options, name):
             continue
-        if _left_to_ddtrace(name, ddtrace_owned):
+        owned_by_ddtrace = _left_to_ddtrace(name, ddtrace_owned)
+        if owned_by_ddtrace and name not in _QUIET_NEXT_TO_DDTRACE:
             if _target_installed(entry_point):
                 left_to_ddtrace.append(name)
             continue
         kwargs = {k: v for k, v in options.get(name, {}).items() if k != "enabled"}
+        # A propagator the app chose wins, and so does its propagation.
+        quiet = owned_by_ddtrace and "propagator" not in kwargs
 
-        def instrument(ep: Any = entry_point, kw: dict[str, Any] = kwargs) -> None:
-            _instrument_one(ep, tracer_provider, meter_provider, kw)
+        def instrument(ep: Any = entry_point, kw: dict[str, Any] = kwargs, q: bool = quiet) -> None:
+            # Reported only once Struct turned it on: a host's own instrumentor is kept as it is.
+            if _instrument_one(ep, tracer_provider, meter_provider, kw, quiet=q) and q:
+                beside_ddtrace.append(ep.name)
 
         _safe(instrument, site=f"auto.instrument.{name}")
     if left_to_ddtrace:
@@ -323,6 +361,28 @@ def _instrument_libraries(
             "them, to avoid duplicate spans and conflicting trace headers.",
             ", ".join(sorted(left_to_ddtrace)),
         )
+    # contrib's two AWS instrumentors share botocore's request hook, so another
+    # one that propagates, with an app-set propagator or the host's own, also
+    # writes the quiet client's HTTP headers.
+    propagating = [
+        name for name in sorted(_QUIET_NEXT_TO_DDTRACE - set(beside_ddtrace))
+        if beside_ddtrace and _aws_instrumentor_propagates(available.get(name))
+    ]
+    if propagating:
+        logger.info(
+            "Struct traces %s alongside Datadog ddtrace without writing its trace context into "
+            "SNS message attributes or Lambda payloads; its HTTP requests carry the headers %s's "
+            "instrumentor writes through the request hook they share.",
+            ", ".join(sorted(beside_ddtrace)),
+            ", ".join(propagating),
+        )
+    elif beside_ddtrace:
+        logger.info(
+            "Struct traces %s alongside Datadog ddtrace without propagating its trace context "
+            "(HTTP headers, SNS message attributes, Lambda payloads); a propagator in "
+            "instrumentation_options turns it back on.",
+            ", ".join(sorted(beside_ddtrace)),
+        )
 
 
 # The module a GenAI integration patches, where it differs from the integration's name.
@@ -346,6 +406,75 @@ def _genai_installed(name: str) -> bool:
         return False
 
 
+def _aws_instrumentor_propagates(entry_point: Any) -> bool:
+    """Whether this AWS instrumentor, not one Struct turned on quietly, is on
+    with a propagator that writes headers."""
+    if entry_point is None or not _target_installed(entry_point):
+        return False
+    try:
+        instrumentor_class = entry_point.load()
+    except Exception:
+        return False
+    instrumentor = instrumentor_class.__new__(instrumentor_class)
+    return bool(instrumentor.is_instrumented_by_opentelemetry) and bool(
+        getattr(getattr(instrumentor, "propagator", None), "fields", ())
+    )
+
+
+def _skip_before_service_call(*args: Any, **kwargs: Any) -> None:
+    pass
+
+
+def _quiet_aws_instrumentor(instrumentor: Any) -> None:
+    """Make an AWS instrumentor Struct just turned on propagate nothing.
+
+    contrib's request hook on botocore's shared ``Endpoint.prepare_request``
+    only writes the X-Ray header, so it is removed: it is the outermost layer,
+    just added by ``instrument()``. The instrumentor's own propagator is left
+    as it is, so nothing has to be restored later and no hook can be left
+    using a removed one. If the hook is not there, a propagator that writes
+    nothing is the fallback.
+
+    Its Lambda and SNS extensions skip before_service_call, which only writes
+    context into the payload or message attributes: the payload goes out as the
+    app wrote it, and nothing is logged about attribute limits. Only this
+    instrumentor's own registry changes, so the other AWS client, the host's
+    global propagator, and a later instrument() (which builds a new registry)
+    are untouched."""
+    import wrapt
+    from botocore.endpoint import Endpoint  # type: ignore[import-untyped]
+
+    hook = Endpoint.__dict__.get("prepare_request")
+    if isinstance(hook, wrapt.FunctionWrapper) and getattr(hook._self_wrapper, "__self__", None) is instrumentor:
+        Endpoint.prepare_request = hook.__wrapped__
+    else:
+        instrumentor.propagator = _NoPropagation()
+
+    registry = instrumentor.extension_registry
+    get_extension = registry.get_extension
+
+    def quiet_get_extension(call_context: Any) -> Any:
+        extension = get_extension(call_context)
+        if call_context.service in _AWS_MESSAGE_PROPAGATING_SERVICES:
+            extension.before_service_call = _skip_before_service_call
+        return extension
+
+    registry.get_extension = quiet_get_extension
+    uninstrument = instrumentor.uninstrument
+
+    def uninstrument_keeping_request_hooks(**kwargs: Any) -> Any:
+        kept = Endpoint.__dict__.get("prepare_request")
+        try:
+            return uninstrument(**kwargs)
+        finally:
+            instrumentor.__dict__.pop("uninstrument", None)
+            # contrib's uninstrument() unwraps the outermost request hook, and
+            # this instrumentor no longer has one: put back what was there.
+            Endpoint.prepare_request = kept
+
+    instrumentor.uninstrument = uninstrument_keeping_request_hooks
+
+
 def _left_to_ddtrace(name: str, ddtrace_owned: set[str]) -> bool:
     if name in _NOT_SPAN_INSTRUMENTATIONS or not ddtrace_owned:
         return False
@@ -383,7 +512,9 @@ def _instrument_one(
     tracer_provider: TracerProvider,
     meter_provider: MeterProvider,
     kwargs: dict[str, Any],
-) -> None:
+    quiet: bool = False,
+) -> bool:
+    """Whether Struct turned the instrumentor on."""
     from opentelemetry.instrumentation.dependencies import get_dist_dependency_conflicts
 
     # Checked before loading: BaseInstrumentor logs a missing target library at
@@ -391,13 +522,13 @@ def _instrument_one(
     conflict = get_dist_dependency_conflicts(entry_point.dist)
     if conflict is not None:
         logger.debug("Skipping %s instrumentation: %s", entry_point.name, conflict)
-        return
+        return False
     instrumentor_class = entry_point.load()
     # Instrumentors are singletons whose constructor resets their config; check
     # the shared instance before re-initializing one the host already owns.
     instrumentor = instrumentor_class.__new__(instrumentor_class)
     if instrumentor.is_instrumented_by_opentelemetry:
-        return
+        return False
     if entry_point.name == "system_metrics":
         instrumentor.__init__(config=_process_metrics_config())
     else:
@@ -411,8 +542,11 @@ def _instrument_one(
     if entry_point.name == "structlog" and not _guard_structlog_processor(instrumentor_class):
         instrumentor.uninstrument()
         logger.debug("Skipping structlog instrumentation: processor not found")
-        return
+        return False
+    if quiet:
+        _quiet_aws_instrumentor(instrumentor)
     logger.info("Auto-instrumented: %s", entry_point.name)
+    return True
 
 
 def _guard_structlog_processor(instrumentor_class: Any) -> bool: