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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: struct-sdk
-Version: 0.4.13
+Version: 0.4.14
 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
@@ -948,6 +948,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.14}/README.md

@@ -832,6 +832,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.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "struct-sdk"
-version = "0.4.13"
+version = "0.4.14"
 description = "Struct agent observability SDK — auto-instruments AI agent frameworks with OpenTelemetry"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -211,6 +211,13 @@ 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",
 ]
 # 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 +261,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.14/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