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..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 @@ -138,7 +138,7 @@ 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 _initialize_metrics(project, credentials, emulator_host=None, client_options=None): """ Initializes the Spanner built-in metrics. @@ -151,17 +151,38 @@ def _initialize_metrics(project, credentials, emulator_host=None): if not _metrics_monitor_initialized: meter_provider = metrics.NoOpMeterProvider() try: + 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( + getattr(client_options, "api_endpoint", None) + ) if ( not _get_spanner_emulator_host() and not emulator_host and not isinstance(credentials, AnonymousCredentials) + 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=universe_domain + ) + if universe_domain + else None + ) meter_provider = MeterProvider( metric_readers=[ PeriodicExportingMetricReader( CloudMonitoringMetricsExporter( project_id=project, credentials=credentials, + client_options=monitoring_options, ), export_interval_millis=METRIC_EXPORT_INTERVAL_MS, ), @@ -421,7 +442,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..8a768e21fdb2 100644 --- a/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py +++ b/packages/google-cloud-spanner/google/cloud/spanner_v1/client.py @@ -119,7 +119,7 @@ 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 _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 +130,36 @@ def _initialize_metrics(project, credentials, emulator_host=None): if not _metrics_monitor_initialized: meter_provider = metrics.NoOpMeterProvider() try: + if isinstance(client_options, dict): + client_options = google.api_core.client_options.from_dict( + client_options + ) + has_custom_endpoint = bool( + getattr(client_options, "api_endpoint", None) + ) if ( not _get_spanner_emulator_host() and (not emulator_host) 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=universe_domain + ) + if universe_domain + else None + ) meter_provider = MeterProvider( metric_readers=[ PeriodicExportingMetricReader( CloudMonitoringMetricsExporter( - project_id=project, credentials=credentials + project_id=project, + credentials=credentials, + client_options=monitoring_options, ), export_interval_millis=METRIC_EXPORT_INTERVAL_MS, ) @@ -367,7 +387,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..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 @@ -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,16 @@ ("grpc.primary_user_agent", _USER_AGENT), ] +# Scopes that authorize writing time series to Cloud Monitoring. +_MONITORING_WRITE_SCOPE = "https://www.googleapis.com/auth/monitoring.write" +_MONITORING_SCOPES = frozenset( + { + "https://www.googleapis.com/auth/cloud-platform", + "https://www.googleapis.com/auth/monitoring", + _MONITORING_WRITE_SCOPE, + } +) + # pylint is unable to resolve members of protobuf objects # pylint: disable=no-member @@ -110,6 +121,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 +135,47 @@ 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, + if client is not None: + self.client = client + else: + # 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, + client_options=client_options, + transport=lambda **kwargs: MetricServiceGrpcTransport( + **kwargs, + channel=lambda *a, **kw: MetricServiceGrpcTransport.create_channel( + *a, **{**kw, "options": _OPTIONS} + ), + ), ) - ) - # Set project information - self.project_id: str + # Avoid ambient ADC project fallback when explicit credentials are provided. if not project_id: - _, default_project_id = google.auth.default() - self.project_id = str(default_project_id) - else: - self.project_id = 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/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") 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..8d7f74905414 100644 --- a/packages/google-cloud-spanner/tests/unit/test_client.py +++ b/packages/google-cloud-spanner/tests/unit/test_client.py @@ -1165,3 +1165,160 @@ 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_universe_propagation_and_option_filtering(self): + from google.api_core.client_options import ClientOptions + + from google.cloud.spanner_v1 import client as MUT + + creds = mock.Mock() + client_options = ClientOptions( + universe_domain="my-universe.com", + quota_project_id="quota-proj", + 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.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, + )