chore(spanner): add initial setup for built-in metrics

.typos.toml

@@ -26,6 +26,8 @@ extend-exclude = [
   "src/spanner/grpc-mock/**",
   # This file contains fixes for typos and therefore has the original typo in it.
   "librarian.yaml",
+  # Contains Spanner-specific metrics abbreviations (like 'afe' for Access Front End)
+  "src/spanner/src/observability/metrics.rs",
 ]
 
 [type.mustache]

src/spanner/Cargo.toml

@@ -31,8 +31,9 @@ default = ["default-rustls-provider"]
 # TLS and authentication. Applications with specific requirements for
 # cryptography (such as exclusively using the [ring] crate) should disable this
 # default and call `rustls::CryptoProvider::install_default()`.
-default-rustls-provider = ["gaxi/_default-rustls-provider"]
-unstable-stream         = ["dep:futures"]
+default-rustls-provider      = ["gaxi/_default-rustls-provider"]
+unstable-stream              = ["dep:futures"]
+experimental-builtin-metrics = ["dep:google-cloud-monitoring-v3", "dep:opentelemetry", "dep:opentelemetry_sdk"]
 
 [dependencies]
 async-trait.workspace                  = true
@@ -60,6 +61,11 @@ tracing.workspace                      = true
 url.workspace                          = true
 wkt                                    = { workspace = true, features = ["time"] }
 
+# Optional dependencies for built-in metrics
+google-cloud-monitoring-v3 = { workspace = true, optional = true }
+opentelemetry              = { workspace = true, optional = true, features = ["metrics"] }
+opentelemetry_sdk          = { workspace = true, optional = true, features = ["metrics", "rt-tokio"] }
+
 [dev-dependencies]
 anyhow.workspace                   = true
 google-cloud-test-macros.workspace = true

src/spanner/src/batch_read_only_transaction.rs

@@ -168,6 +168,7 @@ impl BatchReadOnlyTransaction {
                 request,
                 crate::RequestOptions::default(),
                 self.inner.context.channel_hint,
+                &self.inner.context.client.o11y,
             )
             .await?;
 
@@ -232,6 +233,7 @@ impl BatchReadOnlyTransaction {
                 request,
                 crate::RequestOptions::default(),
                 self.inner.context.channel_hint,
+                &self.inner.context.client.o11y,
             )
             .await?;
 

src/spanner/src/client.rs

@@ -106,20 +106,24 @@ fn parse_emulator_endpoint(endpoint: &str) -> String {
 }
 
 macro_rules! define_idempotent_rpc {
-    ($method:ident, $request_type:ty, $response_type:ty) => {
+    ($method:ident, $request_type:ty, $response_type:ty, $canonical_name:expr) => {
         pub(crate) async fn $method(
             &self,
             request: $request_type,
             options: crate::RequestOptions,
             channel_hint: usize,
+            o11y: &crate::observability::Observability,
         ) -> crate::Result<$response_type> {
-            self.get_channel(channel_hint)
-                .inner
-                .$method()
-                .with_request(request)
-                .with_options(apply_request_defaults(options))
-                .send()
-                .await
+            o11y.trace_operation($canonical_name, || async move {
+                self.get_channel(channel_hint)
+                    .inner
+                    .$method()
+                    .with_request(request)
+                    .with_options(apply_request_defaults(options))
+                    .send()
+                    .await
+            })
+            .await
         }
     };
 }
@@ -298,18 +302,54 @@ impl Spanner {
         self.counter.fetch_add(1, Ordering::Relaxed)
     }
 
-    define_idempotent_rpc!(create_session, CreateSessionRequest, Session);
-    define_idempotent_rpc!(execute_sql, ExecuteSqlRequest, crate::model::ResultSet);
+    define_idempotent_rpc!(
+        create_session,
+        CreateSessionRequest,
+        Session,
+        "google.spanner.v1.Spanner/CreateSession"
+    );
+    define_idempotent_rpc!(
+        execute_sql,
+        ExecuteSqlRequest,
+        crate::model::ResultSet,
+        "google.spanner.v1.Spanner/ExecuteSql"
+    );
     define_idempotent_rpc!(
         execute_batch_dml,
         ExecuteBatchDmlRequest,
-        ExecuteBatchDmlResponse
+        ExecuteBatchDmlResponse,
+        "google.spanner.v1.Spanner/ExecuteBatchDml"
+    );
+    define_idempotent_rpc!(
+        begin_transaction,
+        BeginTransactionRequest,
+        Transaction,
+        "google.spanner.v1.Spanner/BeginTransaction"
+    );
+    define_idempotent_rpc!(
+        commit,
+        CommitRequest,
+        CommitResponse,
+        "google.spanner.v1.Spanner/Commit"
+    );
+    define_idempotent_rpc!(
+        rollback,
+        RollbackRequest,
+        (),
+        "google.spanner.v1.Spanner/Rollback"
+    );
+    define_idempotent_rpc!(
+        partition_query,
+        PartitionQueryRequest,
+        PartitionResponse,
+        "google.spanner.v1.Spanner/PartitionQuery"
+    );
+    define_idempotent_rpc!(
+        partition_read,
+        PartitionReadRequest,
+        PartitionResponse,
+        "google.spanner.v1.Spanner/PartitionRead"
     );
-    define_idempotent_rpc!(begin_transaction, BeginTransactionRequest, Transaction);
-    define_idempotent_rpc!(commit, CommitRequest, CommitResponse);
-    define_idempotent_rpc!(rollback, RollbackRequest, ());
-    define_idempotent_rpc!(partition_query, PartitionQueryRequest, PartitionResponse);
-    define_idempotent_rpc!(partition_read, PartitionReadRequest, PartitionResponse);
 
     /// Executes an SQL statement, returning a stream of results.
     ///
@@ -542,6 +582,7 @@ mod tests {
                 req,
                 crate::RequestOptions::default(),
                 client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
             )
             .await
             .expect("Failed to call create_session");
@@ -661,6 +702,7 @@ mod tests {
                 req,
                 crate::RequestOptions::default(),
                 client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
             )
             .await
             .expect("Failed to call create_session after transport error retry");
@@ -710,6 +752,7 @@ mod tests {
                 req,
                 crate::RequestOptions::default(),
                 client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
             )
             .await
             .expect("Failed to call execute_sql");
@@ -753,6 +796,7 @@ mod tests {
                 req,
                 crate::RequestOptions::default(),
                 client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
             )
             .await
             .expect("Failed to call execute_batch_dml");
@@ -791,6 +835,7 @@ mod tests {
                 req,
                 crate::RequestOptions::default(),
                 client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
             )
             .await
             .expect("Failed to call begin_transaction");
@@ -833,6 +878,7 @@ mod tests {
                 req,
                 crate::RequestOptions::default(),
                 client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
             )
             .await
             .expect("Failed to call commit");
@@ -866,6 +912,7 @@ mod tests {
                 req,
                 crate::RequestOptions::default(),
                 client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
             )
             .await
             .expect("Failed to call rollback");
@@ -1098,6 +1145,7 @@ mod tests {
                 req,
                 crate::RequestOptions::default(),
                 client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
             )
             .await
             .expect("Failed to call create_session");
@@ -1140,7 +1188,12 @@ mod tests {
         options.set_idempotency(false);
 
         let result = client
-            .create_session(req, options, client.next_channel_hint())
+            .create_session(
+                req,
+                options,
+                client.next_channel_hint(),
+                &crate::observability::Observability::disabled(),
+            )
             .await;
 
         // 5. Verify that it failed and did not retry

src/spanner/src/database_client.rs

@@ -15,6 +15,7 @@
 use crate::batch_read_only_transaction::BatchReadOnlyTransactionBuilder;
 use crate::batch_write_transaction::BatchWriteTransactionBuilder;
 use crate::client::Spanner;
+use crate::observability::Observability;
 use crate::partitioned_dml_transaction::PartitionedDmlTransactionBuilder;
 use crate::read_only_transaction::{
     MultiUseReadOnlyTransactionBuilder, SingleUseReadOnlyTransactionBuilder,
@@ -51,6 +52,7 @@ pub struct DatabaseClient {
     pub(crate) spanner: Spanner,
     pub(crate) session_maintainer: Arc<ManagedSessionMaintainer>,
     pub(crate) leader_aware_routing_enabled: bool,
+    pub(crate) o11y: Arc<Observability>,
 }
 
 impl DatabaseClient {
@@ -361,22 +363,35 @@ impl DatabaseClientBuilder {
     /// will be used for all operations on the database.
     pub async fn build(self) -> crate::Result<DatabaseClient> {
         let spanner_clone = self.spanner.clone();
+
+        let project_id = parse_project_id(&self.database_name);
+        let o11y = Arc::new(Observability::init(&self.spanner.config, project_id).await);
         let session_maintainer = ManagedSessionMaintainer::create_and_start_maintenance(
             self.spanner,
             self.database_name,
             self.database_role.unwrap_or_default(),
             self.options.unwrap_or_default(),
+            o11y.clone(),
         )
         .await?;
 
         Ok(DatabaseClient {
             spanner: spanner_clone,
             session_maintainer,
             leader_aware_routing_enabled: self.leader_aware_routing_enabled,
+            o11y,
         })
     }
 }
 
+fn parse_project_id(database_name: &str) -> Option<&str> {
+    let mut parts = database_name.split('/');
+    if parts.next() != Some("projects") {
+        return None;
+    }
+    parts.next()
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;

src/spanner/src/lib.rs

@@ -77,6 +77,7 @@ pub(crate) mod batch_read_only_transaction;
 pub(crate) mod batch_write_transaction;
 pub(crate) mod database_client;
 pub(crate) mod from_value;
+pub(crate) mod observability;
 pub(crate) mod partitioned_dml_transaction;
 pub(crate) mod precommit;
 pub(crate) mod read_only_transaction;

src/spanner/src/observability/exporter.rs

@@ -0,0 +1,61 @@
+// Copyright 2026 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
+//
+//     https://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.
+
+use google_cloud_monitoring_v3::client::MetricService;
+use opentelemetry_sdk::error::OTelSdkResult;
+use opentelemetry_sdk::metrics::Temporality;
+use opentelemetry_sdk::metrics::data::ResourceMetrics;
+use opentelemetry_sdk::metrics::exporter::PushMetricExporter;
+use std::sync::Arc;
+use std::time::Duration;
+
+#[derive(Clone, Debug)]
+pub(crate) struct GcpMonitoringExporter {
+    #[allow(dead_code)]
+    client: Arc<MetricService>,
+    #[allow(dead_code)]
+    project_name: String,
+}
+
+impl GcpMonitoringExporter {
+    pub(crate) fn new(client: MetricService, project_id: &str) -> Self {
+        Self {
+            client: Arc::new(client),
+            project_name: format!("projects/{}", project_id),
+        }
+    }
+}
+
+impl PushMetricExporter for GcpMonitoringExporter {
+    async fn export(&self, _metrics: &ResourceMetrics) -> OTelSdkResult {
+        // TODO: Map ResourceMetrics to CreateTimeSeriesRequest and send via self.client
+        Ok(())
+    }
+
+    fn force_flush(&self) -> OTelSdkResult {
+        Ok(())
+    }
+
+    fn shutdown(&self) -> OTelSdkResult {
+        Ok(())
+    }
+
+    fn shutdown_with_timeout(&self, _timeout: Duration) -> OTelSdkResult {
+        self.shutdown()
+    }
+
+    fn temporality(&self) -> Temporality {
+        Temporality::Cumulative
+    }
+}