google-cloud-spanner 3.62.0__tar.gz → 3.63.0__tar.gz

{google_cloud_spanner-3.62.0/google_cloud_spanner.egg-info → google_cloud_spanner-3.63.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: google-cloud-spanner
-Version: 3.62.0
+Version: 3.63.0
 Summary: Google Cloud Spanner API client library
 Home-page: https://github.com/googleapis/python-spanner
 Author: Google LLC

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_admin_database_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "3.62.0"  # {x-release-please-version}
+__version__ = "3.63.0"  # {x-release-please-version}

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_admin_instance_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "3.62.0"  # {x-release-please-version}
+__version__ = "3.63.0"  # {x-release-please-version}

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_dbapi/version.py

@@ -15,6 +15,6 @@
 import platform
 
 PY_VERSION = platform.python_version()
-__version__ = "3.62.0"
+__version__ = "3.63.0"
 VERSION = __version__
 DEFAULT_USER_AGENT = "gl-dbapi/" + VERSION

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/__init__.py

@@ -65,6 +65,7 @@ from .types.type import TypeAnnotationCode
 from .types.type import TypeCode
 from .data_types import JsonObject, Interval
 from .transaction import BatchTransactionId, DefaultTransactionOptions
+from .exceptions import wrap_with_request_id
 
 from google.cloud.spanner_v1 import param_types
 from google.cloud.spanner_v1.client import Client
@@ -88,6 +89,8 @@ __all__ = (
     # google.cloud.spanner_v1
     "__version__",
     "param_types",
+    # google.cloud.spanner_v1.exceptions
+    "wrap_with_request_id",
     # google.cloud.spanner_v1.client
     "Client",
     # google.cloud.spanner_v1.keyset

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/_helpers.py

@@ -22,6 +22,7 @@ import base64
 import threading
 import logging
 import uuid
+from contextlib import contextmanager
 
 from google.protobuf.struct_pb2 import ListValue
 from google.protobuf.struct_pb2 import Value
@@ -34,8 +35,12 @@ from google.cloud._helpers import _date_from_iso8601_date
 from google.cloud.spanner_v1.types import ExecuteSqlRequest
 from google.cloud.spanner_v1.types import TransactionOptions
 from google.cloud.spanner_v1.data_types import JsonObject, Interval
-from google.cloud.spanner_v1.request_id_header import with_request_id
+from google.cloud.spanner_v1.request_id_header import (
+    with_request_id,
+    with_request_id_metadata_only,
+)
 from google.cloud.spanner_v1.types import TypeCode
+from google.cloud.spanner_v1.exceptions import wrap_with_request_id
 
 from google.rpc.error_details_pb2 import RetryInfo
 
@@ -612,9 +617,11 @@ def _retry(
         try:
             return func()
         except Exception as exc:
-            if (
+            is_allowed = (
                 allowed_exceptions is None or exc.__class__ in allowed_exceptions
-            ) and retries < retry_count:
+            )
+
+            if is_allowed and retries < retry_count:
                 if (
                     allowed_exceptions is not None
                     and allowed_exceptions[exc.__class__] is not None
@@ -767,9 +774,67 @@ class AtomicCounter:
 
 
 def _metadata_with_request_id(*args, **kwargs):
+    """Return metadata with request ID header.
+
+    This function returns only the metadata list (not a tuple),
+    maintaining backward compatibility with existing code.
+
+    Args:
+        *args: Arguments to pass to with_request_id
+        **kwargs: Keyword arguments to pass to with_request_id
+
+    Returns:
+        list: gRPC metadata with request ID header
+    """
+    return with_request_id_metadata_only(*args, **kwargs)
+
+
+def _metadata_with_request_id_and_req_id(*args, **kwargs):
+    """Return both metadata and request ID string.
+
+    This is used when we need to augment errors with the request ID.
+
+    Args:
+        *args: Arguments to pass to with_request_id
+        **kwargs: Keyword arguments to pass to with_request_id
+
+    Returns:
+        tuple: (metadata, request_id)
+    """
     return with_request_id(*args, **kwargs)
 
 
+def _augment_error_with_request_id(error, request_id=None):
+    """Augment an error with request ID information.
+
+    Args:
+        error: The error to augment (typically GoogleAPICallError)
+        request_id (str): The request ID to include
+
+    Returns:
+        The augmented error with request ID information
+    """
+    return wrap_with_request_id(error, request_id)
+
+
+@contextmanager
+def _augment_errors_with_request_id(request_id):
+    """Context manager to augment exceptions with request ID.
+
+    Args:
+        request_id (str): The request ID to include in exceptions
+
+    Yields:
+        None
+    """
+    try:
+        yield
+    except Exception as exc:
+        augmented = _augment_error_with_request_id(exc, request_id)
+        # Use exception chaining to preserve the original exception
+        raise augmented from exc
+
+
 def _merge_Transaction_Options(
     defaultTransactionOptions: TransactionOptions,
     mergeTransactionOptions: TransactionOptions,

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/_opentelemetry_tracing.py

@@ -36,6 +36,7 @@ from google.cloud.spanner_v1.metrics.metrics_capture import MetricsCapture
 
 TRACER_NAME = "cloud.google.com/python/spanner"
 TRACER_VERSION = gapic_version.__version__
+GCP_RESOURCE_NAME_PREFIX = "//spanner.googleapis.com/"
 extended_tracing_globally_disabled = (
     os.getenv("SPANNER_ENABLE_EXTENDED_TRACING", "").lower() == "false"
 )
@@ -106,6 +107,7 @@ def trace_call(
         "gcp.client.service": "spanner",
         "gcp.client.version": TRACER_VERSION,
         "gcp.client.repo": "googleapis/python-spanner",
+        "gcp.resource.name": GCP_RESOURCE_NAME_PREFIX + db_name,
     }
 
     if extra_attributes:

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/batch.py

@@ -13,6 +13,7 @@
 # limitations under the License.
 
 """Context manager for Cloud Spanner batched writes."""
+
 import functools
 from typing import List, Optional
 
@@ -252,20 +253,22 @@ class Batch(_BatchBase):
                     max_commit_delay=max_commit_delay,
                     request_options=request_options,
                 )
+                # This code is retried due to ABORTED, hence nth_request
+                # should be increased. attempt can only be increased if
+                # we encounter UNAVAILABLE or INTERNAL.
+                call_metadata, error_augmenter = database.with_error_augmentation(
+                    getattr(database, "_next_nth_request", 0),
+                    1,
+                    metadata,
+                    span,
+                )
                 commit_method = functools.partial(
                     api.commit,
                     request=commit_request,
-                    metadata=database.metadata_with_request_id(
-                        # This code is retried due to ABORTED, hence nth_request
-                        # should be increased. attempt can only be increased if
-                        # we encounter UNAVAILABLE or INTERNAL.
-                        getattr(database, "_next_nth_request", 0),
-                        1,
-                        metadata,
-                        span,
-                    ),
+                    metadata=call_metadata,
                 )
-                return commit_method()
+                with error_augmenter:
+                    return commit_method()
 
             response = _retry_on_aborted_exception(
                 wrapped_method,

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/client.py

@@ -23,10 +23,12 @@ In the hierarchy of API concepts
 * a :class:`~google.cloud.spanner_v1.instance.Instance` owns a
   :class:`~google.cloud.spanner_v1.database.Database`
 """
+
 import grpc
 import os
 import logging
 import warnings
+import threading
 
 from google.api_core.gapic_v1 import client_info
 from google.auth.credentials import AnonymousCredentials
@@ -99,11 +101,50 @@ def _get_spanner_optimizer_statistics_package():
 
 log = logging.getLogger(__name__)
 
+_metrics_monitor_initialized = False
+_metrics_monitor_lock = threading.Lock()
+
 
 def _get_spanner_enable_builtin_metrics_env():
     return os.getenv(SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR) != "true"
 
 
+def _initialize_metrics(project, credentials):
+    """
+    Initializes the Spanner built-in metrics.
+
+    This function sets up the OpenTelemetry MeterProvider and the SpannerMetricsTracerFactory.
+    It uses a lock to ensure that initialization happens only once.
+    """
+    global _metrics_monitor_initialized
+    if not _metrics_monitor_initialized:
+        with _metrics_monitor_lock:
+            if not _metrics_monitor_initialized:
+                meter_provider = metrics.NoOpMeterProvider()
+                try:
+                    if not _get_spanner_emulator_host():
+                        meter_provider = MeterProvider(
+                            metric_readers=[
+                                PeriodicExportingMetricReader(
+                                    CloudMonitoringMetricsExporter(
+                                        project_id=project,
+                                        credentials=credentials,
+                                    ),
+                                    export_interval_millis=METRIC_EXPORT_INTERVAL_MS,
+                                ),
+                            ]
+                        )
+                    metrics.set_meter_provider(meter_provider)
+                    SpannerMetricsTracerFactory()
+                    _metrics_monitor_initialized = True
+                except Exception as e:
+                    # log is already defined at module level
+                    log.warning(
+                        "Failed to initialize Spanner built-in metrics. Error: %s",
+                        e,
+                    )
+
+
 class Client(ClientWithProject):
     """Client for interacting with Cloud Spanner API.
 
@@ -251,31 +292,12 @@ class Client(ClientWithProject):
             "http://" in self._emulator_host or "https://" in self._emulator_host
         ):
             warnings.warn(_EMULATOR_HOST_HTTP_SCHEME)
-        # Check flag to enable Spanner builtin metrics
         if (
             _get_spanner_enable_builtin_metrics_env()
             and not disable_builtin_metrics
             and HAS_GOOGLE_CLOUD_MONITORING_INSTALLED
         ):
-            meter_provider = metrics.NoOpMeterProvider()
-            try:
-                if not _get_spanner_emulator_host():
-                    meter_provider = MeterProvider(
-                        metric_readers=[
-                            PeriodicExportingMetricReader(
-                                CloudMonitoringMetricsExporter(
-                                    project_id=project, credentials=credentials
-                                ),
-                                export_interval_millis=METRIC_EXPORT_INTERVAL_MS,
-                            ),
-                        ]
-                    )
-                metrics.set_meter_provider(meter_provider)
-                SpannerMetricsTracerFactory()
-            except Exception as e:
-                log.warning(
-                    "Failed to initialize Spanner built-in metrics. Error: %s", e
-                )
+            _initialize_metrics(project, credentials)
         else:
             SpannerMetricsTracerFactory(enabled=False)
 

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/database.py

@@ -25,7 +25,6 @@ import threading
 
 import google.auth.credentials
 from google.api_core.retry import Retry
-from google.api_core.retry import if_exception_type
 from google.cloud.exceptions import NotFound
 from google.api_core.exceptions import Aborted
 from google.api_core import gapic_v1
@@ -55,6 +54,8 @@ from google.cloud.spanner_v1._helpers import (
     _metadata_with_prefix,
     _metadata_with_leader_aware_routing,
     _metadata_with_request_id,
+    _augment_errors_with_request_id,
+    _metadata_with_request_id_and_req_id,
 )
 from google.cloud.spanner_v1.batch import Batch
 from google.cloud.spanner_v1.batch import MutationGroups
@@ -496,6 +497,66 @@ class Database(object):
             span,
         )
 
+    def metadata_and_request_id(
+        self, nth_request, nth_attempt, prior_metadata=[], span=None
+    ):
+        """Return metadata and request ID string.
+
+        This method returns both the gRPC metadata with request ID header
+        and the request ID string itself, which can be used to augment errors.
+
+        Args:
+            nth_request: The request sequence number
+            nth_attempt: The attempt number (for retries)
+            prior_metadata: Prior metadata to include
+            span: Optional span for tracing
+
+        Returns:
+            tuple: (metadata_list, request_id_string)
+        """
+        if span is None:
+            span = get_current_span()
+
+        return _metadata_with_request_id_and_req_id(
+            self._nth_client_id,
+            self._channel_id,
+            nth_request,
+            nth_attempt,
+            prior_metadata,
+            span,
+        )
+
+    def with_error_augmentation(
+        self, nth_request, nth_attempt, prior_metadata=[], span=None
+    ):
+        """Context manager for gRPC calls with error augmentation.
+
+        This context manager provides both metadata with request ID and
+        automatically augments any exceptions with the request ID.
+
+        Args:
+            nth_request: The request sequence number
+            nth_attempt: The attempt number (for retries)
+            prior_metadata: Prior metadata to include
+            span: Optional span for tracing
+
+        Yields:
+            tuple: (metadata_list, context_manager)
+        """
+        if span is None:
+            span = get_current_span()
+
+        metadata, request_id = _metadata_with_request_id_and_req_id(
+            self._nth_client_id,
+            self._channel_id,
+            nth_request,
+            nth_attempt,
+            prior_metadata,
+            span,
+        )
+
+        return metadata, _augment_errors_with_request_id(request_id)
+
     def __eq__(self, other):
         if not isinstance(other, self.__class__):
             return NotImplemented
@@ -783,16 +844,18 @@ class Database(object):
 
                 try:
                     add_span_event(span, "Starting BeginTransaction")
-                    txn = api.begin_transaction(
-                        session=session.name,
-                        options=txn_options,
-                        metadata=self.metadata_with_request_id(
-                            self._next_nth_request,
-                            1,
-                            metadata,
-                            span,
-                        ),
+                    call_metadata, error_augmenter = self.with_error_augmentation(
+                        self._next_nth_request,
+                        1,
+                        metadata,
+                        span,
                     )
+                    with error_augmenter:
+                        txn = api.begin_transaction(
+                            session=session.name,
+                            options=txn_options,
+                            metadata=call_metadata,
+                        )
 
                     txn_selector = TransactionSelector(id=txn.id)
 
@@ -2060,5 +2123,10 @@ def _retry_on_aborted(func, retry_config):
     :type retry_config: Retry
     :param retry_config: retry object with the settings to be used
     """
-    retry = retry_config.with_predicate(if_exception_type(Aborted))
+
+    def _is_aborted(exc):
+        """Check if exception is Aborted."""
+        return isinstance(exc, Aborted)
+
+    retry = retry_config.with_predicate(_is_aborted)
     return retry(func)

google_cloud_spanner-3.63.0/google/cloud/spanner_v1/exceptions.py

@@ -0,0 +1,42 @@
+# Copyright 2026 Google LLC All rights reserved.
+#
+# 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.
+
+"""Cloud Spanner exception utilities with request ID support."""
+
+from google.api_core.exceptions import GoogleAPICallError
+
+
+def wrap_with_request_id(error, request_id=None):
+    """Add request ID information to a GoogleAPICallError.
+
+    This function adds request_id as an attribute to the exception,
+    preserving the original exception type for exception handling compatibility.
+    The request_id is also appended to the error message so it appears in logs.
+
+    Args:
+        error: The error to augment. If not a GoogleAPICallError, returns as-is
+        request_id (str): The request ID to include
+
+    Returns:
+        The original error with request_id attribute added and message updated
+        (if GoogleAPICallError and request_id is provided), otherwise returns
+        the original error unchanged.
+    """
+    if isinstance(error, GoogleAPICallError) and request_id:
+        # Add request_id as an attribute for programmatic access
+        error.request_id = request_id
+        # Modify the message to include request_id so it appears in logs
+        if hasattr(error, "message") and error.message:
+            error.message = f"{error.message}, request_id = {request_id}"
+    return error

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/gapic_version.py

@@ -13,4 +13,4 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
-__version__ = "3.62.0"  # {x-release-please-version}
+__version__ = "3.63.0"  # {x-release-please-version}

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/metrics/metrics_capture.py

@@ -20,6 +20,8 @@ are consistently recorded for Cloud Spanner operations, facilitating observabili
 performance monitoring.
 """
 
+from contextvars import Token
+
 from .spanner_metrics_tracer_factory import SpannerMetricsTracerFactory
 
 
@@ -30,6 +32,9 @@ class MetricsCapture:
     the start and completion of metrics tracing for a given operation.
     """
 
+    _token: Token
+    """Token to reset the context variable after the operation completes."""
+
     def __enter__(self):
         """Enter the runtime context related to this object.
 
@@ -45,11 +50,11 @@ class MetricsCapture:
             return self
 
         # Define a new metrics tracer for the new operation
-        SpannerMetricsTracerFactory.current_metrics_tracer = (
-            factory.create_metrics_tracer()
-        )
-        if SpannerMetricsTracerFactory.current_metrics_tracer:
-            SpannerMetricsTracerFactory.current_metrics_tracer.record_operation_start()
+        # Set the context var and keep the token for reset
+        tracer = factory.create_metrics_tracer()
+        self._token = SpannerMetricsTracerFactory.set_current_tracer(tracer)
+        if tracer:
+            tracer.record_operation_start()
         return self
 
     def __exit__(self, exc_type, exc_value, traceback):
@@ -70,6 +75,11 @@ class MetricsCapture:
         if not SpannerMetricsTracerFactory().enabled:
             return False
 
-        if SpannerMetricsTracerFactory.current_metrics_tracer:
-            SpannerMetricsTracerFactory.current_metrics_tracer.record_operation_completion()
+        tracer = SpannerMetricsTracerFactory.get_current_tracer()
+        if tracer:
+            tracer.record_operation_completion()
+
+        # Reset the context var using the token
+        if getattr(self, "_token", None):
+            SpannerMetricsTracerFactory.reset_current_tracer(self._token)
         return False  # Propagate the exception if any

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/metrics/metrics_interceptor.py

@@ -97,22 +97,17 @@ class MetricsInterceptor(ClientInterceptor):
         Args:
             resources (Dict[str, str]): A dictionary containing project, instance, and database information.
         """
-        if SpannerMetricsTracerFactory.current_metrics_tracer is None:
+        tracer = SpannerMetricsTracerFactory.get_current_tracer()
+        if tracer is None:
             return
 
         if resources:
             if "project" in resources:
-                SpannerMetricsTracerFactory.current_metrics_tracer.set_project(
-                    resources["project"]
-                )
+                tracer.set_project(resources["project"])
             if "instance" in resources:
-                SpannerMetricsTracerFactory.current_metrics_tracer.set_instance(
-                    resources["instance"]
-                )
+                tracer.set_instance(resources["instance"])
             if "database" in resources:
-                SpannerMetricsTracerFactory.current_metrics_tracer.set_database(
-                    resources["database"]
-                )
+                tracer.set_database(resources["database"])
 
     def intercept(self, invoked_method, request_or_iterator, call_details):
         """Intercept gRPC calls to collect metrics.
@@ -126,31 +121,32 @@ class MetricsInterceptor(ClientInterceptor):
             The RPC response
         """
         factory = SpannerMetricsTracerFactory()
-        if (
-            SpannerMetricsTracerFactory.current_metrics_tracer is None
-            or not factory.enabled
-        ):
+        tracer = SpannerMetricsTracerFactory.get_current_tracer()
+        if tracer is None or not factory.enabled:
             return invoked_method(request_or_iterator, call_details)
 
         # Setup Metric Tracer attributes from call details
-        ## Extract  Project / Instance / Databse from header information
-        resources = self._extract_resource_from_path(call_details.metadata)
-        self._set_metrics_tracer_attributes(resources)
+        ## Extract Project / Instance / Database from header information if not already set
+        if not (
+            tracer.client_attributes.get("project_id")
+            and tracer.client_attributes.get("instance_id")
+            and tracer.client_attributes.get("database")
+        ):
+            resources = self._extract_resource_from_path(call_details.metadata)
+            self._set_metrics_tracer_attributes(resources)
 
         ## Format method to be be spanner.<method name>
         method_name = self._remove_prefix(
             call_details.method, SPANNER_METHOD_PREFIX
         ).replace("/", ".")
 
-        SpannerMetricsTracerFactory.current_metrics_tracer.set_method(method_name)
-        SpannerMetricsTracerFactory.current_metrics_tracer.record_attempt_start()
+        tracer.set_method(method_name)
+        tracer.record_attempt_start()
         response = invoked_method(request_or_iterator, call_details)
-        SpannerMetricsTracerFactory.current_metrics_tracer.record_attempt_completion()
+        tracer.record_attempt_completion()
 
         # Process and send GFE metrics if enabled
-        if SpannerMetricsTracerFactory.current_metrics_tracer.gfe_enabled:
+        if tracer.gfe_enabled:
             metadata = response.initial_metadata()
-            SpannerMetricsTracerFactory.current_metrics_trace.record_gfe_metrics(
-                metadata
-            )
+            tracer.record_gfe_metrics(metadata)
         return response

{google_cloud_spanner-3.62.0 → google_cloud_spanner-3.63.0}/google/cloud/spanner_v1/metrics/spanner_metrics_tracer_factory.py

@@ -19,6 +19,7 @@ from .metrics_tracer_factory import MetricsTracerFactory
 import os
 import logging
 from .constants import SPANNER_SERVICE_NAME
+import contextvars
 
 try:
     import mmh3
@@ -43,7 +44,9 @@ class SpannerMetricsTracerFactory(MetricsTracerFactory):
     """A factory for creating SpannerMetricsTracer instances."""
 
     _metrics_tracer_factory: "SpannerMetricsTracerFactory" = None
-    current_metrics_tracer: MetricsTracer = None
+    _current_metrics_tracer_ctx = contextvars.ContextVar(
+        "current_metrics_tracer", default=None
+    )
 
     def __new__(
         cls, enabled: bool = True, gfe_enabled: bool = False
@@ -80,10 +83,22 @@ class SpannerMetricsTracerFactory(MetricsTracerFactory):
             cls._metrics_tracer_factory.gfe_enabled = gfe_enabled
 
             if cls._metrics_tracer_factory.enabled != enabled:
-                cls._metrics_tracer_factory.enabeld = enabled
+                cls._metrics_tracer_factory.enabled = enabled
 
         return cls._metrics_tracer_factory
 
+    @staticmethod
+    def get_current_tracer() -> MetricsTracer:
+        return SpannerMetricsTracerFactory._current_metrics_tracer_ctx.get()
+
+    @staticmethod
+    def set_current_tracer(tracer: MetricsTracer) -> contextvars.Token:
+        return SpannerMetricsTracerFactory._current_metrics_tracer_ctx.set(tracer)
+
+    @staticmethod
+    def reset_current_tracer(token: contextvars.Token):
+        SpannerMetricsTracerFactory._current_metrics_tracer_ctx.reset(token)
+
     @staticmethod
     def _generate_client_uid() -> str:
         """Generate a client UID in the form of uuidv4@pid@hostname.