feat(gapic): add gcp.client.* attributes to T3 method span

Author: chalmerlowe

packages/google-api-core/google/api_core/gapic_v1/method.py

@@ -25,6 +25,7 @@
 
 from google.api_core import _observability, grpc_helpers
 from google.api_core.gapic_v1 import client_info
+from google.api_core.gapic_v1.client_info import METRICS_METADATA_KEY
 from google.api_core.timeout import TimeToDeadlineTimeout
 
 USE_DEFAULT_METADATA = object()
@@ -93,7 +94,7 @@ def _extract_metrics_header(metadata) -> Tuple[str, List[Tuple[str, str]]]:
     if not metadata:
         return "", []
 
-    key_to_find = client_info.METRICS_METADATA_KEY
+    key_to_find = METRICS_METADATA_KEY
 
     metric_str = _deduplicate_metadata_tokens(
         " ".join([v for k, v in metadata if k == key_to_find])
@@ -150,6 +151,9 @@ class _GapicCallable(object):
             (e.g. "/google.cloud.secretmanager.v1.SecretManagerService/AccessSecretVersion").
         is_streaming (bool): Whether the RPC method is streaming. Defaults to False.
             Note: Streaming methods do not currently generate Tier 3 observability spans.
+        client_info (Optional[google.api_core.gapic_v1.client_info.ClientInfo]):
+            Client information used to extract client library metadata (e.g. version, repo)
+            for observability attributes. Defaults to None.
     """
 
     def __init__(
@@ -162,6 +166,7 @@ def __init__(
         client_options=None,
         method_name=None,
         is_streaming=False,
+        client_info=None,
     ):
         self._target = target
         self._retry = retry
@@ -176,7 +181,7 @@ def __init__(
         self._static_metadata = tuple(remaining)
         if self._x_goog_api_client:
             self._default_metadata = (
-                (client_info.METRICS_METADATA_KEY, self._x_goog_api_client),
+                (METRICS_METADATA_KEY, self._x_goog_api_client),
                 *self._static_metadata,
             )
         else:
@@ -213,6 +218,23 @@ def __init__(
                     "rpc.service": self._rpc_service,
                     "rpc.method": self._rpc_method,
                 }
+                if self._rpc_service:
+                    self._span_attributes["gcp.client.service"] = (
+                        self._rpc_service.rpartition(".")[-1]
+                    )
+                if client_info is not None:
+                    client_version = getattr(
+                        client_info, "client_library_version", None
+                    ) or getattr(client_info, "gapic_version", None)
+                    if client_version:
+                        self._span_attributes["gcp.client.version"] = client_version
+                    self._span_attributes["gcp.client.repo"] = (
+                        getattr(client_info, "client_repo", None)
+                        or "googleapis/google-cloud-python"
+                    )
+                    client_artifact = getattr(client_info, "client_artifact", None)
+                    if client_artifact:
+                        self._span_attributes["gcp.client.artifact"] = client_artifact
             except (ImportError, AttributeError, TypeError):
                 # Gracefully disable tracing if OpenTelemetry or custom provider fails
                 self._tracer = None
@@ -248,7 +270,7 @@ def __call__(
                 self._x_goog_api_client, user_x_goog
             )
             if merged_header:
-                final_metadata.append((client_info.METRICS_METADATA_KEY, merged_header))
+                final_metadata.append((METRICS_METADATA_KEY, merged_header))
             final_metadata.extend(remaining)
             kwargs["metadata"] = final_metadata
         elif self._default_metadata:
@@ -416,5 +438,6 @@ def get_topic(name, timeout=None):
             client_options=client_options,
             method_name=method_name,
             is_streaming=is_streaming,
+            client_info=client_info,
         )
     )

packages/google-api-core/google/api_core/gapic_v1/method_async.py

@@ -64,5 +64,6 @@ def wrap_method(
             client_options=client_options,
             method_name=method_name,
             is_streaming=is_streaming,
+            client_info=client_info,
         )
     )

packages/google-api-core/tests/asyncio/gapic/test_method_async.py

@@ -319,5 +319,7 @@ async def test_wrap_method_async_with_otel_tracing(monkeypatch):
             "rpc.system": "grpc",
             "rpc.service": "google.test.AsyncService",
             "rpc.method": "AsyncMethod",
+            "gcp.client.service": "AsyncService",
+            "gcp.client.repo": "googleapis/google-cloud-python",
         },
     )

packages/google-api-core/tests/unit/gapic/test_method.py

@@ -25,11 +25,11 @@
     pytest.skip("No GRPC", allow_module_level=True)
 
 
-import google.api_core.gapic_v1.client_info
 import google.api_core.gapic_v1.method
 import google.api_core.page_iterator
 from google.api_core import client_options as client_options_lib
 from google.api_core import exceptions, retry, timeout
+from google.api_core.gapic_v1 import client_info
 
 
 def _utcnow_monotonic():
@@ -477,6 +477,8 @@ def test_wrap_method_otel_tracing_enabled_success(mock_otel, method_name):
             "rpc.system": "grpc",
             "rpc.service": "google.cloud.secretmanager.v1.SecretManagerService",
             "rpc.method": "ListSecrets",
+            "gcp.client.service": "SecretManagerService",
+            "gcp.client.repo": "googleapis/google-cloud-python",
         },
     )
 
@@ -506,6 +508,8 @@ def test_wrap_method_otel_tracing_custom_client_options(mock_otel):
             "rpc.system": "grpc",
             "rpc.service": "google.test.Service",
             "rpc.method": "TestMethod",
+            "gcp.client.service": "Service",
+            "gcp.client.repo": "googleapis/google-cloud-python",
         },
     )
 
@@ -630,6 +634,8 @@ def test_wrap_method_async_otel_tracing(mock_otel):
             "rpc.system": "grpc",
             "rpc.service": "google.test.AsyncService",
             "rpc.method": "AsyncMethod",
+            "gcp.client.service": "AsyncService",
+            "gcp.client.repo": "googleapis/google-cloud-python",
         },
     )
 
@@ -655,3 +661,143 @@ def test_wrap_method_async_otel_tracing_streaming_skips_span(mock_otel):
         mock_trace=mock_otel.trace,
         expected_result="async_success",
     )
+
+
+def test_wrap_method_otel_tracing_attributes_with_client_info(mock_otel):
+    """Proves that client_info version, repo, and artifact attributes are included in the T3 span."""
+    mock_target = mock.Mock(return_value="success")
+
+    info = client_info.ClientInfo(
+        client_library_version="2.16.0",
+    )
+    info.client_repo = "googleapis/google-cloud-python-test"
+    info.client_artifact = "google-cloud-secretmanager"
+
+    wrapped = google.api_core.gapic_v1.method.wrap_method(
+        mock_target,
+        client_info=info,
+        method_name="/google.cloud.secretmanager.v1.SecretManagerService/ListSecrets",
+    )
+    result = wrapped()
+
+    assert result == "success"
+    mock_otel.tracer.start_as_current_span.assert_called_once_with(
+        "google.cloud.secretmanager.v1.SecretManagerService/ListSecrets",
+        kind="CLIENT",
+        attributes={
+            "rpc.system": "grpc",
+            "rpc.service": "google.cloud.secretmanager.v1.SecretManagerService",
+            "rpc.method": "ListSecrets",
+            "gcp.client.service": "SecretManagerService",
+            "gcp.client.repo": "googleapis/google-cloud-python-test",
+            "gcp.client.version": "2.16.0",
+            "gcp.client.artifact": "google-cloud-secretmanager",
+        },
+    )
+
+
+def test_wrap_method_otel_tracing_attributes_fallback_gapic_version(mock_otel):
+    """Proves that gapic_version is used when client_library_version is not set."""
+    mock_target = mock.Mock(return_value="success")
+
+    info = client_info.ClientInfo(
+        gapic_version="1.5.0",
+    )
+
+    wrapped = google.api_core.gapic_v1.method.wrap_method(
+        mock_target,
+        client_info=info,
+        method_name="/google.cloud.secretmanager.v1.SecretManagerService/ListSecrets",
+    )
+    result = wrapped()
+
+    assert result == "success"
+    mock_otel.tracer.start_as_current_span.assert_called_once_with(
+        "google.cloud.secretmanager.v1.SecretManagerService/ListSecrets",
+        kind="CLIENT",
+        attributes={
+            "rpc.system": "grpc",
+            "rpc.service": "google.cloud.secretmanager.v1.SecretManagerService",
+            "rpc.method": "ListSecrets",
+            "gcp.client.service": "SecretManagerService",
+            "gcp.client.repo": "googleapis/google-cloud-python",
+            "gcp.client.version": "1.5.0",
+        },
+    )
+
+
+def test_wrap_method_otel_tracing_attributes_no_client_info(mock_otel):
+    """Proves that when client_info is None, gcp.client repo, version, and artifact are omitted."""
+    mock_target = mock.Mock(return_value="success")
+
+    wrapped = google.api_core.gapic_v1.method.wrap_method(
+        mock_target,
+        client_info=None,
+        method_name="/google.cloud.secretmanager.v1.SecretManagerService/ListSecrets",
+    )
+    result = wrapped()
+
+    assert result == "success"
+    mock_otel.tracer.start_as_current_span.assert_called_once_with(
+        "google.cloud.secretmanager.v1.SecretManagerService/ListSecrets",
+        kind="CLIENT",
+        attributes={
+            "rpc.system": "grpc",
+            "rpc.service": "google.cloud.secretmanager.v1.SecretManagerService",
+            "rpc.method": "ListSecrets",
+            "gcp.client.service": "SecretManagerService",
+        },
+    )
+
+
+def test_wrap_method_otel_tracing_attributes_no_service(mock_otel):
+    """Proves that when method_name has no service prefix, gcp.client.service is omitted."""
+    mock_target = mock.Mock(return_value="success")
+
+    wrapped = google.api_core.gapic_v1.method.wrap_method(
+        mock_target,
+        client_info=None,
+        method_name="ListSecrets",
+    )
+    result = wrapped()
+
+    assert result == "success"
+    mock_otel.tracer.start_as_current_span.assert_called_once_with(
+        "ListSecrets",
+        kind="CLIENT",
+        attributes={
+            "rpc.system": "grpc",
+            "rpc.service": "",
+            "rpc.method": "ListSecrets",
+        },
+    )
+
+
+def test_wrap_method_async_otel_tracing_with_client_info(mock_otel):
+    """Proves that method_async.wrap_method passes client_info to _GapicCallable."""
+    from google.api_core.gapic_v1 import method_async
+
+    mock_target = mock.Mock(return_value="async_success")
+    info = client_info.ClientInfo(client_library_version="3.0.0")
+
+    wrapped = method_async.wrap_method(
+        mock_target,
+        kind=None,
+        client_info=info,
+        method_name="google.test.AsyncService/AsyncMethod",
+    )
+    result = wrapped()
+
+    assert result == "async_success"
+    mock_otel.tracer.start_as_current_span.assert_called_once_with(
+        "google.test.AsyncService/AsyncMethod",
+        kind="CLIENT",
+        attributes={
+            "rpc.system": "grpc",
+            "rpc.service": "google.test.AsyncService",
+            "rpc.method": "AsyncMethod",
+            "gcp.client.service": "AsyncService",
+            "gcp.client.repo": "googleapis/google-cloud-python",
+            "gcp.client.version": "3.0.0",
+        },
+    )