feat(spanner): provide opt-in auto-tagging feature in client library

Spanner transaction and lock debugging heavily relies on transaction and request tags.
This introduces an opt-in mechanism via `enableAutoTagTransactions()` in `SpannerOptions` to automatically discover and append tags from calling runtime stack frames when explicit tags are absent. Additionally, a dedicated emergency override environment variable `SPANNER_DISABLE_AUTO_TAGGING` is provided to allow disabling auto-tagging globally.

Author: sakthivelmanii

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/AbstractReadContext.java

@@ -644,6 +644,7 @@ private void initTransactionInternal(BeginTransactionRequest request) {
   private final DirectedReadOptions defaultDirectedReadOptions;
   private final DecodeMode defaultDecodeMode;
   private final Clock clock;
+  private volatile String cachedRequestTag;
 
   @GuardedBy("lock")
   private boolean isValid = true;
@@ -831,6 +832,14 @@ QueryOptions buildQueryOptions(QueryOptions requestOptions) {
 
   RequestOptions buildRequestOptions(Options options) {
     RequestOptions.Builder builder = options.toRequestOptionsProto(false).toBuilder();
+    if (builder.getRequestTag().isEmpty()) {
+      if (this.cachedRequestTag == null) {
+        this.cachedRequestTag = AutoTagHelper.getAutoTag(session.getSpanner().getOptions());
+      }
+      if (this.cachedRequestTag != null) {
+        builder.setRequestTag(this.cachedRequestTag);
+      }
+    }
     RequestOptions.ClientContext defaultClientContext =
         session.getSpanner().getOptions().getClientContext();
     if (defaultClientContext != null) {

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/AutoTagHelper.java

@@ -0,0 +1,71 @@
+/*
+ * 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
+ *
+ *       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.
+ */
+
+package com.google.cloud.spanner;
+
+import java.util.List;
+
+class AutoTagHelper {
+
+  private static final String[] INTERNAL_PACKAGES = {
+    "java.", "javax.", "jdk.", "sun.", "io.grpc.", "com.google.cloud.spanner.", "com.google.api."
+  };
+
+  static String getAutoTag(SpannerOptions options) {
+    if (!options.isAutoTagTransactionsEnabled()) {
+      return null;
+    }
+    StackTraceElement[] stackTrace = new Throwable().getStackTrace();
+    int limit = Math.min(stackTrace.length, options.getAutoTagTransactionsTracerLimit());
+    List<String> targetPackages = options.getAutoTagTransactionsPackages();
+    boolean hasTargetPackages = targetPackages != null && !targetPackages.isEmpty();
+
+    for (int i = 0; i < limit; i++) {
+      StackTraceElement element = stackTrace[i];
+      String className = element.getClassName();
+      if (hasTargetPackages) {
+        for (String targetPackage : targetPackages) {
+          if (className.startsWith(targetPackage)) {
+            return formatTag(className, element.getMethodName());
+          }
+        }
+      } else {
+        boolean isInternal = false;
+        for (String internalPackage : INTERNAL_PACKAGES) {
+          if (className.startsWith(internalPackage)) {
+            isInternal = true;
+            break;
+          }
+        }
+        if (isInternal) {
+          continue;
+        }
+        return formatTag(className, element.getMethodName());
+      }
+    }
+    return null;
+  }
+
+  private static String formatTag(String className, String methodName) {
+    int lastDot = className.lastIndexOf('.');
+    String simpleClassName = lastDot == -1 ? className : className.substring(lastDot + 1);
+    String tag = simpleClassName + "." + methodName;
+    if (tag.length() > 50) {
+      tag = tag.substring(0, 50);
+    }
+    return tag;
+  }
+}

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/SessionImpl.java

@@ -315,13 +315,19 @@ public CommitResponse writeAtLeastOnceWithOptions(
 
   private RequestOptions getRequestOptions(TransactionOption... transactionOptions) {
     Options requestOptions = Options.fromTransactionOptions(transactionOptions);
-    if (requestOptions.hasPriority() || requestOptions.hasTag()) {
+    String autoTag = null;
+    if (!requestOptions.hasTag()) {
+      autoTag = AutoTagHelper.getAutoTag(spanner.getOptions());
+    }
+    if (requestOptions.hasPriority() || requestOptions.hasTag() || autoTag != null) {
       RequestOptions.Builder requestOptionsBuilder = RequestOptions.newBuilder();
       if (requestOptions.hasPriority()) {
         requestOptionsBuilder.setPriority(requestOptions.priority());
       }
       if (requestOptions.hasTag()) {
         requestOptionsBuilder.setTransactionTag(requestOptions.tag());
+      } else if (autoTag != null) {
+        requestOptionsBuilder.setTransactionTag(autoTag);
       }
       return requestOptionsBuilder.build();
     }
@@ -501,6 +507,12 @@ ApiFuture<Transaction> beginTransactionAsync(
     }
     RequestOptions.Builder optionsBuilder =
         transactionOptions.toRequestOptionsProto(true).toBuilder();
+    if (!transactionOptions.hasTag()) {
+      String autoTag = AutoTagHelper.getAutoTag(spanner.getOptions());
+      if (autoTag != null) {
+        optionsBuilder.setTransactionTag(autoTag);
+      }
+    }
     RequestOptions.ClientContext defaultClientContext = spanner.getOptions().getClientContext();
     if (defaultClientContext != null) {
       RequestOptions.ClientContext.Builder builder = defaultClientContext.toBuilder();

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/SpannerOptions.java

@@ -96,6 +96,7 @@
 import java.time.Duration;
 import java.util.ArrayList;
 import java.util.Base64;
+import java.util.Collections;
 import java.util.HashMap;
 import java.util.List;
 import java.util.Map;
@@ -308,6 +309,9 @@ static GcpChannelPoolOptions mergeWithDefaultChannelPoolOptions(
   private final String monitoringHost;
   private final TransactionOptions defaultTransactionOptions;
   private final RequestOptions.ClientContext clientContext;
+  private final boolean autoTagTransactionsEnabled;
+  private final List<String> autoTagTransactionsPackages;
+  private final int autoTagTransactionsTracerLimit;
 
   enum TracingFramework {
     OPEN_CENSUS,
@@ -993,6 +997,9 @@ protected SpannerOptions(Builder builder) {
     monitoringHost = builder.monitoringHost;
     defaultTransactionOptions = builder.defaultTransactionOptions;
     clientContext = builder.clientContext;
+    autoTagTransactionsEnabled = builder.autoTagTransactionsEnabled;
+    autoTagTransactionsPackages = builder.autoTagTransactionsPackages;
+    autoTagTransactionsTracerLimit = builder.autoTagTransactionsTracerLimit;
   }
 
   private String getResolvedUniverseDomain() {
@@ -1064,6 +1071,10 @@ default boolean isEnableLocationApi() {
       return false;
     }
 
+    default boolean isAutoTagTransactionsDisabled() {
+      return false;
+    }
+
     @Deprecated
     @ObsoleteApi(
         "This will be removed in an upcoming version without a major version bump. You should use"
@@ -1168,6 +1179,12 @@ public boolean isEnableLocationApi() {
       return Boolean.parseBoolean(System.getenv(EXPERIMENTAL_LOCATION_API_ENV_VAR));
     }
 
+    @Override
+    public boolean isAutoTagTransactionsDisabled() {
+      return Boolean.parseBoolean(System.getenv("SPANNER_DISABLE_AUTO_TAGGING"))
+          || Boolean.parseBoolean(System.getProperty("spanner.disable_auto_tagging"));
+    }
+
     @Override
     public String getMonitoringHost() {
       return System.getenv(SPANNER_MONITORING_HOST);
@@ -1256,6 +1273,9 @@ public static class Builder
     private boolean usePlainText = false;
     private TransactionOptions defaultTransactionOptions = TransactionOptions.getDefaultInstance();
     private RequestOptions.ClientContext clientContext;
+    private boolean autoTagTransactionsEnabled = false;
+    private List<String> autoTagTransactionsPackages = Collections.emptyList();
+    private int autoTagTransactionsTracerLimit = 50;
 
     private static String createCustomClientLibToken(String token) {
       return token + " " + ServiceOptions.getGoogApiClientLibName();
@@ -1362,6 +1382,9 @@ protected Builder() {
       this.monitoringHost = options.monitoringHost;
       this.defaultTransactionOptions = options.defaultTransactionOptions;
       this.clientContext = options.clientContext;
+      this.autoTagTransactionsEnabled = options.autoTagTransactionsEnabled;
+      this.autoTagTransactionsPackages = options.autoTagTransactionsPackages;
+      this.autoTagTransactionsTracerLimit = options.autoTagTransactionsTracerLimit;
     }
 
     @Override
@@ -2120,6 +2143,33 @@ public Builder setDefaultClientContext(RequestOptions.ClientContext clientContex
       return this;
     }
 
+    public Builder enableAutoTagTransactions() {
+      this.autoTagTransactionsEnabled = true;
+      return this;
+    }
+
+    public Builder disableAutoTagTransactions() {
+      this.autoTagTransactionsEnabled = false;
+      return this;
+    }
+
+    public Builder setAutoTagTransactionsPackage(String autoTagTransactionsPackage) {
+      this.autoTagTransactionsPackages = Collections.singletonList(autoTagTransactionsPackage);
+      return this;
+    }
+
+    public Builder setAutoTagTransactionsPackages(List<String> autoTagTransactionsPackages) {
+      this.autoTagTransactionsPackages =
+          Collections.unmodifiableList(
+              new ArrayList<>(Preconditions.checkNotNull(autoTagTransactionsPackages)));
+      return this;
+    }
+
+    public Builder setAutoTagTransactionsTracerLimit(int autoTagTransactionsTracerLimit) {
+      this.autoTagTransactionsTracerLimit = autoTagTransactionsTracerLimit;
+      return this;
+    }
+
     @SuppressWarnings("rawtypes")
     @Override
     public SpannerOptions build() {
@@ -2547,6 +2597,22 @@ public TransactionOptions getDefaultTransactionOptions() {
     return defaultTransactionOptions;
   }
 
+  public boolean isAutoTagTransactionsEnabled() {
+    return autoTagTransactionsEnabled && !environment.isAutoTagTransactionsDisabled();
+  }
+
+  public List<String> getAutoTagTransactionsPackages() {
+    return autoTagTransactionsPackages;
+  }
+
+  public int getAutoTagTransactionsTracerLimit() {
+    return autoTagTransactionsTracerLimit;
+  }
+
+  public boolean isAutoTagTransactionsDisabled() {
+    return environment.isAutoTagTransactionsDisabled();
+  }
+
   @BetaApi
   public boolean isUseVirtualThreads() {
     return useVirtualThreads;

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/TransactionRunnerImpl.java

@@ -198,6 +198,7 @@ public void removeListener(Runnable listener) {
     private boolean aborted;
 
     private final Options options;
+    private volatile String cachedTransactionTag;
 
     /** Default to -1 to indicate not available. */
     @GuardedBy("lock")
@@ -780,7 +781,10 @@ String getTransactionTag() {
       if (this.options.hasTag()) {
         return this.options.tag();
       }
-      return null;
+      if (this.cachedTransactionTag == null) {
+        this.cachedTransactionTag = AutoTagHelper.getAutoTag(session.getSpanner().getOptions());
+      }
+      return this.cachedTransactionTag;
     }
 
     @Nullable

java-spanner/google-cloud-spanner/src/test/java/com/google/cloud/spanner/MockAutoTaggingTest.java

@@ -0,0 +1,113 @@
+/*
+ * 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
+ *
+ *       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.
+ */
+
+package com.google.cloud.spanner;
+
+import static org.junit.Assert.assertEquals;
+
+import com.google.cloud.NoCredentials;
+import com.google.spanner.v1.CommitRequest;
+import com.google.spanner.v1.ExecuteSqlRequest;
+import org.junit.Before;
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+@RunWith(JUnit4.class)
+public class MockAutoTaggingTest extends AbstractMockServerTest {
+
+  @Before
+  public void createSpannerInstanceWithAutoTagging() {
+    // Overrides spanner instance in base class to enable auto-tagging targeting org.junit
+    spanner =
+        SpannerOptions.newBuilder()
+            .setProjectId("test-project")
+            .setChannelProvider(channelProvider)
+            .setCredentials(NoCredentials.getInstance())
+            .enableAutoTagTransactions()
+            .setAutoTagTransactionsPackage("org.junit.runners")
+            .setAutoTagTransactionsTracerLimit(200)
+            .build()
+            .getService();
+  }
+
+  @Test
+  public void testReadWriteTransactionAutoTagging() {
+    DatabaseClient databaseClient = spanner.getDatabaseClient(DatabaseId.of("proj", "inst", "db"));
+    mockSpanner.putStatementResult(
+        MockSpannerServiceImpl.StatementResult.update(
+            Statement.of("UPDATE Venues SET Capacity = 100"), 1L));
+
+    databaseClient
+        .readWriteTransaction()
+        .run(
+            transaction -> {
+              transaction.executeUpdate(Statement.of("UPDATE Venues SET Capacity = 100"));
+              return null;
+            });
+
+    // 1. Verify transaction tag is successfully populated on the ExecuteSqlRequest
+    assertEquals(1, mockSpanner.countRequestsOfType(ExecuteSqlRequest.class));
+    ExecuteSqlRequest sqlRequest = mockSpanner.getRequestsOfType(ExecuteSqlRequest.class).get(0);
+    String transactionTag = sqlRequest.getRequestOptions().getTransactionTag();
+    assertEquals("FrameworkMethod$1.runReflectiveCall", transactionTag);
+
+    // 2. Verify transaction tag is successfully populated on CommitRequest and matches
+    assertEquals(1, mockSpanner.countRequestsOfType(CommitRequest.class));
+    CommitRequest commitRequest = mockSpanner.getRequestsOfType(CommitRequest.class).get(0);
+    assertEquals(transactionTag, commitRequest.getRequestOptions().getTransactionTag());
+  }
+
+  @Test
+  public void testSingleUseQueryAutoTagging() {
+    DatabaseClient databaseClient = spanner.getDatabaseClient(DatabaseId.of("proj", "inst", "db"));
+    com.google.spanner.v1.ResultSet select1ResultSet =
+        com.google.spanner.v1.ResultSet.newBuilder()
+            .addRows(
+                com.google.protobuf.ListValue.newBuilder()
+                    .addValues(com.google.protobuf.Value.newBuilder().setStringValue("1").build())
+                    .build())
+            .setMetadata(
+                com.google.spanner.v1.ResultSetMetadata.newBuilder()
+                    .setRowType(
+                        com.google.spanner.v1.StructType.newBuilder()
+                            .addFields(
+                                com.google.spanner.v1.StructType.Field.newBuilder()
+                                    .setName("COL1")
+                                    .setType(
+                                        com.google.spanner.v1.Type.newBuilder()
+                                            .setCode(com.google.spanner.v1.TypeCode.INT64)
+                                            .build())
+                                    .build())
+                            .build())
+                    .build())
+            .build();
+    mockSpanner.putStatementResult(
+        MockSpannerServiceImpl.StatementResult.query(
+            Statement.of("SELECT * FROM Albums"), select1ResultSet));
+
+    try (ResultSet resultSet =
+        databaseClient.singleUse().executeQuery(Statement.of("SELECT * FROM Albums"))) {
+      while (resultSet.next()) {}
+    }
+
+    // Verify request tag is populated on ExecuteSqlRequest and matches junit
+    assertEquals(1, mockSpanner.countRequestsOfType(ExecuteSqlRequest.class));
+    ExecuteSqlRequest sqlRequest = mockSpanner.getRequestsOfType(ExecuteSqlRequest.class).get(0);
+    String requestTag = sqlRequest.getRequestOptions().getRequestTag();
+    assertEquals("FrameworkMethod$1.runReflectiveCall", requestTag);
+  }
+}