feat(spanner): make built-in metrics enabled by default (#1459)

Make built-in metrics enabled by default
This change inverts the logic for enabling built-in OpenTelemetry
metrics. Previously, metrics were disabled by default and could be
enabled by setting `ENABLE_SPANNER_METRICS_ENV_VAR=true`.
With this update, metrics are now enabled by default to provide better
out-of-the-box observability for users.
To disable metrics, users must now set the new environment variable:
`SPANNER_DISABLE_BUILTIN_METRICS=true`
The old `ENABLE_SPANNER_METRICS_ENV_VAR` is no longer used. Unit tests
have been updated to reflect this new opt-out behavior.
**BREAKING CHANGE**: Built-in metrics are now enabled by default. Users
who previously did not set any environment variables will have metrics
collection and export turned on automatically after upgrading. To
restore the previous behavior and disable metrics, thry have to set the
`SPANNER_DISABLE_BUILTIN_METRICS` environment variable to `true`.

Author: sinhasubham

google/cloud/spanner_v1/client.py

@@ -52,7 +52,6 @@
 fromgoogle.cloud.spanner_v1._helpersimport_metadata_with_prefix
 fromgoogle.cloud.spanner_v1.instanceimportInstance
 fromgoogle.cloud.spanner_v1.metrics.constantsimport (
-ENABLE_SPANNER_METRICS_ENV_VAR,
 METRIC_EXPORT_INTERVAL_MS,
 )
 fromgoogle.cloud.spanner_v1.metrics.spanner_metrics_tracer_factoryimport (
@@ -75,7 +74,7 @@
 
 _CLIENT_INFO=client_info.ClientInfo(client_library_version=__version__)
 EMULATOR_ENV_VAR="SPANNER_EMULATOR_HOST"
-ENABLE_BUILTIN_METRICS_ENV_VAR="SPANNER_ENABLE_BUILTIN_METRICS"
+SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR="SPANNER_DISABLE_BUILTIN_METRICS"
 _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 "
@@ -102,7 +101,7 @@ def _get_spanner_optimizer_statistics_package():
 
 
 def_get_spanner_enable_builtin_metrics():
-returnos.getenv(ENABLE_SPANNER_METRICS_ENV_VAR) =="true"
+returnos.getenv(SPANNER_DISABLE_BUILTIN_METRICS_ENV_VAR) !="true"
 
 
 classClient(ClientWithProject):

google/cloud/spanner_v1/metrics/constants.py

@@ -20,7 +20,6 @@
 GOOGLE_CLOUD_REGION_KEY="cloud.region"
 GOOGLE_CLOUD_REGION_GLOBAL="global"
 SPANNER_METHOD_PREFIX="/google.spanner.v1."
-ENABLE_SPANNER_METRICS_ENV_VAR="SPANNER_ENABLE_BUILTIN_METRICS"
 
 # Monitored resource labels
 MONITORED_RES_LABEL_KEY_PROJECT="project_id"

tests/system/test_metrics.py

@@ -0,0 +1,92 @@
+# Copyright 2025 Google LLC
+#
+# 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.
+
+importos
+importmock
+importpytest
+
+fromopentelemetry.sdk.metricsimportMeterProvider
+fromopentelemetry.sdk.metrics.exportimportInMemoryMetricReader
+
+fromgoogle.cloud.spanner_v1importClient
+
+# System tests are skipped if the environment variables are not set.
+PROJECT=os.environ.get("GOOGLE_CLOUD_PROJECT")
+INSTANCE_ID=os.environ.get("SPANNER_TEST_INSTANCE")
+DATABASE_ID="test_metrics_db_system"
+
+
+pytestmark=pytest.mark.skipif(
+notall([PROJECT, INSTANCE_ID]), reason="System test environment variables not set."
+)
+
+
+@pytest.fixture(scope="module")
+defmetrics_database():
+"""Create a database for the test."""
+client=Client(project=PROJECT)
+instance=client.instance(INSTANCE_ID)
+database=instance.database(DATABASE_ID)
+ifdatabase.exists(): # Clean up from previous failed run
+database.drop()
+op=database.create()
+op.result(timeout=300) # Wait for creation to complete
+yielddatabase
+ifdatabase.exists():
+database.drop()
+
+
+deftest_builtin_metrics_with_default_otel(metrics_database):
+"""
+ Verifies that built-in metrics are collected by default when a
+ transaction is executed.
+ """
+reader=InMemoryMetricReader()
+meter_provider=MeterProvider(metric_readers=[reader])
+
+# Patch the client's metric setup to use our in-memory reader.
+withmock.patch(
+"google.cloud.spanner_v1.client.MeterProvider",
+return_value=meter_provider,
+ ):
+withmock.patch.dict(os.environ, {"SPANNER_DISABLE_BUILTIN_METRICS": "false"}):
+withmetrics_database.snapshot() assnapshot:
+list(snapshot.execute_sql("SELECT 1"))
+
+metric_data=reader.get_metrics_data()
+
+assertlen(metric_data.resource_metrics) >=1
+assertlen(metric_data.resource_metrics[0].scope_metrics) >=1
+
+collected_metrics= {
+metric.name
+formetricinmetric_data.resource_metrics[0].scope_metrics[0].metrics
+ }
+expected_metrics= {
+"spanner/operation_latencies",
+"spanner/attempt_latencies",
+"spanner/operation_count",
+"spanner/attempt_count",
+"spanner/gfe_latencies",
+ }
+assertexpected_metrics.issubset(collected_metrics)
+
+formetricinmetric_data.resource_metrics[0].scope_metrics[0].metrics:
+ifmetric.name=="spanner/operation_count":
+point=next(iter(metric.data.data_points))
+assertpoint.value==1
+assertpoint.attributes["method"] =="ExecuteSql"
+return
+
+pytest.fail("Metric 'spanner/operation_count' not found.")

tests/unit/test_client.py

@@ -22,6 +22,7 @@
 fromtests._buildersimportbuild_scoped_credentials
 
 
+@mock.patch.dict(os.environ, {"SPANNER_DISABLE_BUILTIN_METRICS": "true"})
 classTestClient(unittest.TestCase):
 PROJECT="PROJECT"
 PATH="projects/%s"% (PROJECT,)
@@ -161,8 +162,7 @@ def test_constructor_custom_client_info(self):
 creds=build_scoped_credentials()
 self._constructor_test_helper(expected_scopes, creds, client_info=client_info)
 
-# Disable metrics to avoid google.auth.default calls from Metric Exporter
-@mock.patch.dict(os.environ, {"SPANNER_ENABLE_BUILTIN_METRICS": ""})
+# Metrics are disabled by default for tests in this class
 deftest_constructor_implicit_credentials(self):
 fromgoogle.cloud.spanner_v1importclientasMUT
 
@@ -255,8 +255,8 @@ def test_constructor_w_directed_read_options(self):
 expected_scopes, creds, directed_read_options=self.DIRECTED_READ_OPTIONS
  )
 
-@mock.patch.dict(os.environ, {"SPANNER_ENABLE_BUILTIN_METRICS": "true"})
 @mock.patch("google.cloud.spanner_v1.client.SpannerMetricsTracerFactory")
+@mock.patch.dict(os.environ, {"SPANNER_DISABLE_BUILTIN_METRICS": "false"})
 deftest_constructor_w_metrics_initialization_error(
 self, mock_spanner_metrics_factory
  ):