Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
sinhasubham wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
36 changes: 36 additions & 0 deletions packages/google-cloud-spanner/google/cloud/spanner_v1/_async/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 "
Expand Down Expand Up @@ -133,6 +134,10 @@ def _get_spanner_enable_builtin_metrics_env():
return os.getenv(SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR) != "true"


def _get_spanner_log_client_options_env():
return os.getenv(LOG_CLIENT_OPTIONS_ENV_VAR, "false").lower() == "true"


def _initialize_metrics(project, credentials):
"""
Initializes the Spanner built-in metrics.
Expand Down Expand Up @@ -364,6 +369,37 @@ def __init__(
self._nth_client_id = Client.NTH_CLIENT.increment()
self._nth_request = AtomicCounter(0)

self.host = "spanner.googleapis.com"
if self._emulator_host:
self.host = self._emulator_host
elif self._experimental_host:
self.host = self._experimental_host
elif self._client_options and self._client_options.api_endpoint:
self.host = self._client_options.api_endpoint
Comment on lines +372 to +378
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The attribute host is quite generic and might conflict with future changes in base classes or subclasses. Since it is primarily used for logging client options here, it should be prefixed with an underscore to indicate it is internal.

Suggested change
self.host = "spanner.googleapis.com"
if self._emulator_host:
self.host = self._emulator_host
elif self._experimental_host:
self.host = self._experimental_host
elif self._client_options and self._client_options.api_endpoint:
self.host = self._client_options.api_endpoint
self._host = "spanner.googleapis.com"
if self._emulator_host:
self._host = self._emulator_host
elif self._experimental_host:
self._host = self._experimental_host
elif self._client_options and self._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,
Comment on lines +395 to +399
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

Prefer using public properties instead of private attributes (e.g., directed_read_options instead of _directed_read_options) where available for logging.

Suggested change
self.host,
self.route_to_leader_enabled,
self._directed_read_options,
self._default_transaction_options,
self._observability_options,
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):
return self._nth_request.increment()
Expand Down
34 changes: 29 additions & 5 deletions packages/google-cloud-spanner/google/cloud/spanner_v1/client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,11 @@
import threading
import warnings
from typing import Optional

import google.api_core.client_options
import grpc
from google.api_core.gapic_v1 import client_info
from google.auth.credentials import AnonymousCredentials
from google.cloud.client import ClientWithProject

from google.cloud.spanner_admin_database_v1 import (
DatabaseAdminClient as DatabaseAdminClient,
)
Expand All @@ -55,14 +53,14 @@
from google.cloud.spanner_admin_instance_v1.services.instance_admin.transports.grpc import (
InstanceAdminGrpcTransport,
)
from google.cloud.spanner_v1.instance import Instance
from google.cloud.spanner_v1._helpers import (
AtomicCounter,
_merge_query_options,
_metadata_with_prefix,
_validate_client_context,
)
from google.cloud.spanner_v1.gapic_version import __version__
from google.cloud.spanner_v1.instance import Instance
from google.cloud.spanner_v1.metrics.constants import METRIC_EXPORT_INTERVAL_MS
from google.cloud.spanner_v1.metrics.metrics_exporter import (
CloudMonitoringMetricsExporter,
Expand All @@ -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)
Expand Down Expand Up @@ -114,6 +113,10 @@ def _get_spanner_enable_builtin_metrics_env():
return os.getenv(SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR) != "true"


def _get_spanner_log_client_options_env():
return os.getenv(LOG_CLIENT_OPTIONS_ENV_VAR, "false").lower() == "true"


def _initialize_metrics(project, credentials):
"""Initializes the Spanner built-in metrics.

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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"
if self._emulator_host:
self.host = self._emulator_host
elif self._experimental_host:
self.host = self._experimental_host
elif self._client_options and self._client_options.api_endpoint:
self.host = self._client_options.api_endpoint
Comment on lines +321 to +327
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

The attribute host is quite generic and might conflict with future changes in base classes or subclasses. Since it is primarily used for logging client options here, it should be prefixed with an underscore to indicate it is internal.

Suggested change
self.host = "spanner.googleapis.com"
if self._emulator_host:
self.host = self._emulator_host
elif self._experimental_host:
self.host = self._experimental_host
elif self._client_options and self._client_options.api_endpoint:
self.host = self._client_options.api_endpoint
self._host = "spanner.googleapis.com"
if self._emulator_host:
self._host = self._emulator_host
elif self._experimental_host:
self._host = self._experimental_host
elif self._client_options and self._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(),
)
Comment on lines +334 to +342
Copy link
Copy Markdown
Contributor

@gemini-code-assist gemini-code-assist Bot May 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

medium

For better readability and consistency with the asynchronous client implementation, consider breaking the log format string into multiple lines. Additionally, prefer using public properties instead of private attributes (e.g., directed_read_options instead of _directed_read_options) where available.

        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):
Expand Down
110 changes: 110 additions & 0 deletions packages/google-cloud-spanner/tests/unit/_async/test_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
async def test_constructor_logs_options_disabled_by_default(self):
from google.cloud.spanner_v1._async import client as MUT

logger = MUT.log
creds = build_scoped_credentials()

with mock.patch.object(logger, "info") as info_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
with mock.patch.dict(os.environ, {}, clear=True):
with mock.patch.object(logger, "info") as info_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
async def test_constructor_logs_options(self):
from google.cloud.spanner_v1._async import client as MUT

creds = build_scoped_credentials()
observability_options = {"enable_extended_tracing": True}
with self.assertLogs(MUT.__name__, level="INFO") as cm:
with mock.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"
with self.assertLogs(MUT.__name__, level="INFO") as cm:
with mock.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"
with mock.patch.dict(
os.environ,
{
MUT.EMULATOR_ENV_VAR: emulator_host,
"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true",
},
):
with self.assertLogs(MUT.__name__, level="INFO") as cm:
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"
with mock.patch.dict(
os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true"}
):
with self.assertLogs(MUT.__name__, level="INFO") as cm:
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)
108 changes: 108 additions & 0 deletions packages/google-cloud-spanner/tests/unit/test_client.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"}
)
def test_constructor_logs_options_disabled_by_default(self):
from google.cloud.spanner_v1 import client as MUT

logger = MUT.log
creds = build_scoped_credentials()

with mock.patch.object(logger, "info") as info_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
with mock.patch.dict(os.environ, {}, clear=True):
with mock.patch.object(logger, "info") as info_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()

def test_constructor_logs_options(self):
from google.cloud.spanner_v1 import client as MUT

creds = build_scoped_credentials()
observability_options = {"enable_extended_tracing": True}
with self.assertLogs(MUT.__name__, level="INFO") as cm:
with mock.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"
with self.assertLogs(MUT.__name__, level="INFO") as cm:
with mock.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"
with mock.patch.dict(
os.environ,
{
MUT.EMULATOR_ENV_VAR: emulator_host,
"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true",
},
):
with self.assertLogs(MUT.__name__, level="INFO") as cm:
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"
with mock.patch.dict(
os.environ, {"GOOGLE_CLOUD_SPANNER_ENABLE_LOG_CLIENT_OPTIONS": "true"}
):
with self.assertLogs(MUT.__name__, level="INFO") as cm:
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)
Loading