From aa357b1deb6d536fb8e32399bcbbae145b274e3d Mon Sep 17 00:00:00 2001 From: Sakthivel Subramanian Date: Sat, 21 Nov 2026 20:33:14 +0000 Subject: [PATCH 1/4] fix(spanner): respect universe_domain and client_options in metrics exporter ## Problem - `CloudMonitoringMetricsExporter` always connected to `monitoring.googleapis.com`, ignoring `client_options.universe_domain` and `GOOGLE_CLOUD_UNIVERSE_DOMAIN`. - Clients with a custom `client_options.api_endpoint` still exported built-in metrics to `monitoring.googleapis.com`. - `Client.__init__` passed raw `project` and `credentials` instead of resolved `self.project` and `self._credentials`, causing fallback to ambient ADC. ## Solution - Pass resolved `self.project`, `self._credentials`, and filtered monitoring `client_options` to `_initialize_metrics` and `CloudMonitoringMetricsExporter`. - Skip built-in metrics export when a custom non-default `api_endpoint` is configured. - Configure `MetricServiceClient` via a transport callable so `universe_domain` and credentials validation work natively, re-scope Spanner-only scoped credentials to `monitoring.write`, and avoid ADC project fallback when explicit credentials are provided. - Add unit tests for both sync and async clients and the metrics exporter. --- .../google/cloud/spanner_v1/_async/client.py | 82 ++++++- .../google/cloud/spanner_v1/client.py | 85 ++++++- .../spanner_v1/metrics/metrics_exporter.py | 97 +++++++- .../tests/unit/_async/test_client_extra.py | 78 +++++++ .../tests/unit/test_client.py | 164 +++++++++++++ .../tests/unit/test_metrics_exporter.py | 215 +++++++++++++++++- 6 files changed, 704 insertions(+), 17 deletions(-) diff --git a/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py b/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py index 26364aa7fad0..7618d8b8b7d1 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py @@ -32,6 +32,7 @@ from typing import Optional import google.api_core.client_options +import google.api_core.universe import grpc from google.api_core.gapic_v1 import client_info from google.auth.credentials import AnonymousCredentials @@ -138,7 +139,63 @@ def _get_spanner_log_client_options_env(): return os.getenv(LOG_CLIENT_OPTIONS_ENV_VAR, "false").lower() == "true" -def _initialize_metrics(project, credentials, emulator_host=None): +def _is_custom_api_endpoint(client_options, universe_domain: str) -> bool: + """Return True if ``client_options`` configures a non-default Spanner endpoint. + + When a custom Spanner API endpoint (such as a Private Service Connect, + regional, or proxy endpoint) is configured, built-in metrics export to + Cloud Monitoring must be skipped to preserve endpoint confinement. + + Args: + client_options: Normalized ``ClientOptions`` instance or ``None``. + universe_domain: Resolved universe domain (for example, + ``"googleapis.com"``). + + Returns: + bool: ``True`` if ``api_endpoint`` is set to a non-default Spanner host. + """ + if not client_options or not client_options.api_endpoint: + return False + endpoint = client_options.api_endpoint.strip().lower() + default_host = f"spanner.{universe_domain.lower()}" + return endpoint not in ( + default_host, + f"{default_host}:443", + f"https://{default_host}", + f"https://{default_host}:443", + ) + + +def _build_monitoring_client_options(client_options): + """Build ``ClientOptions`` for Cloud Monitoring from Spanner client options. + + Only propagates options applicable to Cloud Monitoring (``universe_domain``, + ``quota_project_id``, and ``client_cert_source``). Spanner-specific or + credential-conflicting options (``api_endpoint``, ``api_audience``, + ``scopes``, ``credentials_file``, ``api_key``) are intentionally omitted. + + Args: + client_options: Normalized ``ClientOptions`` instance or ``None``. + + Returns: + Optional[google.api_core.client_options.ClientOptions]: Filtered + options for ``CloudMonitoringMetricsExporter``, or ``None``. + """ + if client_options is None: + return None + monitoring_options = {} + if getattr(client_options, "universe_domain", None): + monitoring_options["universe_domain"] = client_options.universe_domain + if getattr(client_options, "quota_project_id", None): + monitoring_options["quota_project_id"] = client_options.quota_project_id + if getattr(client_options, "client_cert_source", None): + monitoring_options["client_cert_source"] = client_options.client_cert_source + if not monitoring_options: + return None + return google.api_core.client_options.ClientOptions(**monitoring_options) + + +def _initialize_metrics(project, credentials, emulator_host=None, client_options=None): """ Initializes the Spanner built-in metrics. @@ -151,17 +208,33 @@ def _initialize_metrics(project, credentials, emulator_host=None): if not _metrics_monitor_initialized: meter_provider = metrics.NoOpMeterProvider() try: + normalized_options = ( + google.api_core.client_options.from_dict(client_options) + if isinstance(client_options, dict) + else client_options + ) + universe_domain = google.api_core.universe.determine_domain( + getattr(normalized_options, "universe_domain", None), + os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN"), + ) if ( not _get_spanner_emulator_host() and not emulator_host and not isinstance(credentials, AnonymousCredentials) + and not _is_custom_api_endpoint( + normalized_options, universe_domain + ) ): + monitoring_client_options = _build_monitoring_client_options( + normalized_options + ) meter_provider = MeterProvider( metric_readers=[ PeriodicExportingMetricReader( CloudMonitoringMetricsExporter( project_id=project, credentials=credentials, + client_options=monitoring_client_options, ), export_interval_millis=METRIC_EXPORT_INTERVAL_MS, ), @@ -421,7 +494,12 @@ def __init__( and not disable_builtin_metrics and HAS_GOOGLE_CLOUD_MONITORING_INSTALLED ): - _initialize_metrics(project, credentials, self._emulator_host) + _initialize_metrics( + self.project, + self._credentials, + self._emulator_host, + client_options=self._client_options, + ) else: SpannerMetricsTracerFactory(enabled=False) diff --git a/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py b/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py index 781603f92078..88108e9c6deb 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py @@ -34,6 +34,7 @@ from typing import Optional import google.api_core.client_options +import google.api_core.universe import grpc from google.api_core.gapic_v1 import client_info from google.auth.credentials import AnonymousCredentials @@ -119,7 +120,61 @@ def _get_spanner_log_client_options_env(): return os.getenv(LOG_CLIENT_OPTIONS_ENV_VAR, "false").lower() == "true" -def _initialize_metrics(project, credentials, emulator_host=None): +def _is_custom_api_endpoint(client_options, universe_domain: str) -> bool: + """Return True if ``client_options`` configures a non-default Spanner endpoint. + + When a custom Spanner API endpoint (such as a Private Service Connect, + regional, or proxy endpoint) is configured, built-in metrics export to + Cloud Monitoring must be skipped to preserve endpoint confinement. + + Args: + client_options: Normalized ``ClientOptions`` instance or ``None``. + universe_domain: Resolved universe domain (for example, + ``"googleapis.com"``). + + Returns: + bool: ``True`` if ``api_endpoint`` is set to a non-default Spanner host.""" + if not client_options or not client_options.api_endpoint: + return False + endpoint = client_options.api_endpoint.strip().lower() + default_host = f"spanner.{universe_domain.lower()}" + return endpoint not in ( + default_host, + f"{default_host}:443", + f"https://{default_host}", + f"https://{default_host}:443", + ) + + +def _build_monitoring_client_options(client_options): + """Build ``ClientOptions`` for Cloud Monitoring from Spanner client options. + + Only propagates options applicable to Cloud Monitoring (``universe_domain``, + ``quota_project_id``, and ``client_cert_source``). Spanner-specific or + credential-conflicting options (``api_endpoint``, ``api_audience``, + ``scopes``, ``credentials_file``, ``api_key``) are intentionally omitted. + + Args: + client_options: Normalized ``ClientOptions`` instance or ``None``. + + Returns: + Optional[google.api_core.client_options.ClientOptions]: Filtered + options for ``CloudMonitoringMetricsExporter``, or ``None``.""" + if client_options is None: + return None + monitoring_options = {} + if getattr(client_options, "universe_domain", None): + monitoring_options["universe_domain"] = client_options.universe_domain + if getattr(client_options, "quota_project_id", None): + monitoring_options["quota_project_id"] = client_options.quota_project_id + if getattr(client_options, "client_cert_source", None): + monitoring_options["client_cert_source"] = client_options.client_cert_source + if not monitoring_options: + return None + return google.api_core.client_options.ClientOptions(**monitoring_options) + + +def _initialize_metrics(project, credentials, emulator_host=None, client_options=None): """Initializes the Spanner built-in metrics. This function sets up the OpenTelemetry MeterProvider and the SpannerMetricsTracerFactory. @@ -130,16 +185,35 @@ def _initialize_metrics(project, credentials, emulator_host=None): if not _metrics_monitor_initialized: meter_provider = metrics.NoOpMeterProvider() try: + normalized_options = ( + google.api_core.client_options.from_dict(client_options) + if isinstance(client_options, dict) + else client_options + ) + universe_domain = google.api_core.universe.determine_domain( + getattr(normalized_options, "universe_domain", None), + os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN"), + ) if ( not _get_spanner_emulator_host() and (not emulator_host) and (not isinstance(credentials, AnonymousCredentials)) + and ( + not _is_custom_api_endpoint( + normalized_options, universe_domain + ) + ) ): + monitoring_client_options = _build_monitoring_client_options( + normalized_options + ) meter_provider = MeterProvider( metric_readers=[ PeriodicExportingMetricReader( CloudMonitoringMetricsExporter( - project_id=project, credentials=credentials + project_id=project, + credentials=credentials, + client_options=monitoring_client_options, ), export_interval_millis=METRIC_EXPORT_INTERVAL_MS, ) @@ -367,7 +441,12 @@ def __init__( and (not disable_builtin_metrics) and HAS_GOOGLE_CLOUD_MONITORING_INSTALLED ): - _initialize_metrics(project, credentials, self._emulator_host) + _initialize_metrics( + self.project, + self._credentials, + self._emulator_host, + client_options=self._client_options, + ) else: SpannerMetricsTracerFactory(enabled=False) self._route_to_leader_enabled = route_to_leader_enabled diff --git a/packages/google-cloud-spanner/google/cloud/spanner_v1/metrics/metrics_exporter.py b/packages/google-cloud-spanner/google/cloud/spanner_v1/metrics/metrics_exporter.py index eeecf56b08b8..798d113c6bf9 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/metrics/metrics_exporter.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/metrics/metrics_exporter.py @@ -27,6 +27,7 @@ from google.api.monitored_resource_pb2 import ( MonitoredResource, ) # pylint: disable=no-name-in-module +from google.api_core import client_options as client_options_lib from google.api_core.exceptions import ( DeadlineExceeded, InvalidArgument, @@ -95,6 +96,45 @@ ("grpc.primary_user_agent", _USER_AGENT), ] +# Scope required to write time series via CreateServiceTimeSeries. +_MONITORING_WRITE_SCOPE = "https://www.googleapis.com/auth/monitoring.write" +# Any of these scopes authorizes writing metrics to Cloud Monitoring. +_MONITORING_SCOPES = frozenset( + { + "https://www.googleapis.com/auth/cloud-platform", + "https://www.googleapis.com/auth/monitoring", + _MONITORING_WRITE_SCOPE, + } +) + + +def _get_monitoring_credentials( + credentials: Optional[ga_credentials.Credentials], +) -> Optional[ga_credentials.Credentials]: + """Return credentials able to authenticate against Cloud Monitoring. + + If ``credentials`` are already pinned to fixed scopes that do not include + Cloud Monitoring (for example, credentials scoped by ``ClientWithProject`` + to ``spanner.admin``), returns a copy scoped to ``monitoring.write`` so + that Cloud Monitoring RPCs succeed without mutating the Spanner client's + credentials. + + Args: + credentials: Credentials from the Spanner client, or ``None``. + + Returns: + Credentials suitable for ``MetricServiceClient``. + """ + if credentials is None: + return None + if ( + isinstance(credentials, ga_credentials.Scoped) + and not credentials.requires_scopes + and not _MONITORING_SCOPES.intersection(credentials.scopes or ()) + ): + return credentials.with_scopes([_MONITORING_WRITE_SCOPE]) + return credentials + # pylint is unable to resolve members of protobuf objects # pylint: disable=no-member @@ -110,6 +150,11 @@ class CloudMonitoringMetricsExporter(MetricExporter): Args: project_id: project id of your Google Cloud project. client: Client to upload metrics to Google Cloud Monitoring. + credentials: Optional credentials for authenticating with Cloud + Monitoring. + client_options: Optional client options (for example, + ``universe_domain`` or ``api_endpoint``) passed to + ``MetricServiceClient``. """ # Based on the cloud_monitoring exporter found here: https://github.com/GoogleCloudPlatform/opentelemetry-operations-python/blob/main/opentelemetry-exporter-gcp-monitoring/src/opentelemetry/exporter/cloud_monitoring/__init__.py @@ -119,28 +164,58 @@ def __init__( project_id: Optional[str] = None, client: Optional["MetricServiceClient"] = None, credentials: Optional[ga_credentials.Credentials] = None, + client_options: Optional[Union[client_options_lib.ClientOptions, dict]] = None, ): """Initialize a custom exporter to send metrics for the Spanner Service Metrics.""" # Default preferred_temporality is all CUMULATIVE so need to customize super().__init__() - # Create a new GRPC Client for Google Cloud Monitoring if not provided - self.client = client or MetricServiceClient( - transport=MetricServiceGrpcTransport( - channel=MetricServiceGrpcTransport.create_channel( - options=_OPTIONS, - credentials=credentials, + # Create a new gRPC Client for Google Cloud Monitoring if not provided. + # Pass a transport callable (not a pre-built channel) so MetricServiceClient + # resolves universe_domain / client_options and retains credentials for + # universe domain validation, while still applying custom gRPC options. + if client is not None: + self.client = client + else: + monitoring_credentials = _get_monitoring_credentials(credentials) + + def _create_channel(*args, **kwargs): + kwargs["options"] = _OPTIONS + return MetricServiceGrpcTransport.create_channel(*args, **kwargs) + + def _create_transport(**kwargs): + return MetricServiceGrpcTransport( + **kwargs, + channel=_create_channel, ) + + self.client = MetricServiceClient( + credentials=monitoring_credentials, + transport=_create_transport, + client_options=client_options, ) - ) - # Set project information + # Set project information without falling back to ambient ADC when + # explicit credentials were supplied. self.project_id: str - if not project_id: + if project_id: + self.project_id = project_id + elif credentials is not None: + creds_project_id = getattr(credentials, "project_id", None) + if not creds_project_id: + raise ValueError( + "project_id must be provided when explicit credentials do not " + "specify a project_id." + ) + self.project_id = str(creds_project_id) + else: _, default_project_id = google.auth.default() + if not default_project_id: + raise ValueError( + "project_id was not provided and could not be determined from " + "Application Default Credentials." + ) self.project_id = str(default_project_id) - else: - self.project_id = project_id self.project_name = self.client.common_project_path(self.project_id) def _batch_write(self, series: List["TimeSeries"], timeout_millis: float) -> None: diff --git a/packages/google-cloud-spanner/tests/unit/_async/test_client_extra.py b/packages/google-cloud-spanner/tests/unit/_async/test_client_extra.py index cca47a952ea8..923b2b2c0092 100644 --- a/packages/google-cloud-spanner/tests/unit/_async/test_client_extra.py +++ b/packages/google-cloud-spanner/tests/unit/_async/test_client_extra.py @@ -275,3 +275,81 @@ def test_initialize_metrics_anonymous_credentials(self): AnonymousCredentials(), ) set_mock.assert_called_once() + + def test_initialize_metrics_custom_api_endpoint_skips_exporter(self): + from google.api_core.client_options import ClientOptions + + from google.cloud.spanner_v1._async import client as MUT + + with ( + mock.patch( + "google.cloud.spanner_v1._async.client._metrics_monitor_initialized", + False, + ), + mock.patch( + "google.cloud.spanner_v1._async.client._get_spanner_emulator_host", + return_value=None, + ), + mock.patch( + "google.cloud.spanner_v1._async.client.CloudMonitoringMetricsExporter" + ) as mock_exporter, + mock.patch( + "google.cloud.spanner_v1._async.client.metrics.set_meter_provider" + ) as mock_set_provider, + mock.patch( + "google.cloud.spanner_v1._async.client.SpannerMetricsTracerFactory" + ), + ): + MUT._initialize_metrics( + "project", + self.credentials, + client_options=ClientOptions(api_endpoint="private-psc.internal:443"), + ) + mock_exporter.assert_not_called() + mock_set_provider.assert_called_once() + self.assertIsInstance( + mock_set_provider.call_args[0][0], + MUT.metrics.NoOpMeterProvider, + ) + + def test_client_passes_resolved_project_credentials_and_universe_domain(self): + import os + + from google.cloud.spanner_v1._async import client as MUT + + creds = build_scoped_credentials() + creds.project_id = "resolved-async-project" + with ( + mock.patch.dict(os.environ, {"SPANNER_DISABLE_BUILTIN_METRICS": "false"}), + mock.patch( + "google.cloud.spanner_v1._async.client._metrics_monitor_initialized", + False, + ), + mock.patch("google.cloud.spanner_v1._async.client.metrics"), + mock.patch( + "google.cloud.spanner_v1._async.client.CloudMonitoringMetricsExporter" + ) as mock_exporter, + mock.patch( + "google.cloud.spanner_v1._async.client.PeriodicExportingMetricReader" + ), + mock.patch("google.cloud.spanner_v1._async.client.MeterProvider"), + mock.patch( + "google.cloud.spanner_v1._async.client.SpannerMetricsTracerFactory" + ), + ): + os.environ.pop("GOOGLE_CLOUD_PROJECT", None) + os.environ.pop("GCLOUD_PROJECT", None) + client = MUT.Client( + project=None, + credentials=creds, + client_options={ + "universe_domain": "async.universe", + "api_audience": "https://spanner.async.universe", + }, + ) + mock_exporter.assert_called_once() + _, kwargs = mock_exporter.call_args + self.assertEqual(kwargs["project_id"], "resolved-async-project") + self.assertIs(kwargs["credentials"], client._credentials) + self.assertEqual(kwargs["client_options"].universe_domain, "async.universe") + self.assertIsNone(kwargs["client_options"].api_audience) diff --git a/packages/google-cloud-spanner/tests/unit/test_client.py b/packages/google-cloud-spanner/tests/unit/test_client.py index c8d4a9895d20..6477611d7709 100644 --- a/packages/google-cloud-spanner/tests/unit/test_client.py +++ b/packages/google-cloud-spanner/tests/unit/test_client.py @@ -1165,3 +1165,167 @@ def test_initialize_metrics_anonymous_credentials(self): AnonymousCredentials(), ) set_mock.assert_called_once() + + def test_initialize_metrics_custom_api_endpoint_skips_exporter(self): + from google.api_core.client_options import ClientOptions + + from google.cloud.spanner_v1 import client as MUT + + custom_endpoints = [ + {"api_endpoint": "private-spanner.internal:443"}, + ClientOptions(api_endpoint="spanner.us-central1.rep.googleapis.com"), + ClientOptions( + api_endpoint="spanner.googleapis.com", + universe_domain="my-universe.com", + ), + ClientOptions(api_endpoint="spanner.googleapis.com@evil.example"), + ] + for client_options in custom_endpoints: + with ( + mock.patch( + "google.cloud.spanner_v1.client._metrics_monitor_initialized", + False, + ), + mock.patch( + "google.cloud.spanner_v1.client._get_spanner_emulator_host", + return_value=None, + ), + mock.patch( + "google.cloud.spanner_v1.client.CloudMonitoringMetricsExporter" + ) as mock_exporter, + mock.patch( + "google.cloud.spanner_v1.client.metrics.set_meter_provider" + ) as mock_set_provider, + mock.patch( + "google.cloud.spanner_v1.client.SpannerMetricsTracerFactory" + ), + ): + MUT._initialize_metrics( + "project", + mock.Mock(), + client_options=client_options, + ) + mock_exporter.assert_not_called() + mock_set_provider.assert_called_once() + self.assertIsInstance( + mock_set_provider.call_args[0][0], + MUT.metrics.NoOpMeterProvider, + ) + + def test_initialize_metrics_default_endpoint_and_universe_propagation(self): + from google.api_core.client_options import ClientOptions + + from google.cloud.spanner_v1 import client as MUT + + def cert_source(): + return (b"cert", b"key") + + creds = mock.Mock() + client_options = ClientOptions( + api_endpoint="https://spanner.my-universe.com:443", + universe_domain="my-universe.com", + quota_project_id="quota-proj", + client_cert_source=cert_source, + scopes=["https://www.googleapis.com/auth/spanner.admin"], + api_audience="https://spanner.my-universe.com", + credentials_file="/tmp/fake-creds.json", + ) + with ( + mock.patch( + "google.cloud.spanner_v1.client._metrics_monitor_initialized", + False, + ), + mock.patch( + "google.cloud.spanner_v1.client._get_spanner_emulator_host", + return_value=None, + ), + mock.patch( + "google.cloud.spanner_v1.client.CloudMonitoringMetricsExporter" + ) as mock_exporter, + mock.patch("google.cloud.spanner_v1.client.PeriodicExportingMetricReader"), + mock.patch("google.cloud.spanner_v1.client.MeterProvider"), + mock.patch("google.cloud.spanner_v1.client.metrics.set_meter_provider"), + mock.patch("google.cloud.spanner_v1.client.SpannerMetricsTracerFactory"), + ): + MUT._initialize_metrics( + "my-project", + creds, + client_options=client_options, + ) + + mock_exporter.assert_called_once() + _, kwargs = mock_exporter.call_args + self.assertEqual(kwargs["project_id"], "my-project") + self.assertIs(kwargs["credentials"], creds) + monitoring_opts = kwargs["client_options"] + self.assertIsInstance(monitoring_opts, ClientOptions) + self.assertEqual(monitoring_opts.universe_domain, "my-universe.com") + self.assertEqual(monitoring_opts.quota_project_id, "quota-proj") + self.assertIs(monitoring_opts.client_cert_source, cert_source) + self.assertIsNone(monitoring_opts.api_endpoint) + self.assertIsNone(monitoring_opts.scopes) + self.assertIsNone(monitoring_opts.api_audience) + self.assertIsNone(monitoring_opts.credentials_file) + self.assertIsNone(monitoring_opts.api_key) + + @mock.patch("google.cloud.spanner_v1.client.metrics") + @mock.patch("google.cloud.spanner_v1.client.CloudMonitoringMetricsExporter") + @mock.patch("google.cloud.spanner_v1.client.PeriodicExportingMetricReader") + @mock.patch("google.cloud.spanner_v1.client.MeterProvider") + @mock.patch("google.cloud.spanner_v1.client.SpannerMetricsTracerFactory") + @mock.patch.dict(os.environ, {"SPANNER_DISABLE_BUILTIN_METRICS": "false"}) + def test_client_passes_resolved_project_credentials_and_options_to_metrics( + self, + mock_spanner_metrics_factory, + mock_meter_provider, + mock_periodic_reader, + mock_exporter, + mock_metrics, + ): + from google.cloud.spanner_v1 import client as MUT + + creds = build_scoped_credentials() + creds.project_id = "resolved-from-creds" + MUT._metrics_monitor_initialized = False + try: + with mock.patch.dict(os.environ, {}, clear=False): + os.environ.pop("GOOGLE_CLOUD_PROJECT", None) + os.environ.pop("GCLOUD_PROJECT", None) + client = MUT.Client( + project=None, + credentials=creds, + client_options={"universe_domain": "custom.universe"}, + ) + mock_exporter.assert_called_once() + _, kwargs = mock_exporter.call_args + self.assertEqual(kwargs["project_id"], "resolved-from-creds") + self.assertIs(kwargs["credentials"], client._credentials) + self.assertEqual( + kwargs["client_options"].universe_domain, "custom.universe" + ) + finally: + MUT._metrics_monitor_initialized = False + + @mock.patch("google.cloud.spanner_v1.client.metrics") + @mock.patch("google.cloud.spanner_v1.client.CloudMonitoringMetricsExporter") + @mock.patch("google.cloud.spanner_v1.client.SpannerMetricsTracerFactory") + @mock.patch.dict(os.environ, {"SPANNER_DISABLE_BUILTIN_METRICS": "false"}) + def test_client_custom_api_endpoint_skips_metrics_exporter( + self, + mock_spanner_metrics_factory, + mock_exporter, + mock_metrics, + ): + from google.cloud.spanner_v1 import client as MUT + + creds = build_scoped_credentials() + MUT._metrics_monitor_initialized = False + try: + MUT.Client( + project="my-project", + credentials=creds, + client_options={"api_endpoint": "private-psc.internal:443"}, + ) + mock_exporter.assert_not_called() + finally: + MUT._metrics_monitor_initialized = False diff --git a/packages/google-cloud-spanner/tests/unit/test_metrics_exporter.py b/packages/google-cloud-spanner/tests/unit/test_metrics_exporter.py index fde06dcdb210..0767e74af36a 100644 --- a/packages/google-cloud-spanner/tests/unit/test_metrics_exporter.py +++ b/packages/google-cloud-spanner/tests/unit/test_metrics_exporter.py @@ -12,11 +12,13 @@ # See the License for the specific language governing permissions and # limitations under the License. +import os import unittest from unittest.mock import MagicMock, Mock, patch from google.api.metric_pb2 import MetricDescriptor -from google.auth.credentials import AnonymousCredentials +from google.api_core.client_options import ClientOptions +from google.auth.credentials import AnonymousCredentials, Credentials, Scoped from opentelemetry.sdk.metrics import MeterProvider from opentelemetry.sdk.metrics.export import ( AggregationTemporality, @@ -496,3 +498,214 @@ def test_to_point(self): ) self.assertIsNone(converted_hist_point_no_count.interval.start_time) self.assertIsNotNone(converted_hist_point_no_count.interval.end_time) + + def test_init_with_universe_domain_client_options(self): + """Verify universe_domain in client_options sets the monitoring host and preserves options.""" + from google.cloud.spanner_v1.metrics.metrics_exporter import _OPTIONS + + creds = AnonymousCredentials() + with ( + patch.dict( + os.environ, + { + "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false", + "GOOGLE_API_USE_MTLS_ENDPOINT": "never", + }, + ), + patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.MetricServiceGrpcTransport.create_channel", + return_value=MagicMock(), + ) as mock_create_channel, + ): + exporter = CloudMonitoringMetricsExporter( + project_id=PROJECT_ID, + credentials=creds, + client_options=ClientOptions(universe_domain="my-universe.com"), + ) + + self.assertEqual(exporter.client.universe_domain, "my-universe.com") + self.assertEqual(exporter.client.api_endpoint, "monitoring.my-universe.com") + self.assertIs(exporter.client.transport._credentials, creds) + mock_create_channel.assert_called_once() + args, kwargs = mock_create_channel.call_args + self.assertEqual(args[0], "monitoring.my-universe.com:443") + self.assertEqual(kwargs["options"], _OPTIONS) + self.assertIs(kwargs["credentials"], creds) + + def test_init_with_universe_domain_env_var(self): + """Verify GOOGLE_CLOUD_UNIVERSE_DOMAIN env var sets the monitoring host.""" + creds = AnonymousCredentials() + with ( + patch.dict( + os.environ, + { + "GOOGLE_CLOUD_UNIVERSE_DOMAIN": "env-universe.com", + "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false", + "GOOGLE_API_USE_MTLS_ENDPOINT": "never", + }, + ), + patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.MetricServiceGrpcTransport.create_channel", + return_value=MagicMock(), + ) as mock_create_channel, + ): + exporter = CloudMonitoringMetricsExporter( + project_id=PROJECT_ID, + credentials=creds, + ) + + self.assertEqual(exporter.client.universe_domain, "env-universe.com") + self.assertEqual( + exporter.client.api_endpoint, "monitoring.env-universe.com" + ) + mock_create_channel.assert_called_once() + args, _ = mock_create_channel.call_args + self.assertEqual(args[0], "monitoring.env-universe.com:443") + + def test_init_with_explicit_api_endpoint_client_options(self): + """Verify explicit api_endpoint in client_options overrides the monitoring host.""" + creds = AnonymousCredentials() + with patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.MetricServiceGrpcTransport.create_channel", + return_value=MagicMock(), + ) as mock_create_channel: + exporter = CloudMonitoringMetricsExporter( + project_id=PROJECT_ID, + credentials=creds, + client_options={"api_endpoint": "custom-monitoring.internal:443"}, + ) + + self.assertEqual( + exporter.client.api_endpoint, "custom-monitoring.internal:443" + ) + mock_create_channel.assert_called_once() + args, _ = mock_create_channel.call_args + self.assertEqual(args[0], "custom-monitoring.internal:443") + + def test_init_rescopes_spanner_scoped_credentials(self): + """Verify credentials pinned to non-monitoring scopes are re-scoped to monitoring.write.""" + + class _FakeScopedCredentials(Credentials, Scoped): + def __init__(self, scopes, requires_scopes=False): + super().__init__() + self._scopes = scopes + self._requires_scopes = requires_scopes + + @property + def requires_scopes(self): + return self._requires_scopes + + @property + def scopes(self): + return self._scopes + + def with_scopes(self, scopes, default_scopes=None): + return _FakeScopedCredentials(tuple(scopes), requires_scopes=False) + + def refresh(self, request): + pass + + spanner_creds = _FakeScopedCredentials( + scopes=("https://www.googleapis.com/auth/spanner.admin",), + requires_scopes=False, + ) + with patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.MetricServiceGrpcTransport.create_channel", + return_value=MagicMock(), + ) as mock_create_channel: + CloudMonitoringMetricsExporter( + project_id=PROJECT_ID, + credentials=spanner_creds, + ) + + _, kwargs = mock_create_channel.call_args + self.assertEqual( + kwargs["credentials"].scopes, + ("https://www.googleapis.com/auth/monitoring.write",), + ) + + # Credentials that already cover Cloud Monitoring should not be re-scoped. + monitoring_creds = _FakeScopedCredentials( + scopes=("https://www.googleapis.com/auth/cloud-platform",), + requires_scopes=False, + ) + with patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.MetricServiceGrpcTransport.create_channel", + return_value=MagicMock(), + ) as mock_create_channel: + CloudMonitoringMetricsExporter( + project_id=PROJECT_ID, + credentials=monitoring_creds, + ) + + _, kwargs = mock_create_channel.call_args + self.assertIs(kwargs["credentials"], monitoring_creds) + + def test_init_uses_credentials_project_id_without_adc(self): + """Verify explicit credentials project_id is used without falling back to ADC.""" + creds = AnonymousCredentials() + creds.project_id = "creds-project-id" + with ( + patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.google.auth.default" + ) as mock_auth_default, + patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.MetricServiceGrpcTransport.create_channel", + return_value=MagicMock(), + ), + ): + exporter = CloudMonitoringMetricsExporter( + project_id=None, + credentials=creds, + ) + + mock_auth_default.assert_not_called() + self.assertEqual(exporter.project_id, "creds-project-id") + self.assertEqual(exporter.project_name, "projects/creds-project-id") + + def test_init_raises_when_explicit_credentials_missing_project_id(self): + """Verify missing project_id with explicit credentials does not fall back to ambient ADC.""" + creds = AnonymousCredentials() + with ( + patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.google.auth.default" + ) as mock_auth_default, + patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.MetricServiceGrpcTransport.create_channel", + return_value=MagicMock(), + ), + ): + with self.assertRaises(ValueError): + CloudMonitoringMetricsExporter( + project_id=None, + credentials=creds, + ) + + mock_auth_default.assert_not_called() + + def test_init_adc_project_fallback_when_no_credentials(self): + """Verify ADC fallback works when neither project_id nor credentials are provided.""" + mock_client = MagicMock() + mock_client.common_project_path.side_effect = lambda p: f"projects/{p}" + with patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.google.auth.default", + return_value=(AnonymousCredentials(), "adc-project"), + ): + exporter = CloudMonitoringMetricsExporter( + project_id=None, + client=mock_client, + credentials=None, + ) + self.assertEqual(exporter.project_id, "adc-project") + self.assertEqual(exporter.project_name, "projects/adc-project") + + with patch( + "google.cloud.spanner_v1.metrics.metrics_exporter.google.auth.default", + return_value=(AnonymousCredentials(), None), + ): + with self.assertRaises(ValueError): + CloudMonitoringMetricsExporter( + project_id=None, + client=mock_client, + credentials=None, + ) From 6ccfad7aecd4bbfa4d27b8efc09756b09861c14a Mon Sep 17 00:00:00 2001 From: Sakthivel Subramanian Date: Sat, 21 Nov 2026 21:02:41 +0000 Subject: [PATCH 2/4] Addressed comments --- .../google/cloud/spanner_v1/_async/client.py | 87 ++++-------------- .../google/cloud/spanner_v1/client.py | 85 +++-------------- .../spanner_v1/metrics/metrics_exporter.py | 92 ++++++------------- .../tests/unit/test_client.py | 9 +- 4 files changed, 57 insertions(+), 216 deletions(-) diff --git a/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py b/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py index 7618d8b8b7d1..aa5809d2db24 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py @@ -32,7 +32,6 @@ from typing import Optional import google.api_core.client_options -import google.api_core.universe import grpc from google.api_core.gapic_v1 import client_info from google.auth.credentials import AnonymousCredentials @@ -139,62 +138,6 @@ def _get_spanner_log_client_options_env(): return os.getenv(LOG_CLIENT_OPTIONS_ENV_VAR, "false").lower() == "true" -def _is_custom_api_endpoint(client_options, universe_domain: str) -> bool: - """Return True if ``client_options`` configures a non-default Spanner endpoint. - - When a custom Spanner API endpoint (such as a Private Service Connect, - regional, or proxy endpoint) is configured, built-in metrics export to - Cloud Monitoring must be skipped to preserve endpoint confinement. - - Args: - client_options: Normalized ``ClientOptions`` instance or ``None``. - universe_domain: Resolved universe domain (for example, - ``"googleapis.com"``). - - Returns: - bool: ``True`` if ``api_endpoint`` is set to a non-default Spanner host. - """ - if not client_options or not client_options.api_endpoint: - return False - endpoint = client_options.api_endpoint.strip().lower() - default_host = f"spanner.{universe_domain.lower()}" - return endpoint not in ( - default_host, - f"{default_host}:443", - f"https://{default_host}", - f"https://{default_host}:443", - ) - - -def _build_monitoring_client_options(client_options): - """Build ``ClientOptions`` for Cloud Monitoring from Spanner client options. - - Only propagates options applicable to Cloud Monitoring (``universe_domain``, - ``quota_project_id``, and ``client_cert_source``). Spanner-specific or - credential-conflicting options (``api_endpoint``, ``api_audience``, - ``scopes``, ``credentials_file``, ``api_key``) are intentionally omitted. - - Args: - client_options: Normalized ``ClientOptions`` instance or ``None``. - - Returns: - Optional[google.api_core.client_options.ClientOptions]: Filtered - options for ``CloudMonitoringMetricsExporter``, or ``None``. - """ - if client_options is None: - return None - monitoring_options = {} - if getattr(client_options, "universe_domain", None): - monitoring_options["universe_domain"] = client_options.universe_domain - if getattr(client_options, "quota_project_id", None): - monitoring_options["quota_project_id"] = client_options.quota_project_id - if getattr(client_options, "client_cert_source", None): - monitoring_options["client_cert_source"] = client_options.client_cert_source - if not monitoring_options: - return None - return google.api_core.client_options.ClientOptions(**monitoring_options) - - def _initialize_metrics(project, credentials, emulator_host=None, client_options=None): """ Initializes the Spanner built-in metrics. @@ -208,25 +151,27 @@ def _initialize_metrics(project, credentials, emulator_host=None, client_options if not _metrics_monitor_initialized: meter_provider = metrics.NoOpMeterProvider() try: - normalized_options = ( - google.api_core.client_options.from_dict(client_options) - if isinstance(client_options, dict) - else client_options - ) - universe_domain = google.api_core.universe.determine_domain( - getattr(normalized_options, "universe_domain", None), - os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN"), + if isinstance(client_options, dict): + client_options = google.api_core.client_options.from_dict( + client_options + ) + # Skip metrics export when a custom Spanner api_endpoint is set. + has_custom_endpoint = bool( + client_options and client_options.api_endpoint ) if ( not _get_spanner_emulator_host() and not emulator_host and not isinstance(credentials, AnonymousCredentials) - and not _is_custom_api_endpoint( - normalized_options, universe_domain - ) + and not has_custom_endpoint ): - monitoring_client_options = _build_monitoring_client_options( - normalized_options + # Only forward universe_domain to Cloud Monitoring. + monitoring_options = ( + google.api_core.client_options.ClientOptions( + universe_domain=client_options.universe_domain + ) + if client_options and client_options.universe_domain + else None ) meter_provider = MeterProvider( metric_readers=[ @@ -234,7 +179,7 @@ def _initialize_metrics(project, credentials, emulator_host=None, client_options CloudMonitoringMetricsExporter( project_id=project, credentials=credentials, - client_options=monitoring_client_options, + client_options=monitoring_options, ), export_interval_millis=METRIC_EXPORT_INTERVAL_MS, ), diff --git a/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py b/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py index 88108e9c6deb..8806221e9f3c 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py @@ -34,7 +34,6 @@ from typing import Optional import google.api_core.client_options -import google.api_core.universe import grpc from google.api_core.gapic_v1 import client_info from google.auth.credentials import AnonymousCredentials @@ -120,60 +119,6 @@ def _get_spanner_log_client_options_env(): return os.getenv(LOG_CLIENT_OPTIONS_ENV_VAR, "false").lower() == "true" -def _is_custom_api_endpoint(client_options, universe_domain: str) -> bool: - """Return True if ``client_options`` configures a non-default Spanner endpoint. - - When a custom Spanner API endpoint (such as a Private Service Connect, - regional, or proxy endpoint) is configured, built-in metrics export to - Cloud Monitoring must be skipped to preserve endpoint confinement. - - Args: - client_options: Normalized ``ClientOptions`` instance or ``None``. - universe_domain: Resolved universe domain (for example, - ``"googleapis.com"``). - - Returns: - bool: ``True`` if ``api_endpoint`` is set to a non-default Spanner host.""" - if not client_options or not client_options.api_endpoint: - return False - endpoint = client_options.api_endpoint.strip().lower() - default_host = f"spanner.{universe_domain.lower()}" - return endpoint not in ( - default_host, - f"{default_host}:443", - f"https://{default_host}", - f"https://{default_host}:443", - ) - - -def _build_monitoring_client_options(client_options): - """Build ``ClientOptions`` for Cloud Monitoring from Spanner client options. - - Only propagates options applicable to Cloud Monitoring (``universe_domain``, - ``quota_project_id``, and ``client_cert_source``). Spanner-specific or - credential-conflicting options (``api_endpoint``, ``api_audience``, - ``scopes``, ``credentials_file``, ``api_key``) are intentionally omitted. - - Args: - client_options: Normalized ``ClientOptions`` instance or ``None``. - - Returns: - Optional[google.api_core.client_options.ClientOptions]: Filtered - options for ``CloudMonitoringMetricsExporter``, or ``None``.""" - if client_options is None: - return None - monitoring_options = {} - if getattr(client_options, "universe_domain", None): - monitoring_options["universe_domain"] = client_options.universe_domain - if getattr(client_options, "quota_project_id", None): - monitoring_options["quota_project_id"] = client_options.quota_project_id - if getattr(client_options, "client_cert_source", None): - monitoring_options["client_cert_source"] = client_options.client_cert_source - if not monitoring_options: - return None - return google.api_core.client_options.ClientOptions(**monitoring_options) - - def _initialize_metrics(project, credentials, emulator_host=None, client_options=None): """Initializes the Spanner built-in metrics. @@ -185,27 +130,25 @@ def _initialize_metrics(project, credentials, emulator_host=None, client_options if not _metrics_monitor_initialized: meter_provider = metrics.NoOpMeterProvider() try: - normalized_options = ( - google.api_core.client_options.from_dict(client_options) - if isinstance(client_options, dict) - else client_options - ) - universe_domain = google.api_core.universe.determine_domain( - getattr(normalized_options, "universe_domain", None), - os.getenv("GOOGLE_CLOUD_UNIVERSE_DOMAIN"), + if isinstance(client_options, dict): + client_options = google.api_core.client_options.from_dict( + client_options + ) + has_custom_endpoint = bool( + client_options and client_options.api_endpoint ) if ( not _get_spanner_emulator_host() and (not emulator_host) and (not isinstance(credentials, AnonymousCredentials)) - and ( - not _is_custom_api_endpoint( - normalized_options, universe_domain - ) - ) + and (not has_custom_endpoint) ): - monitoring_client_options = _build_monitoring_client_options( - normalized_options + monitoring_options = ( + google.api_core.client_options.ClientOptions( + universe_domain=client_options.universe_domain + ) + if client_options and client_options.universe_domain + else None ) meter_provider = MeterProvider( metric_readers=[ @@ -213,7 +156,7 @@ def _initialize_metrics(project, credentials, emulator_host=None, client_options CloudMonitoringMetricsExporter( project_id=project, credentials=credentials, - client_options=monitoring_client_options, + client_options=monitoring_options, ), export_interval_millis=METRIC_EXPORT_INTERVAL_MS, ) diff --git a/packages/google-cloud-spanner/google/cloud/spanner_v1/metrics/metrics_exporter.py b/packages/google-cloud-spanner/google/cloud/spanner_v1/metrics/metrics_exporter.py index 798d113c6bf9..02ae24ec542f 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/metrics/metrics_exporter.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/metrics/metrics_exporter.py @@ -96,9 +96,8 @@ ("grpc.primary_user_agent", _USER_AGENT), ] -# Scope required to write time series via CreateServiceTimeSeries. +# Scopes that authorize writing time series to Cloud Monitoring. _MONITORING_WRITE_SCOPE = "https://www.googleapis.com/auth/monitoring.write" -# Any of these scopes authorizes writing metrics to Cloud Monitoring. _MONITORING_SCOPES = frozenset( { "https://www.googleapis.com/auth/cloud-platform", @@ -108,34 +107,6 @@ ) -def _get_monitoring_credentials( - credentials: Optional[ga_credentials.Credentials], -) -> Optional[ga_credentials.Credentials]: - """Return credentials able to authenticate against Cloud Monitoring. - - If ``credentials`` are already pinned to fixed scopes that do not include - Cloud Monitoring (for example, credentials scoped by ``ClientWithProject`` - to ``spanner.admin``), returns a copy scoped to ``monitoring.write`` so - that Cloud Monitoring RPCs succeed without mutating the Spanner client's - credentials. - - Args: - credentials: Credentials from the Spanner client, or ``None``. - - Returns: - Credentials suitable for ``MetricServiceClient``. - """ - if credentials is None: - return None - if ( - isinstance(credentials, ga_credentials.Scoped) - and not credentials.requires_scopes - and not _MONITORING_SCOPES.intersection(credentials.scopes or ()) - ): - return credentials.with_scopes([_MONITORING_WRITE_SCOPE]) - return credentials - - # pylint is unable to resolve members of protobuf objects # pylint: disable=no-member # pylint: disable=too-many-branches @@ -170,52 +141,41 @@ def __init__( # Default preferred_temporality is all CUMULATIVE so need to customize super().__init__() - # Create a new gRPC Client for Google Cloud Monitoring if not provided. - # Pass a transport callable (not a pre-built channel) so MetricServiceClient - # resolves universe_domain / client_options and retains credentials for - # universe domain validation, while still applying custom gRPC options. if client is not None: self.client = client else: - monitoring_credentials = _get_monitoring_credentials(credentials) - - def _create_channel(*args, **kwargs): - kwargs["options"] = _OPTIONS - return MetricServiceGrpcTransport.create_channel(*args, **kwargs) - - def _create_transport(**kwargs): - return MetricServiceGrpcTransport( - **kwargs, - channel=_create_channel, + # Re-scope credentials pinned to Spanner-only scopes for Cloud Monitoring. + monitoring_credentials = credentials + if ( + isinstance(credentials, ga_credentials.Scoped) + and not credentials.requires_scopes + and not _MONITORING_SCOPES.intersection(credentials.scopes or ()) + ): + monitoring_credentials = credentials.with_scopes( + [_MONITORING_WRITE_SCOPE] ) + # Pass transport/channel callables so MetricServiceClient resolves + # universe_domain and validates credentials while keeping _OPTIONS. self.client = MetricServiceClient( credentials=monitoring_credentials, - transport=_create_transport, client_options=client_options, + transport=lambda **kwargs: MetricServiceGrpcTransport( + **kwargs, + channel=lambda *a, **kw: MetricServiceGrpcTransport.create_channel( + *a, **{**kw, "options": _OPTIONS} + ), + ), ) - # Set project information without falling back to ambient ADC when - # explicit credentials were supplied. - self.project_id: str - if project_id: - self.project_id = project_id - elif credentials is not None: - creds_project_id = getattr(credentials, "project_id", None) - if not creds_project_id: - raise ValueError( - "project_id must be provided when explicit credentials do not " - "specify a project_id." - ) - self.project_id = str(creds_project_id) - else: - _, default_project_id = google.auth.default() - if not default_project_id: - raise ValueError( - "project_id was not provided and could not be determined from " - "Application Default Credentials." - ) - self.project_id = str(default_project_id) + # Avoid ambient ADC project fallback when explicit credentials are provided. + if not project_id: + project_id = getattr(credentials, "project_id", None) + if not project_id and credentials is None: + _, project_id = google.auth.default() + if not project_id: + raise ValueError("project_id could not be determined.") + self.project_id = str(project_id) self.project_name = self.client.common_project_path(self.project_id) def _batch_write(self, series: List["TimeSeries"], timeout_millis: float) -> None: diff --git a/packages/google-cloud-spanner/tests/unit/test_client.py b/packages/google-cloud-spanner/tests/unit/test_client.py index 6477611d7709..8d7f74905414 100644 --- a/packages/google-cloud-spanner/tests/unit/test_client.py +++ b/packages/google-cloud-spanner/tests/unit/test_client.py @@ -1212,20 +1212,15 @@ def test_initialize_metrics_custom_api_endpoint_skips_exporter(self): MUT.metrics.NoOpMeterProvider, ) - def test_initialize_metrics_default_endpoint_and_universe_propagation(self): + def test_initialize_metrics_universe_propagation_and_option_filtering(self): from google.api_core.client_options import ClientOptions from google.cloud.spanner_v1 import client as MUT - def cert_source(): - return (b"cert", b"key") - creds = mock.Mock() client_options = ClientOptions( - api_endpoint="https://spanner.my-universe.com:443", universe_domain="my-universe.com", quota_project_id="quota-proj", - client_cert_source=cert_source, scopes=["https://www.googleapis.com/auth/spanner.admin"], api_audience="https://spanner.my-universe.com", credentials_file="/tmp/fake-creds.json", @@ -1260,8 +1255,6 @@ def cert_source(): monitoring_opts = kwargs["client_options"] self.assertIsInstance(monitoring_opts, ClientOptions) self.assertEqual(monitoring_opts.universe_domain, "my-universe.com") - self.assertEqual(monitoring_opts.quota_project_id, "quota-proj") - self.assertIs(monitoring_opts.client_cert_source, cert_source) self.assertIsNone(monitoring_opts.api_endpoint) self.assertIsNone(monitoring_opts.scopes) self.assertIsNone(monitoring_opts.api_audience) From 1713c72c5d6fd4993009ded8326f4f38e1f4b127 Mon Sep 17 00:00:00 2001 From: Sakthivel Subramanian Date: Sat, 21 Nov 2026 21:10:26 +0000 Subject: [PATCH 3/4] Addressed comments --- .../test_metrics_exporter_endpoint.py | 337 ++++++++++++++++++ 1 file changed, 337 insertions(+) create mode 100644 packages/google-cloud-spanner/tests/mockserver_tests/test_metrics_exporter_endpoint.py diff --git a/packages/google-cloud-spanner/tests/mockserver_tests/test_metrics_exporter_endpoint.py b/packages/google-cloud-spanner/tests/mockserver_tests/test_metrics_exporter_endpoint.py new file mode 100644 index 000000000000..c0a61d49020d --- /dev/null +++ b/packages/google-cloud-spanner/tests/mockserver_tests/test_metrics_exporter_endpoint.py @@ -0,0 +1,337 @@ +# 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. + +import os +from concurrent import futures +from unittest import mock + +import grpc +from google.api_core.client_options import ClientOptions +from google.auth.credentials import Credentials, Scoped +from google.cloud.monitoring_v3 import CreateTimeSeriesRequest +from google.protobuf import empty_pb2 +from opentelemetry import metrics +from opentelemetry.sdk.metrics import MeterProvider +from opentelemetry.sdk.metrics.export import InMemoryMetricReader + +import google.cloud.spanner_v1.client as client_mod +from google.cloud.spanner_v1 import Client +from google.cloud.spanner_v1.metrics.constants import ( + BUILT_IN_METRICS_METER_NAME, + METRIC_NAME_OPERATION_COUNT, + NATIVE_METRICS_PREFIX, +) +from google.cloud.spanner_v1.metrics.metrics_exporter import ( + CloudMonitoringMetricsExporter, +) +from google.cloud.spanner_v1.metrics.spanner_metrics_tracer_factory import ( + SpannerMetricsTracerFactory, +) +from tests.mockserver_tests.mock_server_test_base import MockServerTestBase + + +class _FakeUniverseCredentials(Credentials, Scoped): + """Minimal Scoped credentials with configurable universe_domain and project_id.""" + + def __init__( + self, + universe_domain="googleapis.com", + project_id="resolved-project", + scopes=("https://www.googleapis.com/auth/spanner.admin",), + requires_scopes=False, + ): + super().__init__() + self._universe_domain = universe_domain + self.project_id = project_id + self._scopes = scopes + self._requires_scopes = requires_scopes + + @property + def universe_domain(self): + return self._universe_domain + + @property + def requires_scopes(self): + return self._requires_scopes + + @property + def scopes(self): + return self._scopes + + def with_scopes(self, scopes, default_scopes=None): + return _FakeUniverseCredentials( + universe_domain=self._universe_domain, + project_id=self.project_id, + scopes=tuple(scopes), + requires_scopes=False, + ) + + def refresh(self, request): + self.token = "fake-token" + + +class _MockMonitoringServer: + """Local in-process gRPC server implementing CreateServiceTimeSeries.""" + + def __init__(self): + self.requests = [] + self.metadata = [] + self._server = grpc.server(futures.ThreadPoolExecutor(max_workers=2)) + handler = grpc.method_handlers_generic_handler( + "google.monitoring.v3.MetricService", + { + "CreateServiceTimeSeries": grpc.unary_unary_rpc_method_handler( + self._create_service_time_series, + request_deserializer=CreateTimeSeriesRequest.deserialize, + response_serializer=empty_pb2.Empty.SerializeToString, + ), + }, + ) + self._server.add_generic_rpc_handlers((handler,)) + self.port = self._server.add_insecure_port("127.0.0.1:0") + + def _create_service_time_series(self, request, context): + self.requests.append(request) + self.metadata.append(dict(context.invocation_metadata())) + return empty_pb2.Empty() + + def start(self): + self._server.start() + return self + + def stop(self): + self._server.stop(grace=0) + + def __enter__(self): + return self.start() + + def __exit__(self, *args): + self.stop() + + +def _collect_sample_metrics(project_id): + reader = InMemoryMetricReader() + provider = MeterProvider(metric_readers=[reader]) + meter = provider.get_meter(BUILT_IN_METRICS_METER_NAME) + counter = meter.create_counter( + name=METRIC_NAME_OPERATION_COUNT, + description="Test operation count", + unit="1", + ) + counter.add( + 1, + attributes={ + "project_id": project_id, + "instance_id": "test-instance", + "instance_config": "regional-us-central1", + "location": "us-central1", + "client_hash": "000001", + "client_uid": "test-uid", + "client_name": "spanner-python/test", + "database": "test-db", + "method": "Spanner.ExecuteStreamingSql", + "status": "OK", + }, + ) + return reader.get_metrics_data() + + +class TestMetricsExporterEndpointIntegration(MockServerTestBase): + def setUp(self): + super().setUp() + self._orig_disable = os.environ.get("SPANNER_DISABLE_BUILTIN_METRICS") + os.environ["SPANNER_DISABLE_BUILTIN_METRICS"] = "false" + SpannerMetricsTracerFactory._metrics_tracer_factory = None + client_mod._metrics_monitor_initialized = False + + def tearDown(self): + super().tearDown() + if self._orig_disable is None: + os.environ.pop("SPANNER_DISABLE_BUILTIN_METRICS", None) + else: + os.environ["SPANNER_DISABLE_BUILTIN_METRICS"] = self._orig_disable + metrics.set_meter_provider(metrics.NoOpMeterProvider()) + SpannerMetricsTracerFactory._metrics_tracer_factory = None + client_mod._metrics_monitor_initialized = False + + def test_exporter_sends_rpc_to_configured_endpoint_with_matching_universe(self): + """End-to-end gRPC export hits the configured Monitoring server and sends user-agent.""" + creds = _FakeUniverseCredentials( + universe_domain="custom-universe.test", + project_id="test-project", + ) + with _MockMonitoringServer() as server: + endpoint = f"127.0.0.1:{server.port}" + with ( + mock.patch.dict( + os.environ, + { + "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false", + "GOOGLE_API_USE_MTLS_ENDPOINT": "never", + }, + ), + mock.patch( + "google.cloud.spanner_v1.metrics.metrics_exporter." + "MetricServiceGrpcTransport.create_channel", + side_effect=lambda host, **kw: grpc.insecure_channel( + host, options=kw.get("options") + ), + ), + ): + exporter = CloudMonitoringMetricsExporter( + project_id="test-project", + credentials=creds, + client_options=ClientOptions( + api_endpoint=endpoint, + universe_domain="custom-universe.test", + ), + ) + try: + metrics_data = _collect_sample_metrics("test-project") + self.assertTrue(exporter.export(metrics_data)) + finally: + exporter.shutdown() + + self.assertEqual(len(server.requests), 1) + self.assertEqual(server.requests[0].name, "projects/test-project") + self.assertEqual(len(server.requests[0].time_series), 1) + self.assertEqual( + server.requests[0].time_series[0].metric.type, + f"{NATIVE_METRICS_PREFIX}/{METRIC_NAME_OPERATION_COUNT}", + ) + self.assertIn( + "python-spanner; google-cloud-service-metric-exporter", + server.metadata[0].get("user-agent", ""), + ) + + def test_client_env_universe_domain_propagates_to_monitoring_channel(self): + """Client respects GOOGLE_CLOUD_UNIVERSE_DOMAIN end-to-end for Monitoring.""" + creds = _FakeUniverseCredentials( + universe_domain="env-universe.test", + project_id="env-project", + ) + captured = {} + + def _capture_channel(host, **kwargs): + captured["host"] = host + captured["credentials"] = kwargs.get("credentials") + return mock.MagicMock() + + env_override = { + "SPANNER_DISABLE_BUILTIN_METRICS": "false", + "GOOGLE_CLOUD_UNIVERSE_DOMAIN": "env-universe.test", + "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false", + "GOOGLE_API_USE_MTLS_ENDPOINT": "never", + } + with ( + mock.patch.dict(os.environ, env_override), + mock.patch( + "google.cloud.spanner_v1.client._get_spanner_emulator_host", + return_value=None, + ), + mock.patch( + "google.cloud.spanner_v1.client.PeriodicExportingMetricReader" + ) as mock_reader, + mock.patch( + "google.cloud.spanner_v1.metrics.metrics_exporter." + "MetricServiceGrpcTransport.create_channel", + side_effect=_capture_channel, + ), + ): + os.environ.pop("GOOGLE_CLOUD_PROJECT", None) + os.environ.pop("GCLOUD_PROJECT", None) + Client(project=None, credentials=creds) + + self.assertEqual(captured["host"], "monitoring.env-universe.test:443") + self.assertEqual( + captured["credentials"].scopes, + ("https://www.googleapis.com/auth/monitoring.write",), + ) + exporter = mock_reader.call_args[0][0] + self.assertEqual(exporter.project_id, "env-project") + self.assertEqual(exporter.project_name, "projects/env-project") + + def test_client_custom_api_endpoint_never_opens_monitoring_channel(self): + """Client with a custom api_endpoint does not initialize CloudMonitoringMetricsExporter.""" + creds = _FakeUniverseCredentials(project_id="test-project") + with ( + mock.patch( + "google.cloud.spanner_v1.client._get_spanner_emulator_host", + return_value=None, + ), + mock.patch( + "google.cloud.spanner_v1.metrics.metrics_exporter." + "MetricServiceGrpcTransport.create_channel" + ) as mock_create_channel, + ): + Client( + project="test-project", + credentials=creds, + client_options=ClientOptions( + api_endpoint=f"localhost:{MockServerTestBase.port}", + ), + ) + + mock_create_channel.assert_not_called() + self.assertIsInstance(metrics.get_meter_provider(), metrics.NoOpMeterProvider) + + def test_client_universe_domain_propagates_to_monitoring_channel_and_project(self): + """Client with project=None and custom universe_domain routes Monitoring to that universe.""" + creds = _FakeUniverseCredentials( + universe_domain="custom-universe.test", + project_id="creds-project", + ) + captured = {} + + def _capture_channel(host, **kwargs): + captured["host"] = host + captured["credentials"] = kwargs.get("credentials") + return mock.MagicMock() + + env_override = { + "SPANNER_DISABLE_BUILTIN_METRICS": "false", + "GOOGLE_API_USE_CLIENT_CERTIFICATE": "false", + "GOOGLE_API_USE_MTLS_ENDPOINT": "never", + } + with ( + mock.patch.dict(os.environ, env_override), + mock.patch( + "google.cloud.spanner_v1.client._get_spanner_emulator_host", + return_value=None, + ), + mock.patch( + "google.cloud.spanner_v1.client.PeriodicExportingMetricReader" + ) as mock_reader, + mock.patch( + "google.cloud.spanner_v1.metrics.metrics_exporter." + "MetricServiceGrpcTransport.create_channel", + side_effect=_capture_channel, + ), + ): + os.environ.pop("GOOGLE_CLOUD_PROJECT", None) + os.environ.pop("GCLOUD_PROJECT", None) + Client( + project=None, + credentials=creds, + client_options=ClientOptions(universe_domain="custom-universe.test"), + ) + + self.assertEqual(captured["host"], "monitoring.custom-universe.test:443") + self.assertEqual( + captured["credentials"].scopes, + ("https://www.googleapis.com/auth/monitoring.write",), + ) + exporter = mock_reader.call_args[0][0] + self.assertEqual(exporter.project_id, "creds-project") + self.assertEqual(exporter.project_name, "projects/creds-project") From b0c9b66cc0f8614629d342bfb2cc3cd253bb43a8 Mon Sep 17 00:00:00 2001 From: Sakthivel Subramanian Date: Sat, 21 Nov 2026 21:28:44 +0000 Subject: [PATCH 4/4] Addressed comments --- .../google/cloud/spanner_v1/_async/client.py | 9 ++++++--- .../google/cloud/spanner_v1/client.py | 9 ++++++--- 2 files changed, 12 insertions(+), 6 deletions(-) diff --git a/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py b/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py index aa5809d2db24..2c732b75aebb 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py @@ -157,7 +157,7 @@ def _initialize_metrics(project, credentials, emulator_host=None, client_options ) # Skip metrics export when a custom Spanner api_endpoint is set. has_custom_endpoint = bool( - client_options and client_options.api_endpoint + getattr(client_options, "api_endpoint", None) ) if ( not _get_spanner_emulator_host() @@ -166,11 +166,14 @@ def _initialize_metrics(project, credentials, emulator_host=None, client_options and not has_custom_endpoint ): # Only forward universe_domain to Cloud Monitoring. + universe_domain = getattr( + client_options, "universe_domain", None + ) monitoring_options = ( google.api_core.client_options.ClientOptions( - universe_domain=client_options.universe_domain + universe_domain=universe_domain ) - if client_options and client_options.universe_domain + if universe_domain else None ) meter_provider = MeterProvider( diff --git a/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py b/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py index 8806221e9f3c..8a768e21fdb2 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py @@ -135,7 +135,7 @@ def _initialize_metrics(project, credentials, emulator_host=None, client_options client_options ) has_custom_endpoint = bool( - client_options and client_options.api_endpoint + getattr(client_options, "api_endpoint", None) ) if ( not _get_spanner_emulator_host() @@ -143,11 +143,14 @@ def _initialize_metrics(project, credentials, emulator_host=None, client_options and (not isinstance(credentials, AnonymousCredentials)) and (not has_custom_endpoint) ): + universe_domain = getattr( + client_options, "universe_domain", None + ) monitoring_options = ( google.api_core.client_options.ClientOptions( - universe_domain=client_options.universe_domain + universe_domain=universe_domain ) - if client_options and client_options.universe_domain + if universe_domain else None ) meter_provider = MeterProvider(