feat(observability): add base OpenTelemetry span enricher interceptor

Author: chalmerlowe

packages/google-api-core/google/api_core/observability/__init__.py

@@ -1,3 +1,9 @@
 from .options import is_signal_enabled
 
-__all__ = ["is_signal_enabled"]
+try:
+    # Tell flake8 that it's okay this is unused, it's just being exposed to the package namespace.
+    from .tracing import OtelSpanEnricher  # noqa: F401
+
+    __all__ = ["is_signal_enabled", "OtelSpanEnricher"]
+except ImportError:
+    __all__ = ["is_signal_enabled"]

packages/google-api-core/google/api_core/observability/tracing.py

@@ -0,0 +1,75 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""OpenTelemetry Tracing Enrichment Interceptors."""
+
+from typing import Any, Callable, Dict, Optional
+
+import grpc
+from opentelemetry import trace
+
+
+class OtelSpanEnricher(grpc.UnaryUnaryClientInterceptor):
+    """A gRPC client interceptor that enriches the active OpenTelemetry span.
+
+    This interceptor relies on the standard OpenTelemetry gRPC instrumentor
+    to create the baseline span. It runs in the interceptor chain to inject
+    additional Google Cloud specific domain attributes.
+    """
+
+    def __init__(
+        self,
+        static_attributes: Optional[Dict[str, Any]] = None,
+        attribute_extractor: Optional[
+            Callable[[Any, grpc.ClientCallDetails], Dict[str, Any]]
+        ] = None,
+    ):
+        """Initializes the OtelSpanEnricher.
+
+        Args:
+            static_attributes: Standard static attributes to attach to every span.
+                E.g. {"gcp.client.repo": "googleapis/google-cloud-python"}
+            attribute_extractor: A callable that extracts dynamic attributes from
+                the request and client call details.
+        """
+        self._static_attributes = static_attributes or {}
+        self._attribute_extractor = attribute_extractor
+
+    def intercept_unary_unary(
+        self,
+        continuation: Callable[[grpc.ClientCallDetails, Any], Any],
+        client_call_details: grpc.ClientCallDetails,
+        request: Any,
+    ) -> Any:
+        span = trace.get_current_span()
+
+        if span.is_recording():
+            # Inject static attributes
+            for key, val in self._static_attributes.items():
+                span.set_attribute(key, val)
+
+            # Extract and inject dynamic attributes
+            if self._attribute_extractor:
+                try:
+                    dynamic_attrs = self._attribute_extractor(
+                        request, client_call_details
+                    )
+                    for key, val in dynamic_attrs.items():
+                        if val is not None:
+                            span.set_attribute(key, val)
+                except Exception:
+                    # Prevent custom extractor exceptions from failing the RPC
+                    pass
+
+        return continuation(client_call_details, request)

packages/google-api-core/pyproject.toml

@@ -49,6 +49,7 @@ dependencies = [
   "proto-plus >= 1.25.0, < 2.0.0; python_version >= '3.13'",
   "google-auth >= 2.14.1, < 3.0.0",
   "requests >= 2.33.0, < 3.0.0",
+  "opentelemetry-api >= 1.1.0, < 2.0.0",
 ]
 dynamic = ["version"]
 

packages/google-api-core/testing/constraints-3.10.txt

@@ -12,3 +12,4 @@ requests==2.33.0
 grpcio==1.41.0
 grpcio-status==1.41.0
 proto-plus==1.24.0
+opentelemetry-api==1.1.0

packages/google-api-core/testing/constraints-async-rest-3.10.txt

@@ -13,3 +13,4 @@ grpcio==1.41.0
 grpcio-status==1.41.0
 proto-plus==1.24.0
 aiohttp==3.13.4
+opentelemetry-api==1.1.0

packages/google-api-core/tests/unit/observability/test_tracing.py

@@ -0,0 +1,160 @@
+# Copyright 2026 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from unittest.mock import MagicMock, Mock
+
+import pytest
+
+# Check if grpc is available
+try:
+    import grpc
+
+    has_grpc = True
+except ImportError:
+    has_grpc = False
+
+# Skip all tests in this module if grpc is not installed
+pytestmark = pytest.mark.skipif(not has_grpc, reason="grpc package is required")
+
+if has_grpc:
+
+    class MockClientCallDetails(grpc.ClientCallDetails):
+        pass
+
+else:
+    # Tell mypy that we are intentionally redefining this class for the non-gRPC fallback path.
+    class MockClientCallDetails:  # type: ignore[no-redef]
+        pass
+
+
+@pytest.fixture
+def mock_span(mocker):
+    """Mocks trace.get_current_span to return a recording span."""
+    mock_span_obj = MagicMock()
+    mock_span_obj.is_recording.return_value = True
+    mocker.patch("opentelemetry.trace.get_current_span", return_value=mock_span_obj)
+    return mock_span_obj
+
+
+@pytest.fixture
+def mock_span_non_recording(mocker):
+    """Mocks trace.get_current_span to return a non-recording span."""
+    mock_span_obj = MagicMock()
+    mock_span_obj.is_recording.return_value = False
+    mocker.patch("opentelemetry.trace.get_current_span", return_value=mock_span_obj)
+    return mock_span_obj
+
+
+def test_enricher_non_recording_span(mock_span_non_recording):
+    """Verifies that non-recording spans do not have attributes set and extractor is skipped."""
+    from google.api_core.observability.tracing import OtelSpanEnricher
+
+    extractor = Mock()
+    enricher = OtelSpanEnricher(
+        static_attributes={"static.key": "static.val"}, attribute_extractor=extractor
+    )
+
+    continuation = Mock(return_value="response")
+    details = MockClientCallDetails()
+    request = "request"
+
+    res = enricher.intercept_unary_unary(continuation, details, request)
+
+    assert res == "response"
+    continuation.assert_called_once_with(details, request)
+    mock_span_non_recording.set_attribute.assert_not_called()
+    extractor.assert_not_called()
+
+
+@pytest.mark.parametrize(
+    "static_attrs,request_val,extractor_return,expected_attrs",
+    [
+        # Case 1: Only static attributes
+        ({"static.key": "static.val"}, "req", None, {"static.key": "static.val"}),
+        # Case 2: Only dynamic attributes
+        (None, "req", {"dynamic.key": "dynamic.val"}, {"dynamic.key": "dynamic.val"}),
+        # Case 3: Both static and dynamic
+        (
+            {"static.key": "static.val"},
+            "req",
+            {"dynamic.key": "dynamic.val"},
+            {"static.key": "static.val", "dynamic.key": "dynamic.val"},
+        ),
+        # Case 4: Dynamic extractor returns None values (should be skipped)
+        (
+            {"static.key": "static.val"},
+            "req",
+            {"dynamic.key": None, "other.key": "other.val"},
+            {"static.key": "static.val", "other.key": "other.val"},
+        ),
+    ],
+)
+def test_enricher_recording_span(
+    mock_span, static_attrs, request_val, extractor_return, expected_attrs
+):
+    """Verifies static and dynamic attribute resolution on recording spans."""
+    from google.api_core.observability.tracing import OtelSpanEnricher
+
+    if extractor_return is not None:
+        extractor = Mock(return_value=extractor_return)
+    else:
+        extractor = None
+
+    enricher = OtelSpanEnricher(
+        static_attributes=static_attrs, attribute_extractor=extractor
+    )
+
+    continuation = Mock(return_value="response")
+    details = MockClientCallDetails()
+    request = request_val
+
+    res = enricher.intercept_unary_unary(continuation, details, request)
+
+    assert res == "response"
+    continuation.assert_called_once_with(details, request)
+
+    # Check that expected attributes were set
+    for key, val in expected_attrs.items():
+        mock_span.set_attribute.assert_any_call(key, val)
+
+    # Total set_attribute calls should match expected_attrs size
+    assert mock_span.set_attribute.call_count == len(expected_attrs)
+
+    if extractor:
+        extractor.assert_called_once_with(request, details)
+
+
+def test_enricher_extractor_exception(mock_span):
+    """Verifies that exceptions in attribute extraction are caught and do not fail the call."""
+    from google.api_core.observability.tracing import OtelSpanEnricher
+
+    def bad_extractor(req, details):
+        raise ValueError("Extraction failure")
+
+    enricher = OtelSpanEnricher(
+        static_attributes={"static.key": "static.val"},
+        attribute_extractor=bad_extractor,
+    )
+
+    continuation = Mock(return_value="response")
+    details = MockClientCallDetails()
+    request = "req"
+
+    res = enricher.intercept_unary_unary(continuation, details, request)
+
+    assert res == "response"
+    continuation.assert_called_once_with(details, request)
+
+    # Static attributes should still be set before extractor failure
+    mock_span.set_attribute.assert_called_once_with("static.key", "static.val")