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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: struct-sdk
-Version: 0.4.15
+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
@@ -900,9 +900,14 @@ them.
 ### Datadog ddtrace
 
 Under `ddtrace-run`, Struct leaves the libraries ddtrace patches to it, and
-`urllib3` beneath `requests` or `botocore` (and `aiobotocore` when ddtrace
-patches `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
+`urllib3` beneath `requests` or `botocore`, to avoid duplicate spans and
+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.15 → struct_sdk-0.4.16}/README.md

@@ -784,9 +784,14 @@ them.
 ### Datadog ddtrace
 
 Under `ddtrace-run`, Struct leaves the libraries ddtrace patches to it, and
-`urllib3` beneath `requests` or `botocore` (and `aiobotocore` when ddtrace
-patches `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
+`urllib3` beneath `requests` or `botocore`, to avoid duplicate spans and
+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.15 → struct_sdk-0.4.16}/pyproject.toml

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

{struct_sdk-0.4.15 → 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,10 +133,39 @@ _DDTRACE_INTEGRATIONS = {
 }
 
 # Transports beneath clients ddtrace patches: instrumenting one would overwrite
-# the traceparent ddtrace wrote on the same request. contrib's aiobotocore
-# instrumentor also wraps botocore's Endpoint.prepare_request, so it would write
-# Struct's X-Ray header on every botocore request ddtrace traces.
-_TRANSPORT_BENEATH = {"urllib3": ("requests", "botocore"), "aiobotocore": ("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"
@@ -305,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:
@@ -325,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.
@@ -348,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
@@ -385,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
@@ -393,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:
@@ -413,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: