google-api-core 2.36.0__tar.gz → 2.37.0__tar.gz

{google_api_core-2.36.0/google_api_core.egg-info → google_api_core-2.37.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-api-core
-Version: 2.36.0
+Version: 2.37.0
 Summary: Google API client core library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0

{google_api_core-2.36.0 → google_api_core-2.37.0}/google/api_core/gapic_v1/method.py

@@ -18,12 +18,14 @@ This is used by gapic clients to provide common error mapping, retry, timeout,
 compression, pagination, and long-running operations to gRPC methods.
 """
 
+import contextlib
 import enum
 import functools
-from typing import List, Tuple
+from typing import Any, List, Optional, Tuple
 
-from google.api_core import grpc_helpers
+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()
@@ -92,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])
@@ -104,6 +106,124 @@ def _extract_metrics_header(metadata) -> Tuple[str, List[Tuple[str, str]]]:
     return metric_str, arbitrary_metadata
 
 
+def _extract_rpc_identity(
+    method_name: str,
+) -> Tuple[str, str, str]:
+    """Extract (full_rpc_name, service_name, rpc_method_name) from an explicit method name.
+
+    Args:
+        method_name: Explicit RPC name (e.g. "/google.cloud.secretmanager.v1.SecretManagerService/AccessSecretVersion").
+
+    Returns:
+        Tuple[str, str, str]: A 3-tuple of (full_rpc_name, service_name, rpc_method_name).
+    """
+    method_str = method_name.lstrip("/")
+    service, _, method = method_str.rpartition("/")
+    return method_str, service, method
+
+
+def _extract_status_code(exc: Optional[Exception]) -> str:
+    """Extract canonical status code name string from an exception.
+
+    Status code name strings are resolved by inspecting the following locations:
+    * Chained exceptions: Unwraps RetryError or __cause__ to the root exception.
+    * Enum & code attributes: Inspects .grpc_status_code on GoogleAPICallError or .code on gRPC errors.
+    * Integer status codes: Maps raw gRPC integer status codes to canonical enum names.
+    * Fallback: Defaults to the exception class name for standard Python errors.
+
+    Args:
+        exc (Optional[Exception]): The exception to extract the status code name from.
+
+    Returns:
+        str: The canonical status code name (e.g. "NOT_FOUND", "UNAVAILABLE") or class name.
+    """
+    if exc is None:
+        return ""
+
+    # 1. Unwrap chained exceptions: unwrap RetryError or __cause__ to the root failure
+    target = getattr(exc, "cause", None) or getattr(exc, "__cause__", None) or exc
+
+    # 2. Check enum & code attributes: .grpc_status_code enum or callable/non-callable .code
+    status = getattr(target, "grpc_status_code", None)
+    if status is None and hasattr(target, "code"):
+        try:
+            status = target.code() if callable(target.code) else target.code
+        except Exception:
+            status = None
+
+    name = getattr(status, "name", None)
+    if name:
+        return str(name)
+
+    # 3. Check integer status codes: map raw gRPC integer status codes to canonical enum names
+    if isinstance(status, int):
+        from google.api_core import exceptions
+
+        status = exceptions._INT_TO_GRPC_CODE.get(status, status)
+        return getattr(status, "name", str(status))
+
+    # 4. Fallback: default to the exception class name for standard Python errors
+    return target.__class__.__name__
+
+
+def _extract_error_attributes(exc: Optional[Exception]) -> dict[str, Any]:
+    """Extract gcp.errors.* and error.type attributes from an exception.
+
+    Error details and ErrorInfo structures are resolved by inspecting the following locations:
+    * Chained exceptions: Unwraps RetryError or __cause__ to the root exception.
+    * GoogleAPICallError attributes: Reads ErrorInfo from ._error_info or .error_info.
+    * Native gRPC trailing metadata: Parses google.rpc.Status binary details from trailing_metadata.
+    * Unified attribute extraction: Extracts domain, reason, and metadata from ErrorInfo or exception attributes.
+
+    Args:
+        exc (Optional[Exception]): An exception (such as GoogleAPICallError or grpc.RpcError) or ErrorInfo object.
+
+    Returns:
+        dict[str, Any]: Extracted error attributes (e.g. gcp.errors.domain, error.type, gcp.errors.metadata.*).
+    """
+    attrs: dict[str, Any] = {}
+    if exc is None:
+        return attrs
+
+    # 1. Unwrap chained exceptions: unwrap RetryError or __cause__ to the root failure
+    target_exc = getattr(exc, "cause", None) or getattr(exc, "__cause__", None) or exc
+
+    # 2. Check GoogleAPICallError ErrorInfo attributes
+    error_info = getattr(target_exc, "_error_info", None) or getattr(
+        target_exc, "error_info", None
+    )
+
+    # 3. Check native gRPC trailing metadata for binary google.rpc.Status details
+    if error_info is None:
+        rpc_call = (
+            target_exc
+            if hasattr(target_exc, "trailing_metadata")
+            else getattr(target_exc, "response", None)
+        )
+        if rpc_call is not None and hasattr(rpc_call, "trailing_metadata"):
+            try:
+                from google.api_core import exceptions
+
+                _, error_info = exceptions._parse_grpc_error_details(rpc_call)
+            except Exception:
+                pass
+
+    # 4. Unified attribute extraction: extract domain, reason, and metadata from ErrorInfo or exception attributes
+    source = error_info or target_exc
+    domain = getattr(source, "domain", None)
+    if domain:
+        attrs["gcp.errors.domain"] = domain
+    reason = getattr(source, "reason", None)
+    if reason:
+        attrs["error.type"] = reason
+    metadata = getattr(source, "metadata", None)
+    if metadata:
+        for k, v in metadata.items():
+            attrs[f"gcp.errors.metadata.{k}"] = str(v)
+
+    return attrs
+
+
 class _GapicCallable(object):
     """Callable that applies retry, timeout, and metadata logic.
 
@@ -123,6 +243,18 @@ class _GapicCallable(object):
             provided to the RPC method on every invocation. This is merged with
             any metadata specified during invocation. If ``None``, no
             additional metadata will be passed to the RPC method.
+        client_options
+            (Optional[google.api_core.client_options.ClientOptions]):
+                Client options used to configure client-level behavior, such as
+                custom OpenTelemetry tracer providers. Defaults to None.
+        method_name (Optional[str]): The optional explicit full RPC method name
+            (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 for metadata headers. Defaults to None.
+        kind (str): The transport kind for the RPC method. Defaults to "grpc".
+            Allowed values for OpenTelemetry method tracing are "grpc" and "grpc_asyncio".
     """
 
     def __init__(
@@ -132,22 +264,65 @@ class _GapicCallable(object):
         timeout,
         compression,
         metadata=None,
+        client_options=None,
+        method_name=None,
+        is_streaming=False,
+        client_info=None,
+        kind="grpc",
     ):
         self._target = target
         self._retry = retry
         self._timeout = timeout
         self._compression = compression
+
         # Pre-extract the x-goog-api-client header from the initialized metadata.
         self._x_goog_api_client, remaining = _extract_metrics_header(metadata)
         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:
             self._default_metadata = self._static_metadata
 
+        # Configure the OpenTelemetry span factory once at initialization.
+        # For now, method tracing is gated to non-streaming gRPC calls where an explicit method_name is provided.
+        self._start_span_fn = None
+        if (
+            not is_streaming
+            and kind == "grpc"
+            and method_name is not None
+            and _observability.is_otel_capabilities_enabled(client_options)
+        ):
+            try:
+                from opentelemetry import trace
+
+                tracer_provider = None
+                if isinstance(client_options, dict):
+                    tracer_provider = client_options.get("tracer_provider")
+                elif client_options is not None:
+                    tracer_provider = getattr(client_options, "tracer_provider", None)
+                if tracer_provider is not None:
+                    tracer = tracer_provider.get_tracer("google.api_core")
+                else:
+                    tracer = trace.get_tracer("google.api_core")
+
+                span_name, _, _ = _extract_rpc_identity(method_name)
+                span_attributes = {
+                    "rpc.system.name": "grpc",
+                    "rpc.method": span_name,
+                }
+                self._start_span_fn = functools.partial(
+                    tracer.start_as_current_span,
+                    span_name,
+                    kind=trace.SpanKind.CLIENT,
+                    attributes=span_attributes,
+                )
+            except (ImportError, AttributeError, TypeError):
+                # Gracefully disable tracing if OpenTelemetry or custom provider fails
+                self._start_span_fn = None
+
     def __call__(
         self, *args, timeout=DEFAULT, retry=DEFAULT, compression=DEFAULT, **kwargs
     ):
@@ -177,7 +352,7 @@ class _GapicCallable(object):
                 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:
@@ -186,7 +361,27 @@ class _GapicCallable(object):
         if self._compression is not None:
             kwargs["compression"] = compression
 
-        return wrapped_func(*args, **kwargs)
+        span_cm = contextlib.nullcontext()
+        if self._start_span_fn is not None:
+            try:
+                span_cm = self._start_span_fn()
+            except Exception:
+                span_cm = contextlib.nullcontext()
+
+        with span_cm as span:
+            try:
+                result = wrapped_func(*args, **kwargs)
+                if span is not None and hasattr(span, "set_attribute"):
+                    span.set_attribute("rpc.response.status_code", "OK")
+                return result
+            except Exception as exc:
+                if span is not None and hasattr(span, "set_attribute"):
+                    span.set_attribute(
+                        "rpc.response.status_code", _extract_status_code(exc)
+                    )
+                    for k, v in _extract_error_attributes(exc).items():
+                        span.set_attribute(k, v)
+                raise
 
 
 def wrap_method(
@@ -197,6 +392,10 @@ def wrap_method(
     client_info=client_info.DEFAULT_CLIENT_INFO,
     *,
     with_call=False,
+    client_options=None,
+    method_name=None,
+    is_streaming=False,
+    kind="grpc",
 ):
     """Wrap an RPC method with common behavior.
 
@@ -280,6 +479,18 @@ def wrap_method(
             return a tuple of (response, grpc.Call) instead of just the response.
             This is useful for extracting trailing metadata from unary calls.
             Defaults to False.
+        client_options
+            (Optional[google.api_core.client_options.ClientOptions]):
+                Client options used to configure client-level behavior, such as
+                custom OpenTelemetry tracer providers. Defaults to None.
+        method_name (Optional[str]): Optional explicit full RPC method name
+            (e.g. "/google.cloud.secretmanager.v1.SecretManagerService/AccessSecretVersion").
+            Used to identify the RPC for observability.
+        is_streaming (bool): Whether the RPC method is streaming. Defaults to False.
+            Streaming methods are currently gated and do not generate Tier 3 spans.
+        kind (str): The transport kind for the RPC method. Defaults to "grpc".
+            Non-gRPC transports (e.g. "rest") are currently gated and do not generate
+            Tier 3 method spans.
 
     Returns:
         Callable: A new callable that takes optional ``retry``, ``timeout``,
@@ -307,5 +518,10 @@ def wrap_method(
             default_timeout,
             default_compression,
             metadata=user_agent_metadata,
+            client_options=client_options,
+            method_name=method_name,
+            is_streaming=is_streaming,
+            client_info=client_info,
+            kind=kind,
         )
     )

{google_api_core-2.36.0 → google_api_core-2.37.0}/google/api_core/version.py

@@ -12,4 +12,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-__version__ = "2.36.0"
+__version__ = "2.37.0"

{google_api_core-2.36.0 → google_api_core-2.37.0/google_api_core.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-api-core
-Version: 2.36.0
+Version: 2.37.0
 Summary: Google API client core library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0

google_api_core-2.37.0/tests/conftest.py

@@ -0,0 +1,66 @@
+# 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.
+
+import os
+import sys
+import types
+from unittest import mock
+
+import pytest
+
+
+@pytest.fixture(scope="session", autouse=True)
+def mock_mtls_env():
+    """Autouse session-scoped fixture to isolate unit tests from workstation mTLS environments."""
+    with mock.patch.dict(
+        os.environ,
+        {
+            "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false",
+            "CLOUDSDK_CONTEXT_AWARE_USE_CLIENT_CERTIFICATE": "false",
+        },
+    ):
+        yield
+
+
+@pytest.fixture
+def mock_otel(monkeypatch):
+    """Provides a mocked OpenTelemetry environment with tracing enabled."""
+    monkeypatch.setenv("GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED", "true")
+    mock_span = mock.MagicMock()
+    mock_tracer = mock.MagicMock()
+    mock_tracer.start_as_current_span.return_value.__enter__.return_value = mock_span
+
+    mock_trace = mock.Mock()
+    mock_trace.get_tracer.return_value = mock_tracer
+    mock_trace.SpanKind.CLIENT = "CLIENT"
+    mock_trace.StatusCode.ERROR = "ERROR"
+
+    with (
+        mock.patch(
+            "google.api_core._observability.is_otel_capabilities_enabled",
+            return_value=True,
+        ),
+        mock.patch.dict(
+            sys.modules,
+            {
+                "opentelemetry": mock.Mock(trace=mock_trace),
+                "opentelemetry.trace": mock_trace,
+            },
+        ),
+    ):
+        yield types.SimpleNamespace(
+            trace=mock_trace,
+            tracer=mock_tracer,
+            span=mock_span,
+        )

{google_api_core-2.36.0 → google_api_core-2.37.0}/tests/helpers.py

@@ -78,3 +78,28 @@ warn_deprecated_credentials_file = functools.partial(
     DeprecationWarning,
     match="argument is deprecated because of a potential security risk",
 )
+
+
+def assert_uninstrumented_gapic_callable(
+    wrapped,
+    result,
+    mock_target,
+    mock_trace=None,
+    expected_result="success",
+):
+    """Verifies that an uninstrumented RPC callable succeeds without tracing overhead.
+
+    1. Proves the RPC executed successfully with the expected return value.
+    2. Proves the OpenTelemetry API was never invoked.
+    3. Proves the callable holds no tracer or span configuration.
+    """
+    # 1. Prove the RPC executed successfully
+    assert result == expected_result
+    mock_target.assert_called_once()
+
+    # 2. Prove the OpenTelemetry API was never invoked
+    if mock_trace is not None:
+        mock_trace.get_tracer.assert_not_called()
+
+    # 3. Prove the callable holds no span factory
+    assert getattr(wrapped, "_start_span_fn", None) is None