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;
@@ -842,6 +843,15 @@ RequestOptions buildRequestOptions(Options options) {
     }
     if (getTransactionTag() != null) {
       builder.setTransactionTag(getTransactionTag());
+    } else if (session.getSpanner().getOptions().isAutoTagTransactionsEnabled()
+        && builder.getRequestTag().isEmpty()) {
+      if (this.cachedRequestTag == null) {
+        String autoTag = AutoTagHelper.getAutoTag(session.getSpanner().getOptions());
+        this.cachedRequestTag = autoTag == null ? "" : autoTag;
+      }
+      if (!this.cachedRequestTag.isEmpty()) {
+        builder.setRequestTag(this.cachedRequestTag);
+      }
     }
     return builder.build();
   }

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

@@ -0,0 +1,95 @@
+/*
+ * 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;
+
+/** Helper for Spanner transaction tags. */
+final class AutoTagHelper {
+
+  /** Maximum allowed character length for resolved tags. */
+  private static final int MAX_TAG_LENGTH = 50;
+
+  /** Ignored packages. */
+  private static final String[] INTERNAL_PACKAGES;
+
+  static {
+    INTERNAL_PACKAGES =
+        new String[] {
+          "java.",
+          "javax.",
+          "jdk.",
+          "sun.",
+          "io.grpc.",
+          "com.google.cloud.spanner.",
+          "com.google.api."
+        };
+  }
+
+  private AutoTagHelper() {
+    // prevent instantiation
+  }
+
+  static String getAutoTag(final SpannerOptions options) {
+    StackTraceElement[] stackTrace = new Throwable().getStackTrace();
+    int tracerLimit = options.getAutoTagTransactionsTracerLimit();
+    int limit = Math.min(stackTrace.length, tracerLimit);
+    List<String> targetPackages = options.getAutoTagTransactionsPackages();
+    boolean hasTarget = targetPackages != null && !targetPackages.isEmpty();
+
+    for (int i = 0; i < limit; i++) {
+      StackTraceElement element = stackTrace[i];
+      String className = element.getClassName();
+      if (hasTarget) {
+        for (String targetPackage : targetPackages) {
+          if (className.startsWith(targetPackage)) {
+            return formatTag(className, element.getMethodName());
+          }
+        }
+      } else if (isInternalPackage(className)) {
+        continue;
+      } else {
+        return formatTag(className, element.getMethodName());
+      }
+    }
+    return null;
+  }
+
+  private static boolean isInternalPackage(final String cls) {
+    for (String internalPackage : INTERNAL_PACKAGES) {
+      if (cls.startsWith(internalPackage)) {
+        return true;
+      }
+    }
+    return false;
+  }
+
+  private static String formatTag(final String cls, final String method) {
+    int lastDot = cls.lastIndexOf('.');
+    String simpleClassName;
+    if (lastDot == -1) {
+      simpleClassName = cls;
+    } else {
+      simpleClassName = cls.substring(lastDot + 1);
+    }
+    String tag = simpleClassName + "." + method;
+    if (tag.length() > MAX_TAG_LENGTH) {
+      tag = tag.substring(tag.length() - MAX_TAG_LENGTH);
+    }
+    return tag;
+  }
+}

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,14 @@ default boolean isEnableLocationApi() {
       return false;
     }
 
+    default boolean isAutoTagTransactionsDisabled() {
+      return false;
+    }
+
+    default boolean isAutoTagTransactionsEnabled() {
+      return false;
+    }
+
     @Deprecated
     @ObsoleteApi(
         "This will be removed in an upcoming version without a major version bump. You should use"
@@ -1168,6 +1183,18 @@ 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 boolean isAutoTagTransactionsEnabled() {
+      return Boolean.parseBoolean(System.getenv("SPANNER_ENABLE_AUTO_TAGGING"))
+          || Boolean.getBoolean("spanner.enable_auto_tagging");
+    }
+
     @Override
     public String getMonitoringHost() {
       return System.getenv(SPANNER_MONITORING_HOST);
@@ -1256,6 +1283,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 +1392,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 +2153,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 +2607,25 @@ public TransactionOptions getDefaultTransactionOptions() {
     return defaultTransactionOptions;
   }
 
+  public boolean isAutoTagTransactionsEnabled() {
+    if (environment.isAutoTagTransactionsDisabled()) {
+      return false;
+    }
+    return autoTagTransactionsEnabled || environment.isAutoTagTransactionsEnabled();
+  }
+
+  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,6 +781,15 @@ String getTransactionTag() {
       if (this.options.hasTag()) {
         return this.options.tag();
       }
+      if (session.getSpanner().getOptions().isAutoTagTransactionsEnabled()) {
+        if (this.cachedTransactionTag == null) {
+          this.cachedTransactionTag = AutoTagHelper.getAutoTag(session.getSpanner().getOptions());
+          if (this.cachedTransactionTag == null) {
+            this.cachedTransactionTag = "";
+          }
+        }
+        return this.cachedTransactionTag.isEmpty() ? null : this.cachedTransactionTag;
+      }
       return null;
     }
 

java-spanner/google-cloud-spanner/src/test/java/com/example/spanner/TagTestHelper.java

@@ -0,0 +1,68 @@
+/*
+ * 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.example.spanner;
+
+import com.google.api.core.ApiFuture;
+import com.google.cloud.spanner.DatabaseClient;
+import com.google.cloud.spanner.Options.TransactionOption;
+import com.google.cloud.spanner.TransactionRunner;
+import com.google.common.util.concurrent.MoreExecutors;
+
+/** Helper class in a non-ignored package to stable-test auto-tagging stack walks. */
+public final class TagTestHelper {
+
+  private TagTestHelper() {}
+
+  public static <T> T run(
+      DatabaseClient client, TransactionRunner.TransactionCallable<T> callable) {
+    return client.readWriteTransaction().run(callable);
+  }
+
+  public static <T> T runWithOptions(
+      DatabaseClient client,
+      TransactionRunner.TransactionCallable<T> callable,
+      TransactionOption option) {
+    return client.readWriteTransaction(option).run(callable);
+  }
+
+  public static <R> ApiFuture<R> runAsync(
+      DatabaseClient client, com.google.cloud.spanner.AsyncRunner.AsyncWork<R> work) {
+    return client.runAsync().runAsync(work, MoreExecutors.directExecutor());
+  }
+
+  public static void singleUseConsume(
+      DatabaseClient client, com.google.cloud.spanner.Statement stmt) {
+    try (com.google.cloud.spanner.ResultSet resultSet = client.singleUse().executeQuery(stmt)) {
+      while (resultSet.next()) {}
+    }
+  }
+
+  public static void readOnlyTxnConsume(
+      com.google.cloud.spanner.ReadOnlyTransaction txn, com.google.cloud.spanner.Statement stmt) {
+    try (com.google.cloud.spanner.ResultSet resultSet = txn.executeQuery(stmt)) {
+      while (resultSet.next()) {}
+    }
+  }
+
+  /** Subclass with an extremely long name to test tag truncation rules. */
+  public static final class ExtremelyLongClassNameForTestingTagTruncationSupportUnderCheckstyle {
+    public static <T> T run(
+        DatabaseClient client, TransactionRunner.TransactionCallable<T> callable) {
+      return client.readWriteTransaction().run(callable);
+    }
+  }
+}