feat(spanner): log client configuration at startup (#17040)

This is an already reviewed change as part of [this
PR](googleapis/python-spanner#1461) in old repo.
This change introduces logging for Spanner client options upon
initialization.
This allows customers to easily capture and inspect the configuration
being used, which is valuable for debugging and verification.
This feature mirrors the existing logSpannerOptions functionality in the
Java client, improving consistency across client libraries.
googleapis/java-spanner#4141

Author: sinhasubham

packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py

@@ -101,6 +101,7 @@
 
 EMULATOR_ENV_VAR="SPANNER_EMULATOR_HOST"
 SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR="SPANNER_DISABLE_BUILTIN_METRICS"
+LOG_CLIENT_OPTIONS_ENV_VAR="GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS"
 _EMULATOR_HOST_HTTP_SCHEME= (
 "%s contains a http scheme. When used with a scheme it may cause gRPC's "
 "DNS resolver to endlessly attempt to resolve. %s is intended to be used "
@@ -133,6 +134,10 @@ def _get_spanner_enable_builtin_metrics_env():
 returnos.getenv(SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR) !="true"
 
 
+def_get_spanner_log_client_options_env():
+returnos.getenv(LOG_CLIENT_OPTIONS_ENV_VAR, "false").lower() =="true"
+
+
 def_initialize_metrics(project, credentials):
 """
  Initializes the Spanner built-in metrics.
@@ -364,6 +369,37 @@ def __init__(
 self._nth_client_id=Client.NTH_CLIENT.increment()
 self._nth_request=AtomicCounter(0)
 
+self._host="spanner.googleapis.com"
+ifself._emulator_host:
+self._host=self._emulator_host
+elifself._experimental_host:
+self._host=self._experimental_host
+elifself._client_optionsandself._client_options.api_endpoint:
+self._host=self._client_options.api_endpoint
+
+if_get_spanner_log_client_options_env():
+self._log_spanner_options()
+
+def_log_spanner_options(self):
+"""Logs Spanner client options."""
+log.info(
+"Spanner options: \n"
+" Project ID: %s\n"
+" Host: %s\n"
+" Route to leader enabled: %s\n"
+" Directed read options: %s\n"
+" Default transaction options: %s\n"
+" Observability options: %s\n"
+" Built-in metrics enabled: %s",
+self.project,
+self._host,
+self.route_to_leader_enabled,
+self._directed_read_options,
+self._default_transaction_options,
+self._observability_options,
+_get_spanner_enable_builtin_metrics_env(),
+ )
+
 @property
 def_next_nth_request(self):
 returnself._nth_request.increment()

packages/google-cloud-spanner/google/cloud/spanner_v1/client.py

@@ -32,13 +32,11 @@
 importthreading
 importwarnings
 fromtypingimportOptional
-
 importgoogle.api_core.client_options
 importgrpc
 fromgoogle.api_core.gapic_v1importclient_info
 fromgoogle.auth.credentialsimportAnonymousCredentials
 fromgoogle.cloud.clientimportClientWithProject
-
 fromgoogle.cloud.spanner_admin_database_v1import (
 DatabaseAdminClientasDatabaseAdminClient,
 )
@@ -55,14 +53,14 @@
 fromgoogle.cloud.spanner_admin_instance_v1.services.instance_admin.transports.grpcimport (
 InstanceAdminGrpcTransport,
 )
+fromgoogle.cloud.spanner_v1.instanceimportInstance
 fromgoogle.cloud.spanner_v1._helpersimport (
 AtomicCounter,
 _merge_query_options,
 _metadata_with_prefix,
 _validate_client_context,
 )
 fromgoogle.cloud.spanner_v1.gapic_versionimport__version__
-fromgoogle.cloud.spanner_v1.instanceimportInstance
 fromgoogle.cloud.spanner_v1.metrics.constantsimportMETRIC_EXPORT_INTERVAL_MS
 fromgoogle.cloud.spanner_v1.metrics.metrics_exporterimport (
 CloudMonitoringMetricsExporter,
@@ -84,6 +82,7 @@
 _CLIENT_INFO=client_info.ClientInfo(client_library_version=__version__)
 EMULATOR_ENV_VAR="SPANNER_EMULATOR_HOST"
 SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR="SPANNER_DISABLE_BUILTIN_METRICS"
+LOG_CLIENT_OPTIONS_ENV_VAR="GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS"
 _EMULATOR_HOST_HTTP_SCHEME= (
 "%s contains a http scheme. When used with a scheme it may cause gRPC's DNS resolver to endlessly attempt to resolve. %s is intended to be used without a scheme: ex %s=localhost:8080."
 % ((EMULATOR_ENV_VAR,) *3)
@@ -114,6 +113,10 @@ def _get_spanner_enable_builtin_metrics_env():
 returnos.getenv(SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR) !="true"
 
 
+def_get_spanner_log_client_options_env():
+returnos.getenv(LOG_CLIENT_OPTIONS_ENV_VAR, "false").lower() =="true"
+
+
 def_initialize_metrics(project, credentials):
 """Initializes the Spanner built-in metrics.
 
@@ -226,8 +229,7 @@ class Client(ClientWithProject):
  the Spanner built-in metrics collection and exporting.
 
  :raises: :class:`ValueError <exceptions.ValueError>` if both ``read_only``
- and ``admin`` are :data:`True`
- """
+ and ``admin`` are :data:`True`"""
 
 _instance_admin_api=None
 _database_admin_api=None
@@ -316,6 +318,28 @@ def __init__(
 self._default_transaction_options=default_transaction_options
 self._nth_client_id=Client.NTH_CLIENT.increment()
 self._nth_request=AtomicCounter(0)
+self._host="spanner.googleapis.com"
+ifself._emulator_host:
+self._host=self._emulator_host
+elifself._experimental_host:
+self._host=self._experimental_host
+elifself._client_optionsandself._client_options.api_endpoint:
+self._host=self._client_options.api_endpoint
+if_get_spanner_log_client_options_env():
+self._log_spanner_options()
+
+def_log_spanner_options(self):
+"""Logs Spanner client options."""
+log.info(
+"Spanner options: \n Project ID: %s\n Host: %s\n Route to leader enabled: %s\n Directed read options: %s\n Default transaction options: %s\n Observability options: %s\n Built-in metrics enabled: %s",
+self.project,
+self._host,
+self.route_to_leader_enabled,
+self._directed_read_options,
+self._default_transaction_options,
+self._observability_options,
+_get_spanner_enable_builtin_metrics_env(),
+ )
 
 @property
 def_next_nth_request(self):

packages/google-cloud-spanner/tests/unit/_async/test_client.py

@@ -778,3 +778,113 @@ async def __anext__(self):
 self.assertEqual(li_api.call_count, 1)
 args, kwargs=li_api.call_args
 self.assertEqual(kwargs["metadata"], expected_metadata)
+
+@mock.patch.dict(
+os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "false"}
+ )
+@CrossSync.pytest
+asyncdeftest_constructor_logs_options_disabled_by_default(self):
+fromgoogle.cloud.spanner_v1._asyncimportclientasMUT
+
+logger=MUT.log
+creds=build_scoped_credentials()
+
+withmock.patch.object(logger, "info") asinfo_logger:
+client=self._make_one(
+project=self.PROJECT,
+credentials=creds,
+ )
+self.assertIsNotNone(client)
+# Assert that no logs are emitted when the environment variable is explicitly false
+info_logger.assert_not_called()
+
+# Also test when the environment variable is not set at all
+withmock.patch.dict(os.environ, {}, clear=True):
+withmock.patch.object(logger, "info") asinfo_logger:
+client=self._make_one(project=self.PROJECT, credentials=creds)
+self.assertIsNotNone(client)
+# Assert that no logs are emitted when the environment variable is not set
+info_logger.assert_not_called()
+
+@CrossSync.pytest
+asyncdeftest_constructor_logs_options(self):
+fromgoogle.cloud.spanner_v1._asyncimportclientasMUT
+
+creds=build_scoped_credentials()
+observability_options= {"enable_extended_tracing": True}
+withself.assertLogs(MUT.__name__, level="INFO") ascm:
+withmock.patch.dict(
+os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true"}
+ ):
+client=self._make_one(
+project=self.PROJECT,
+credentials=creds,
+route_to_leader_enabled=False,
+directed_read_options=self.DIRECTED_READ_OPTIONS,
+default_transaction_options=self.DEFAULT_TRANSACTION_OPTIONS,
+observability_options=observability_options,
+ )
+self.assertIsNotNone(client)
+
+# Assert that logs are emitted when the environment variable is true
+# and verify their content.
+self.assertEqual(len(cm.output), 1)
+log_output=cm.output[0]
+self.assertIn("Spanner options:", log_output)
+self.assertIn(f"\n Project ID: {self.PROJECT}", log_output)
+self.assertIn("\n Host: spanner.googleapis.com", log_output)
+self.assertIn("\n Route to leader enabled: False", log_output)
+self.assertIn(
+f"\n Directed read options: {self.DIRECTED_READ_OPTIONS}", log_output
+ )
+self.assertIn(
+f"\n Default transaction options: {self.DEFAULT_TRANSACTION_OPTIONS}",
+log_output,
+ )
+self.assertIn(f"\n Observability options: {observability_options}", log_output)
+# SPANNER_DISABLE_BUILTIN_METRICS is "true" from class-level patch
+self.assertIn("\n Built-in metrics enabled: False", log_output)
+# Test with custom host
+endpoint="test.googleapis.com"
+withself.assertLogs(MUT.__name__, level="INFO") ascm:
+withmock.patch.dict(
+os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true"}
+ ):
+self._make_one(
+project=self.PROJECT,
+credentials=creds,
+client_options={"api_endpoint": endpoint},
+ )
+self.assertEqual(len(cm.output), 1)
+log_output=cm.output[0]
+self.assertIn(f"\n Host: {endpoint}", log_output)
+
+# Test with emulator host
+emulator_host="localhost:9010"
+withmock.patch.dict(
+os.environ,
+ {
+MUT.EMULATOR_ENV_VAR: emulator_host,
+"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true",
+ },
+ ):
+withself.assertLogs(MUT.__name__, level="INFO") ascm:
+self._make_one(project=self.PROJECT, credentials=creds)
+self.assertEqual(len(cm.output), 1)
+log_output=cm.output[0]
+self.assertIn(f"\n Host: {emulator_host}", log_output)
+
+# Test with experimental host
+experimental_host="exp.googleapis.com"
+withmock.patch.dict(
+os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true"}
+ ):
+withself.assertLogs(MUT.__name__, level="INFO") ascm:
+self._make_one(
+project=self.PROJECT,
+credentials=creds,
+experimental_host=experimental_host,
+ )
+self.assertEqual(len(cm.output), 1)
+log_output=cm.output[0]
+self.assertIn(f"\n Host: {experimental_host}", log_output)

packages/google-cloud-spanner/tests/unit/test_client.py

@@ -836,3 +836,111 @@ def test_list_instances_w_options(self):
 retry=mock.ANY,
 timeout=mock.ANY,
  )
+
+@mock.patch.dict(
+os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "false"}
+ )
+deftest_constructor_logs_options_disabled_by_default(self):
+fromgoogle.cloud.spanner_v1importclientasMUT
+
+logger=MUT.log
+creds=build_scoped_credentials()
+
+withmock.patch.object(logger, "info") asinfo_logger:
+client=self._make_one(
+project=self.PROJECT,
+credentials=creds,
+ )
+self.assertIsNotNone(client)
+# Assert that no logs are emitted when the environment variable is explicitly false
+info_logger.assert_not_called()
+
+# Also test when the environment variable is not set at all
+withmock.patch.dict(os.environ, {}, clear=True):
+withmock.patch.object(logger, "info") asinfo_logger:
+client=self._make_one(project=self.PROJECT, credentials=creds)
+self.assertIsNotNone(client)
+# Assert that no logs are emitted when the environment variable is not set
+info_logger.assert_not_called()
+
+deftest_constructor_logs_options(self):
+fromgoogle.cloud.spanner_v1importclientasMUT
+
+creds=build_scoped_credentials()
+observability_options= {"enable_extended_tracing": True}
+withself.assertLogs(MUT.__name__, level="INFO") ascm:
+withmock.patch.dict(
+os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true"}
+ ):
+client=self._make_one(
+project=self.PROJECT,
+credentials=creds,
+route_to_leader_enabled=False,
+directed_read_options=self.DIRECTED_READ_OPTIONS,
+default_transaction_options=self.DEFAULT_TRANSACTION_OPTIONS,
+observability_options=observability_options,
+ )
+self.assertIsNotNone(client)
+
+# Assert that logs are emitted when the environment variable is true
+# and verify their content.
+self.assertEqual(len(cm.output), 1)
+log_output=cm.output[0]
+self.assertIn("Spanner options:", log_output)
+self.assertIn(f"\n Project ID: {self.PROJECT}", log_output)
+self.assertIn("\n Host: spanner.googleapis.com", log_output)
+self.assertIn("\n Route to leader enabled: False", log_output)
+self.assertIn(
+f"\n Directed read options: {self.DIRECTED_READ_OPTIONS}", log_output
+ )
+self.assertIn(
+f"\n Default transaction options: {self.DEFAULT_TRANSACTION_OPTIONS}",
+log_output,
+ )
+self.assertIn(f"\n Observability options: {observability_options}", log_output)
+# SPANNER_DISABLE_BUILTIN_METRICS is "true" from class-level patch
+self.assertIn("\n Built-in metrics enabled: False", log_output)
+# Test with custom host
+endpoint="test.googleapis.com"
+withself.assertLogs(MUT.__name__, level="INFO") ascm:
+withmock.patch.dict(
+os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true"}
+ ):
+self._make_one(
+project=self.PROJECT,
+credentials=creds,
+client_options={"api_endpoint": endpoint},
+ )
+self.assertEqual(len(cm.output), 1)
+log_output=cm.output[0]
+self.assertIn(f"\n Host: {endpoint}", log_output)
+
+# Test with emulator host
+emulator_host="localhost:9010"
+withmock.patch.dict(
+os.environ,
+ {
+MUT.EMULATOR_ENV_VAR: emulator_host,
+"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true",
+ },
+ ):
+withself.assertLogs(MUT.__name__, level="INFO") ascm:
+self._make_one(project=self.PROJECT, credentials=creds)
+self.assertEqual(len(cm.output), 1)
+log_output=cm.output[0]
+self.assertIn(f"\n Host: {emulator_host}", log_output)
+
+# Test with experimental host
+experimental_host="exp.googleapis.com"
+withmock.patch.dict(
+os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true"}
+ ):
+withself.assertLogs(MUT.__name__, level="INFO") ascm:
+self._make_one(
+project=self.PROJECT,
+credentials=creds,
+experimental_host=experimental_host,
+ )
+self.assertEqual(len(cm.output), 1)
+log_output=cm.output[0]
+self.assertIn(f"\n Host: {experimental_host}", log_output)