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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: struct-sdk
-Version: 0.4.13
+Version: 0.4.15
 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:
@@ -894,8 +900,9 @@ them.
 ### Datadog ddtrace
 
 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
+`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
 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.
@@ -948,6 +955,40 @@ Temporal server metrics are a Prometheus endpoint; scrape them with an
 OpenTelemetry Collector and export OTLP/HTTP to your Struct ingest endpoint
 with the `x-struct-ingest-key` header.
 
+### Google Cloud clients
+
+```python
+from struct_sdk import gcp, struct
+
+struct.init(ingest_key="pk-...", service_name="monitor-worker")
+gcp.instrument()  # once at startup, before creating Google clients
+```
+
+Released gRPC Google clients (Cloud Logging, Cloud Monitoring, Secret Manager,
+Pub/Sub admin and the other generated libraries) emit no OpenTelemetry spans.
+`gcp.instrument()` (no extra needed) gives each unary RPC attempt one CLIENT
+span, `google.monitoring.v3.MetricService/ListTimeSeries`, with `rpc.service`,
+`rpc.method`, `rpc.grpc.status_code` and `server.address`; a retried call shows
+one span per attempt. Streaming RPCs are passed through untouched. Your
+metadata keeps repeated keys; the trace headers of your configured
+propagator replace any copies of its fields, and trace fields gRPC would
+reject are dropped. A failure in Struct's tracing never affects the call. Spans go to the global tracer provider (Struct's, or yours
+when Struct attaches to your OpenTelemetry setup, so your exporter gets them
+too), or to `tracer_provider=` if you pass one. Channels already traced by
+contrib's gRPC instrumentor keep its provider and behavior. `struct.init()` never calls it
+for you. Clients created before the call, and transports you give your own
+`channel`, are left alone. `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=gcp` turns it
+off and `OTEL_PYTHON_GRPC_EXCLUDED_SERVICES` excludes services; under a ddtrace
+that patches `grpc` it steps aside.
+
+Other Google libraries trace themselves: `google-cloud-bigquery` emits its own
+`BigQuery.*` spans whenever `opentelemetry-instrumentation` is installed (its
+`path` and `db.name` attributes carry project, dataset and table names, never
+query text). `google-cloud-storage` needs `ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True`
+set before it is imported, and the Pub/Sub publisher and subscriber need
+`enable_open_telemetry_tracing=True` in their options. `google-api-python-client`
+(discovery) calls get only the HTTP spans of an instrumented transport.
+
 ## Reliability
 
 The SDK is designed never to break your application. Instrumentation

{struct_sdk-0.4.13 → struct_sdk-0.4.15}/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:
@@ -778,8 +784,9 @@ them.
 ### Datadog ddtrace
 
 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
+`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
 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.
@@ -832,6 +839,40 @@ Temporal server metrics are a Prometheus endpoint; scrape them with an
 OpenTelemetry Collector and export OTLP/HTTP to your Struct ingest endpoint
 with the `x-struct-ingest-key` header.
 
+### Google Cloud clients
+
+```python
+from struct_sdk import gcp, struct
+
+struct.init(ingest_key="pk-...", service_name="monitor-worker")
+gcp.instrument()  # once at startup, before creating Google clients
+```
+
+Released gRPC Google clients (Cloud Logging, Cloud Monitoring, Secret Manager,
+Pub/Sub admin and the other generated libraries) emit no OpenTelemetry spans.
+`gcp.instrument()` (no extra needed) gives each unary RPC attempt one CLIENT
+span, `google.monitoring.v3.MetricService/ListTimeSeries`, with `rpc.service`,
+`rpc.method`, `rpc.grpc.status_code` and `server.address`; a retried call shows
+one span per attempt. Streaming RPCs are passed through untouched. Your
+metadata keeps repeated keys; the trace headers of your configured
+propagator replace any copies of its fields, and trace fields gRPC would
+reject are dropped. A failure in Struct's tracing never affects the call. Spans go to the global tracer provider (Struct's, or yours
+when Struct attaches to your OpenTelemetry setup, so your exporter gets them
+too), or to `tracer_provider=` if you pass one. Channels already traced by
+contrib's gRPC instrumentor keep its provider and behavior. `struct.init()` never calls it
+for you. Clients created before the call, and transports you give your own
+`channel`, are left alone. `OTEL_PYTHON_DISABLED_INSTRUMENTATIONS=gcp` turns it
+off and `OTEL_PYTHON_GRPC_EXCLUDED_SERVICES` excludes services; under a ddtrace
+that patches `grpc` it steps aside.
+
+Other Google libraries trace themselves: `google-cloud-bigquery` emits its own
+`BigQuery.*` spans whenever `opentelemetry-instrumentation` is installed (its
+`path` and `db.name` attributes carry project, dataset and table names, never
+query text). `google-cloud-storage` needs `ENABLE_GCS_PYTHON_CLIENT_OTEL_TRACES=True`
+set before it is imported, and the Pub/Sub publisher and subscriber need
+`enable_open_telemetry_tracing=True` in their options. `google-api-python-client`
+(discovery) calls get only the HTTP spans of an instrumented transport.
+
 ## Reliability
 
 The SDK is designed never to break your application. Instrumentation

{struct_sdk-0.4.13 → struct_sdk-0.4.15}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.4.13"
+version = "0.4.15"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -211,6 +211,22 @@ dev = [
     # runs over a transport-mocked OpenAI client.
     "autogen-agentchat>=0.7.0",
     "autogen-ext[openai]>=0.7.0",
+    # Google Cloud suite (tests/test_gcp.py): real GAPIC gRPC and BigQuery
+    # REST clients against in-process fake services, next to contrib's gRPC
+    # instrumentor that gcp.instrument() defers to.
+    "google-cloud-monitoring>=2.29.1",
+    "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).
@@ -254,7 +270,7 @@ markers = [
 
 [tool.mypy]
 [[tool.mypy.overrides]]
-module = ["agents", "agents.*", "anthropic", "anthropic.*", "pydantic_ai", "pydantic_ai.*", "claude_agent_sdk", "claude_agent_sdk.*", "langchain_core", "langchain_core.*", "langchain", "langchain.*", "langgraph", "langgraph.*", "openai", "openai.*", "opentelemetry.instrumentation.*", "azure.core.*", "temporalio", "temporalio.*", "requests", "requests.*", "opentelemetry.resource.*", "ddtrace", "ddtrace.*", "wrapt", "wrapt.*", "mcp", "mcp.*", "google.genai", "google.genai.*", "google.adk", "google.adk.*", "litellm", "litellm.*", "llama_index", "llama_index.*", "crewai", "crewai.*", "autogen_core", "autogen_core.*", "autogen_ext", "autogen_ext.*", "autogen_agentchat", "autogen_agentchat.*", "autogen", "autogen.*", "ag2", "ag2.*"]
+module = ["agents", "agents.*", "anthropic", "anthropic.*", "pydantic_ai", "pydantic_ai.*", "claude_agent_sdk", "claude_agent_sdk.*", "langchain_core", "langchain_core.*", "langchain", "langchain.*", "langgraph", "langgraph.*", "openai", "openai.*", "opentelemetry.instrumentation.*", "azure.core.*", "temporalio", "temporalio.*", "requests", "requests.*", "opentelemetry.resource.*", "ddtrace", "ddtrace.*", "wrapt", "wrapt.*", "mcp", "mcp.*", "google.genai", "google.genai.*", "google.adk", "google.adk.*", "litellm", "litellm.*", "llama_index", "llama_index.*", "crewai", "crewai.*", "autogen_core", "autogen_core.*", "autogen_ext", "autogen_ext.*", "autogen_agentchat", "autogen_agentchat.*", "autogen", "autogen.*", "ag2", "ag2.*", "grpc", "grpc.*"]
 ignore_missing_imports = true
 
 [tool.hatch.build.targets.wheel]

{struct_sdk-0.4.13 → struct_sdk-0.4.15}/src/struct_sdk/_auto.py

@@ -132,8 +132,10 @@ _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 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",)}
 
 # Non-entry-point options handled here rather than by a contrib instrumentor.
 LOGGING = "logging"

struct_sdk-0.4.15/src/struct_sdk/gcp.py

@@ -0,0 +1,477 @@
+"""Google Cloud client operations traced with OpenTelemetry.
+
+Usage::
+
+    from struct_sdk import gcp, struct
+
+    struct.init(ingest_key="pk-...", service_name="monitor-worker")
+    gcp.instrument()  # once at startup, before the app creates Google clients
+
+Google's generated gRPC clients (Cloud Logging, Cloud Monitoring, Secret
+Manager, Pub/Sub's admin clients and the rest of the GAPIC libraries) emit no
+OpenTelemetry spans of their own in their released versions. ``instrument()``
+gives every unary RPC attempt on a channel Google's
+``grpc_helpers.create_channel`` builds from then on one CLIENT span, the layer
+``google-api-core[tracing]`` calls an attempt span. Streaming RPCs pass
+through untouched. Spans go to the global tracer provider unless one is
+passed: Struct's in owned mode, the host's in attach mode, where Struct's
+attached exporter copies them.
+
+google-cloud-bigquery traces its own operations whenever
+``opentelemetry-instrumentation`` is importable and needs nothing here.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import collections
+import functools
+import importlib
+import logging
+import os
+import re
+import sys
+import threading
+from typing import TYPE_CHECKING, Any, Callable, Optional
+
+from struct_sdk import _auto
+from struct_sdk.core import _SDK_VERSION, _contain_logged
+
+if TYPE_CHECKING:
+    from opentelemetry.trace import Span, Tracer, TracerProvider
+
+logger = logging.getLogger("struct_sdk.gcp")
+
+# This integration's name in OTEL_PYTHON_DISABLED_INSTRUMENTATIONS.
+NAME = "gcp"
+# Contrib's gRPC exclusion list, read the same way.
+OTEL_PYTHON_GRPC_EXCLUDED_SERVICES = "OTEL_PYTHON_GRPC_EXCLUDED_SERVICES"
+
+_CHANNEL_MODULES = ("google.api_core.grpc_helpers", "google.api_core.grpc_helpers_async")
+
+_lock = threading.Lock()
+# The create_channel wrapper Struct installed, per module, compared by
+# identity: a host decorator built with functools.wraps copies its attributes.
+_installed: dict[str, Callable[..., Any]] = {}
+
+# What gRPC accepts as a metadata key: lower-case token characters.
+_METADATA_KEY = re.compile(r"[0-9a-z_.\-]+\Z")
+# Every header B3 propagators read, multi-header and single-header alike: a
+# propagator's ``fields`` names only those it writes.
+_B3_HEADERS = frozenset(
+    {"b3", "x-b3-traceid", "x-b3-spanid", "x-b3-parentspanid", "x-b3-sampled", "x-b3-flags"}
+)
+
+
+def instrument(*, tracer_provider: Optional["TracerProvider"] = None) -> bool:
+    """Trace the unary RPCs on gRPC channels Google Cloud clients create from now on.
+
+    Returns True when tracing is on, including after an earlier call, whose
+    ``tracer_provider`` stays. Returns False, without raising, when
+    OTEL_PYTHON_DISABLED_INSTRUMENTATIONS turns ``gcp`` off, when Datadog
+    ddtrace instruments grpc, or when google-api-core's gRPC support is
+    missing. Clients built before the call, and transports given their own
+    ``channel``, are left as they are.
+    """
+    on = False
+
+    def setup() -> None:
+        nonlocal on
+        on = _instrument(tracer_provider)
+
+    _contain_logged(setup, site="gcp.instrument")
+    return on
+
+
+def uninstrument() -> None:
+    """Stop tracing new Google Cloud channels; existing ones keep tracing."""
+
+    def teardown() -> None:
+        with _lock:
+            for module_name, wrapper in list(_installed.items()):
+                wrapper.__struct_active__ = False  # type: ignore[attr-defined]
+                module = sys.modules.get(module_name)
+                if getattr(module, "create_channel", None) is wrapper:
+                    setattr(module, "create_channel", wrapper.__struct_original__)  # type: ignore[attr-defined]
+                    del _installed[module_name]
+                # Otherwise the host wrapped Struct's layer: it stays, passing through.
+
+    _contain_logged(teardown, site="gcp.uninstrument")
+
+
+def _instrument(tracer_provider: Optional["TracerProvider"]) -> bool:
+    if _disabled():
+        logger.debug(
+            "Skipping %s instrumentation: turned off by %s",
+            NAME,
+            _auto.OTEL_PYTHON_DISABLED_INSTRUMENTATIONS,
+        )
+        return False
+    try:
+        grpc_helpers = importlib.import_module("google.api_core.grpc_helpers")
+    except ImportError:
+        logger.debug("Skipping %s instrumentation: google-api-core gRPC support is not installed", NAME)
+        return False
+    if _ddtrace_owns_grpc():
+        logger.info(
+            "Struct left Google Cloud gRPC clients to Datadog ddtrace, which instruments grpc, "
+            "to avoid duplicate spans and conflicting trace headers."
+        )
+        return False
+    with _lock:
+        modules = [(grpc_helpers, False)]
+        try:
+            modules.append((importlib.import_module("google.api_core.grpc_helpers_async"), True))
+        except ImportError:
+            pass
+        installed_now = False
+        attempts: Optional[_Attempts] = None
+        for module, aio in modules:
+            wrapper = _installed.get(module.__name__)
+            if wrapper is not None and _reachable(module.create_channel, wrapper):
+                # Still in place, possibly beneath a host wrapper: turn it back on.
+                wrapper.__struct_active__ = True  # type: ignore[attr-defined]
+                continue
+            if wrapper is not None:
+                # It may still run inside a host wrapper that hides __wrapped__.
+                wrapper.__struct_active__ = False  # type: ignore[attr-defined]
+            if attempts is None:
+                attempts = _Attempts(tracer_provider, _excluded_services())
+            wrapper = _tracing(module.create_channel, attempts, aio=aio)
+            setattr(module, "create_channel", wrapper)
+            _installed[module.__name__] = wrapper
+            installed_now = True
+    if installed_now:
+        logger.info("Auto-instrumented: %s", NAME)
+    return True
+
+
+def _reachable(current: Any, wrapper: Callable[..., Any]) -> bool:
+    """Whether ``current`` is Struct's wrapper or wraps it (functools.wraps)."""
+    for _ in range(16):
+        if current is wrapper:
+            return True
+        current = getattr(current, "__wrapped__", None)
+        if current is None:
+            return False
+    return False
+
+
+def _disabled() -> bool:
+    names = {n.strip() for n in os.environ.get(_auto.OTEL_PYTHON_DISABLED_INSTRUMENTATIONS, "").split(",")}
+    return NAME in names or "*" in names
+
+
+def _excluded_services() -> frozenset[str]:
+    services = (s.strip() for s in os.environ.get(OTEL_PYTHON_GRPC_EXCLUDED_SERVICES, "").split(","))
+    return frozenset(s for s in services if s)
+
+
+def _guarded(fn: Callable[[], Any], *, site: str, default: Any = None) -> Any:
+    result = default
+
+    def run() -> None:
+        nonlocal result
+        result = fn()
+
+    _contain_logged(run, site=site)
+    return result
+
+
+def _tracing(original: Callable[..., Any], attempts: "_Attempts", *, aio: bool) -> Callable[..., Any]:
+    """A ``create_channel`` that adds Struct's interceptor to Google's channel."""
+
+    @functools.wraps(original)
+    def create_channel(*args: Any, **kwargs: Any) -> Any:
+        if not create_channel.__struct_active__ or _guarded(  # type: ignore[attr-defined]
+            _ddtrace_owns_grpc, site="gcp.ddtrace", default=False
+        ):
+            return original(*args, **kwargs)
+        target = args[0] if args else kwargs.get("target")
+        if aio:
+            # grpc.aio channels take their interceptors at construction.
+            interceptor = _guarded(lambda: attempts.aio_interceptor(target), site="gcp.aio_channel")
+            if interceptor is not None:
+                kwargs = {**kwargs, "interceptors": [interceptor, *(kwargs.get("interceptors") or ())]}
+            return original(*args, **kwargs)
+        channel = original(*args, **kwargs)
+        return _guarded(lambda: attempts.intercept(channel, target), site="gcp.channel", default=channel)
+
+    create_channel.__struct_original__ = original  # type: ignore[attr-defined]
+    create_channel.__struct_active__ = True  # type: ignore[attr-defined]
+    return create_channel
+
+
+def _ddtrace_owns_grpc() -> bool:
+    """ddtrace patched grpc, possibly after instrument(): channels created from
+    then on are its own."""
+    return _auto._left_to_ddtrace("grpc_client", _auto._ddtrace_instrumented())
+
+
+def _contrib_instruments(class_name: str) -> bool:
+    """Whether contrib's own gRPC client instrumentor (owned mode's
+    ``grpc_client`` and ``grpc_aio_client``, or the host's) already traces
+    every new channel. Checked on the shared instance, which constructing one
+    would reset; a never-imported contrib cannot be on."""
+    contrib = sys.modules.get("opentelemetry.instrumentation.grpc")
+    instrumentor_class = getattr(contrib, class_name, None)
+    if instrumentor_class is None:
+        return False
+    return bool(instrumentor_class.__new__(instrumentor_class).is_instrumented_by_opentelemetry)
+
+
+def _server(target: Any) -> dict[str, Any]:
+    if not isinstance(target, str) or not target:
+        return {}
+    host, separator, port = target.rpartition(":")
+    if not separator or not port.isdigit() or host.endswith(":"):
+        return {"server.address": target.strip("[]")}
+    return {"server.address": host.strip("[]"), "server.port": int(port)}
+
+
+class _Attempts:
+    """Starts and ends one CLIENT span per unary RPC attempt.
+
+    Every telemetry step is contained: the RPC's continuation runs exactly
+    once, with the app's metadata (repeated keys included) plus the host
+    propagator's headers. The span is never made the current span, so no
+    context is attached across the call.
+    """
+
+    def __init__(self, tracer_provider: Optional["TracerProvider"], excluded: frozenset[str]) -> None:
+        from opentelemetry import trace
+
+        self._tracer: "Tracer" = trace.get_tracer("struct_sdk.gcp", _SDK_VERSION, tracer_provider)
+        self._excluded = excluded
+
+    def intercept(self, channel: Any, target: Any) -> Any:
+        if _contrib_instruments("GrpcInstrumentorClient"):
+            return channel
+        import grpc
+
+        return grpc.intercept_channel(channel, _interceptor_classes()[0](self, _server(target)))
+
+    def aio_interceptor(self, target: Any) -> Any:
+        if _contrib_instruments("GrpcAioInstrumentorClient"):
+            return None
+        return _interceptor_classes()[1](self, _server(target))
+
+    def start(self, details: Any, server: dict[str, Any], *, aio: bool) -> Optional["_Attempt"]:
+        from opentelemetry import context, trace
+        from opentelemetry.context import _SUPPRESS_INSTRUMENTATION_KEY
+        from opentelemetry.trace import SpanKind
+
+        if context.get_value(_SUPPRESS_INSTRUMENTATION_KEY):
+            return None
+        method = details.method.decode() if isinstance(details.method, bytes) else details.method
+        service, _, name = (method or "").lstrip("/").rpartition("/")
+        if not service or service in self._excluded:
+            return None
+        span = self._tracer.start_span(
+            f"{service}/{name}",
+            kind=SpanKind.CLIENT,
+            attributes={"rpc.system": "grpc", "rpc.service": service, "rpc.method": name, **server},
+        )
+        metadata = list(details.metadata or ())
+
+        def propagate() -> None:
+            from opentelemetry.propagate import get_global_textmap, inject
+
+            carrier: dict[str, str] = {}
+            inject(carrier, context=trace.set_span_in_context(span))
+            headers = _grpc_headers(carrier)
+            # Every field the configured propagator owns describes this
+            # attempt, written or not: an app-supplied copy (a caller's own
+            # parent context, a leftover tracestate) would be extracted instead.
+            owned = _propagation_fields(get_global_textmap()) | headers.keys()
+            metadata[:] = [item for item in metadata if str(item[0]).lower() not in owned]
+            metadata.extend(headers.items())
+
+        _contain_logged(propagate, site="gcp.propagate")
+        attempt = _Attempt(span, details)
+        _contain_logged(lambda: attempt.send_with(metadata, aio=aio), site="gcp.metadata")
+        return attempt
+
+
+class _Attempt:
+    __slots__ = ("span", "details", "_ended")
+
+    def __init__(self, span: "Span", details: Any) -> None:
+        self.span = span
+        self.details = details
+        self._ended = False
+
+    def send_with(self, metadata: list[Any], *, aio: bool) -> None:
+        details = self.details
+        if aio:
+            from grpc import aio as grpc_aio
+
+            self.details = grpc_aio.ClientCallDetails(
+                details.method,
+                details.timeout,
+                grpc_aio.Metadata(*metadata),
+                details.credentials,
+                details.wait_for_ready,
+            )
+        else:
+            self.details = _interceptor_classes()[2](
+                details.method,
+                details.timeout,
+                metadata,
+                details.credentials,
+                getattr(details, "wait_for_ready", None),
+                getattr(details, "compression", None),
+            )
+
+    def end(self, code: Any) -> None:
+        if self._ended:
+            return
+        self._ended = True
+        import grpc
+        from opentelemetry.trace import Status, StatusCode
+
+        code = code if isinstance(code, grpc.StatusCode) else grpc.StatusCode.UNKNOWN
+        _contain_logged(lambda: self.span.set_attribute("rpc.grpc.status_code", code.value[0]), site="gcp.status")
+        if code is not grpc.StatusCode.OK:
+            _contain_logged(lambda: self.span.set_status(Status(StatusCode.ERROR, code.name)), site="gcp.status")
+        self.span.end()
+
+    def end_when_done(self, outcome: Any) -> None:
+        def done(future: Any) -> None:
+            code = _guarded(lambda: future.code(), site="gcp.code")
+            _contain_logged(lambda: self.end(code), site="gcp.end")
+
+        try:
+            outcome.add_done_callback(done)
+        except Exception:
+            done(outcome)
+
+
+def _propagation_fields(propagator: Any) -> set[str]:
+    fields = {str(field).lower() for field in (getattr(propagator, "fields", None) or ())}
+    if fields & _B3_HEADERS:
+        fields |= _B3_HEADERS
+    return fields
+
+
+def _grpc_headers(carrier: dict[Any, Any]) -> dict[str, str]:
+    """The propagator's fields gRPC accepts as metadata. gRPC fails the whole
+    call with INTERNAL on an upper-case or otherwise invalid key, a reserved
+    ``grpc-`` key or a non-printable value, so those fields are dropped."""
+    headers = {}
+    for key, value in carrier.items():
+        key = str(key).lower()
+        if not _METADATA_KEY.match(key) or key.startswith("grpc-") or key.endswith("-bin"):
+            continue
+        if not isinstance(value, str) or not (value.isascii() and value.isprintable()):
+            continue
+        headers[key] = value
+    return headers
+
+
+def _code_of(error: BaseException) -> Any:
+    if isinstance(error, asyncio.CancelledError):
+        import grpc
+
+        return grpc.StatusCode.CANCELLED
+    code = _guarded(lambda: getattr(error, "code", None), site="gcp.code")
+    return _guarded(code, site="gcp.code") if callable(code) else None
+
+
+# Tasks reading a finished grpc.aio call's status (its code() is a coroutine).
+_finishing: set["asyncio.Task[None]"] = set()
+
+
+def _end_when_aio_done(call: Any, attempt: _Attempt) -> None:
+    loop = asyncio.get_running_loop()
+
+    async def finish(done: Any) -> None:
+        code: Any = None
+        try:
+            code = await done.code()
+        except BaseException as error:  # noqa: BLE001 — the status read only feeds the span
+            code = _code_of(error)
+        finally:
+            # Not left to a done callback: a loop closed right after this
+            # task finishes never runs one.
+            _finishing.discard(asyncio.current_task())  # type: ignore[arg-type]
+        _contain_logged(lambda: attempt.end(code), site="gcp.end")
+
+    def done(finished: Any) -> None:
+        def schedule() -> None:
+            task = loop.create_task(finish(finished))
+            _finishing.add(task)
+            task.add_done_callback(_finishing.discard)
+
+        _contain_logged(schedule, site="gcp.end")
+
+    # A host interceptor that awaited the call hands back grpc's finished
+    # response wrapper, which takes no callbacks.
+    try:
+        if call.done():
+            done(call)
+        else:
+            call.add_done_callback(done)
+    except Exception:
+        # The call cannot be observed: end the attempt now rather than never.
+        _contain_logged(lambda: attempt.end(None), site="gcp.end")
+
+
+@functools.lru_cache(maxsize=None)
+def _interceptor_classes() -> tuple[type, type, type]:
+    # Defined on first use: grpc is an optional dependency of this module.
+    import grpc
+    from grpc import aio
+
+    class UnaryUnaryAttempts(grpc.UnaryUnaryClientInterceptor):  # type: ignore[misc]
+        def __init__(self, attempts: _Attempts, server: dict[str, Any]) -> None:
+            self._attempts = attempts
+            self._server = server
+
+        def intercept_unary_unary(self, continuation: Any, client_call_details: Any, request: Any) -> Any:
+            attempt = _guarded(
+                lambda: self._attempts.start(client_call_details, self._server, aio=False), site="gcp.start"
+            )
+            if attempt is None:
+                return continuation(client_call_details, request)
+            try:
+                outcome = continuation(attempt.details, request)
+            except BaseException as error:
+                failed = _code_of(error)
+                _contain_logged(lambda: attempt.end(failed), site="gcp.end")
+                raise
+            _contain_logged(lambda: attempt.end_when_done(outcome), site="gcp.end")
+            return outcome
+
+    class AioUnaryUnaryAttempts(aio.UnaryUnaryClientInterceptor):  # type: ignore[misc]
+        def __init__(self, attempts: _Attempts, server: dict[str, Any]) -> None:
+            self._attempts = attempts
+            self._server = server
+
+        async def intercept_unary_unary(self, continuation: Any, client_call_details: Any, request: Any) -> Any:
+            attempt = _guarded(
+                lambda: self._attempts.start(client_call_details, self._server, aio=True), site="gcp.start"
+            )
+            if attempt is None:
+                return await continuation(client_call_details, request)
+            try:
+                call = await continuation(attempt.details, request)
+            except BaseException as error:
+                failed = _code_of(error)
+                _contain_logged(lambda: attempt.end(failed), site="gcp.end")
+                raise
+            # Returned at once, as without Struct, so waiting on, timing out
+            # or cancelling the call behaves as grpc does; the span ends when
+            # the call does.
+            _contain_logged(lambda: _end_when_aio_done(call, attempt), site="gcp.end")
+            return call
+
+    class CallDetails(
+        collections.namedtuple(
+            "CallDetails", ("method", "timeout", "metadata", "credentials", "wait_for_ready", "compression")
+        ),
+        grpc.ClientCallDetails,
+    ):
+        pass
+
+    return UnaryUnaryAttempts, AioUnaryUnaryAttempts, CallDetails