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

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

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

google_api_core-2.38.0/google/api_core/_observability.py

@@ -0,0 +1,281 @@
+# -*- coding: utf-8 -*-
+# 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 helpers for resolving and instantiating interceptors."""
+
+from __future__ import annotations
+
+import urllib.parse
+from typing import TYPE_CHECKING, Any, Callable, Sequence
+
+from google.api_core import _feature_gating_helpers
+from google.api_core.client_options import ClientOptions
+
+if TYPE_CHECKING:
+    # flake8: grpc, trace, and ClientInterceptor are imported only for static analysis and type annotations
+    # The 'noqa: F401' comment avoids flake8 "imported but not used" errors.
+    import grpc  # noqa: F401
+    import opentelemetry.trace  # noqa: F401
+
+    from google.api_core.grpc_helpers import ClientInterceptor  # noqa: F401
+
+_TRACER_PROVIDER = "tracer_provider"
+
+
+def is_otel_capabilities_enabled(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+    env_var: str = "GOOGLE_SDK_EXPERIMENTAL_PYTHON_TRACING_ENABLED",
+) -> bool:
+    """Checks if OTel capabilities are enabled and installed.
+
+    Args:
+        client_options: The client options object or dictionary.
+        env_var: The environment variable to check for enablement.
+
+    Returns:
+        bool: True if enabled and installed, False otherwise.
+    """
+    is_tracing_enabled = _feature_gating_helpers.resolve_feature_flags(
+        env_var=env_var,
+        feature_key=_TRACER_PROVIDER,
+        configuration=client_options,
+    )
+
+    if is_tracing_enabled:
+        try:
+            import opentelemetry.instrumentation.grpc as otel_grpc  # type: ignore[import-not-found] # noqa: F401
+
+            return True
+        except ImportError:
+            pass
+
+    return False
+
+
+def _extract_endpoint_attributes(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+) -> dict[str, Any]:
+    """Extracts server.address, server.port (if non-default), and url.domain from client options if present.
+
+    Args:
+        client_options: The client options object or dictionary.
+
+    Returns:
+        dict[str, Any]: A dictionary containing url.domain and, if an api_endpoint is configured,
+            server.address and non-default server.port.
+    """
+    attrs: dict[str, Any] = {}
+    endpoint = None
+    universe_domain = None
+
+    if isinstance(client_options, dict):
+        endpoint = client_options.get("api_endpoint")
+        universe_domain = client_options.get("universe_domain")
+    elif client_options is not None:
+        endpoint = getattr(client_options, "api_endpoint", None)
+        universe_domain = getattr(client_options, "universe_domain", None)
+
+    attrs["url.domain"] = universe_domain or "googleapis.com"
+
+    if endpoint and isinstance(endpoint, str):
+        target = endpoint if "//" in endpoint else f"//{endpoint}"
+        parsed = None
+        hostname = None
+        port = None
+        try:
+            parsed = urllib.parse.urlsplit(target)
+            hostname = parsed.hostname
+            port = parsed.port
+        except ValueError:
+            pass
+
+        if hostname:
+            attrs["server.address"] = hostname
+        if port and parsed:
+            scheme = parsed.scheme.lower()
+            is_default_port = (port == 443 and scheme in ("https", "")) or (
+                port == 80 and scheme == "http"
+            )
+            if not is_default_port:
+                attrs["server.port"] = port
+    return attrs
+
+
+def _make_grpc_client_request_hook(
+    endpoint_attrs: dict[str, Any] | None = None,
+) -> Callable[[Any, Any], None]:
+    """Creates an OpenTelemetry gRPC client request hook with optional endpoint attributes.
+
+    Args:
+        endpoint_attrs: Optional static endpoint attributes to attach to every span.
+
+    Returns:
+        Callable[[Any, Any], None]: The request hook callback.
+    """
+    static_attrs = dict(endpoint_attrs) if endpoint_attrs else {}
+
+    def client_request_hook(span: Any, request: Any) -> None:
+        if span is None or not getattr(span, "is_recording", lambda: True)():
+            return
+
+        # Upstream opentelemetry-instrumentation-grpc may format span names with a
+        # leading slash (e.g. "/package.Service/Method"). Normalize the span name
+        # and ensure rpc.method is always captured as the clean, fully-qualified name.
+        span_name = getattr(span, "name", None)
+        if isinstance(span_name, str) and span_name:
+            clean_method_name = span_name.lstrip("/")
+            if span_name.startswith("/") and hasattr(span, "update_name"):
+                span.update_name(clean_method_name)
+            span.set_attribute("rpc.method", clean_method_name)
+
+        attrs: dict[str, Any] = {
+            "rpc.system.name": "grpc",
+        }
+        if static_attrs:
+            attrs.update(static_attrs)
+        for key, value in attrs.items():
+            span.set_attribute(key, value)
+
+    return client_request_hook
+
+
+_grpc_client_request_hook = _make_grpc_client_request_hook()
+
+
+def _grpc_client_response_hook(span: Any, response: Any) -> None:
+    """OpenTelemetry gRPC client response hook to record successful response status.
+
+    Upstream ``opentelemetry-instrumentation-grpc`` sets the integer status code
+    ``rpc.grpc.status_code`` (e.g. 0), but does not record the modern string status
+    ``rpc.response.status_code`` (e.g. "OK") required by Cloud Trace and current
+    OpenTelemetry semantic conventions (v1.27.0+).
+
+    This hook enriches successful RPC attempt spans with ``rpc.response.status_code = "OK"``.
+    Errors and non-OK statuses are handled at the Tier 3 method span layer or upstream.
+
+    Upstream handles synchronous and asynchronous invocations differently:
+    - **Synchronous gRPC**: Upstream only invokes the response hook when an RPC call
+      succeeds. On failure, the hook is bypassed entirely.
+    - **Asynchronous gRPC**: Upstream invokes the response hook unconditionally for
+      both successes and failures (passing exception details on error). However, it
+      always marks ``span.status`` with an error status before calling the hook.
+
+    Because of this disparity, this hook checks ``span.status`` to guard against
+    async failure callbacks while allowing synchronous and successful asynchronous
+    calls to be marked "OK".
+
+    Note:
+        If upstream ``opentelemetry-instrumentation-grpc`` adds native support for
+        modern ``rpc.response.status_code`` in future releases, this hook can be retired.
+
+    Args:
+        span: The OpenTelemetry span.
+        response: The gRPC response object or details.
+    """
+    if not span.is_recording():
+        return
+
+    # Guard against upstream async calls that invoke this hook on failures.
+    status = getattr(span, "status", None)
+    status_code = getattr(status, "status_code", None)
+    if (
+        getattr(status_code, "name", None) == "ERROR"
+        or getattr(status_code, "value", None) == 2
+    ):
+        return
+
+    span.set_attribute("rpc.response.status_code", "OK")
+
+
+def _get_tracer_provider(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+) -> opentelemetry.trace.TracerProvider | None:
+    """Extracts the OpenTelemetry tracer provider from client options if present.
+
+    Args:
+        client_options: The client options object or dictionary.
+
+    Returns:
+        opentelemetry.trace.TracerProvider | None: The tracer provider if present,
+            None otherwise.
+    """
+    if isinstance(client_options, dict):
+        return client_options.get(_TRACER_PROVIDER)
+    elif client_options is not None:
+        return getattr(client_options, _TRACER_PROVIDER, None)
+    return None
+
+
+def get_otel_interceptor(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+) -> Callable[[grpc.Channel], grpc.Channel] | None:
+    """Returns an interceptor callable that wraps a sync gRPC channel with OpenTelemetry tracing.
+
+    Args:
+        client_options: The client options object or dictionary used for feature gating
+            and extracting the tracer provider.
+
+    Returns:
+        Callable[[grpc.Channel], grpc.Channel] | None: An interceptor callable if OpenTelemetry
+            tracing is enabled and installed, None otherwise.
+    """
+    if not is_otel_capabilities_enabled(client_options):
+        return None
+
+    import opentelemetry.instrumentation.grpc as otel_grpc  # type: ignore[import-not-found]
+
+    endpoint_attrs = _extract_endpoint_attributes(client_options)
+    request_hook = _make_grpc_client_request_hook(endpoint_attrs)
+
+    interceptor: ClientInterceptor = otel_grpc.client_interceptor(
+        tracer_provider=_get_tracer_provider(client_options),
+        request_hook=request_hook,
+        response_hook=_grpc_client_response_hook,
+    )
+
+    def otel_interceptor(channel: grpc.Channel) -> grpc.Channel:
+        return otel_grpc.intercept_channel(channel, interceptor)
+
+    return otel_interceptor
+
+
+def get_otel_async_interceptor(
+    client_options: ClientOptions | dict[str, Any] | None = None,
+) -> Sequence[grpc.aio.ClientInterceptor] | None:
+    """Returns async gRPC client interceptors for OpenTelemetry tracing.
+
+    Args:
+        client_options: The client options object or dictionary used for feature gating
+            and extracting the tracer provider.
+
+    Returns:
+        Sequence[grpc.aio.ClientInterceptor] | None: Instantiated OpenTelemetry async
+            client interceptors if tracing is enabled and installed, None otherwise.
+    """
+    if not is_otel_capabilities_enabled(client_options):
+        return None
+
+    # Ignored by mypy: Optional dependency only loaded if early-return is skipped
+    import opentelemetry.instrumentation.grpc as otel_grpc  # type: ignore[import-not-found]
+
+    endpoint_attrs = _extract_endpoint_attributes(client_options)
+    request_hook = _make_grpc_client_request_hook(endpoint_attrs)
+
+    return otel_grpc.aio_client_interceptors(
+        tracer_provider=_get_tracer_provider(client_options),
+        request_hook=request_hook,
+        response_hook=_grpc_client_response_hook,
+    )

{google_api_core-2.36.0 → google_api_core-2.38.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.38.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.38.0"

{google_api_core-2.36.0 → google_api_core-2.38.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.38.0
 Summary: Google API client core library
 Author-email: Google LLC <googleapis-packages@google.com>
 License: Apache 2.0

google_api_core-2.38.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,
+        )