chore(spanner): add LatencyTracker interface and default implementation

Adds an internal LatencyTracker interface and a default implementation that allows the
client to track the latency of requests. This can be used for automatic replica
selection and load balancing.

Author: olavloite

java-spanner/.gitignore

@@ -0,0 +1,85 @@
+/*
+ * 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.spi.v1;
+
+import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
+import com.google.common.base.Preconditions;
+import javax.annotation.concurrent.GuardedBy;
+
+/**
+ * Implementation of {@link LatencyTracker} using Exponentially Weighted Moving Average (EWMA).
+ *
+ * <p>Formula: $S_{i+1} = \alpha * new\_latency + (1 - \alpha) * S_i$
+ *
+ * <p>This class is thread-safe.
+ */
+@InternalApi
+@BetaApi
+public class EwmaLatencyTracker implements LatencyTracker {
+
+  public static final double DEFAULT_ALPHA = 0.05;
+
+  private final double alpha;
+  private final Object lock = new Object();
+
+  @GuardedBy("lock")
+  private double score;
+
+  @GuardedBy("lock")
+  private boolean initialized = false;
+
+  /** Creates a new tracker with the default alpha value of 0.05. */
+  public EwmaLatencyTracker() {
+    this(DEFAULT_ALPHA);
+  }
+
+  /**
+   * Creates a new tracker with the specified alpha value.
+   *
+   * @param alpha the smoothing factor, must be in the range (0, 1]
+   */
+  public EwmaLatencyTracker(double alpha) {
+    Preconditions.checkArgument(alpha > 0.0 && alpha <= 1.0, "alpha must be in (0, 1]");
+    this.alpha = alpha;
+  }
+
+  @Override
+  public double getScore() {
+    synchronized (lock) {
+      return initialized ? score : Double.MAX_VALUE;
+    }
+  }
+
+  @Override
+  public void update(long latencyMillis) {
+    synchronized (lock) {
+      if (!initialized) {
+        score = latencyMillis;
+        initialized = true;
+      } else {
+        score = alpha * latencyMillis + (1 - alpha) * score;
+      }
+    }
+  }
+
+  @Override
+  public void recordError(long penaltyMillis) {
+    // Treat the error as a sample with high latency (penalty)
+    update(penaltyMillis);
+  }
+}

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/EwmaLatencyTracker.java

@@ -0,0 +1,52 @@
+/*
+ * 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.spi.v1;
+
+import com.google.api.core.BetaApi;
+import com.google.api.core.InternalApi;
+
+/**
+ * Interface for tracking latency scores of Spanner servers.
+ *
+ * <p>Implementations must be thread-safe as instances may be shared across multiple concurrent
+ * operations.
+ */
+@InternalApi
+@BetaApi
+public interface LatencyTracker {
+
+  /**
+   * Returns the current latency score.
+   *
+   * @return the latency score, where lower is better.
+   */
+  double getScore();
+
+  /**
+   * Updates the latency score with a new observation.
+   *
+   * @param latencyMillis the observed latency in milliseconds.
+   */
+  void update(long latencyMillis);
+
+  /**
+   * Records an error and applies a latency penalty.
+   *
+   * @param penaltyMillis the penalty in milliseconds to apply.
+   */
+  void recordError(long penaltyMillis);
+}

java-spanner/google-cloud-spanner/src/main/java/com/google/cloud/spanner/spi/v1/LatencyTracker.java

@@ -0,0 +1,93 @@
+/*
+ * 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.spi.v1;
+
+import static org.junit.Assert.assertEquals;
+import static org.junit.Assert.assertThrows;
+
+import org.junit.Test;
+import org.junit.runner.RunWith;
+import org.junit.runners.JUnit4;
+
+@RunWith(JUnit4.class)
+public class EwmaLatencyTrackerTest {
+
+  @Test
+  public void testInitialization() {
+    EwmaLatencyTracker tracker = new EwmaLatencyTracker();
+    tracker.update(100);
+    assertEquals(100.0, tracker.getScore(), 0.001);
+  }
+
+  @Test
+  public void testUninitializedScore() {
+    EwmaLatencyTracker tracker = new EwmaLatencyTracker();
+    assertEquals(Double.MAX_VALUE, tracker.getScore(), 0.001);
+  }
+
+  @Test
+  public void testEwmaCalculation() {
+    double alpha = 0.5;
+    EwmaLatencyTracker tracker = new EwmaLatencyTracker(alpha);
+
+    tracker.update(100); // Initial score = 100
+    assertEquals(100.0, tracker.getScore(), 0.001);
+
+    tracker.update(200); // Score = 0.5 * 200 + 0.5 * 100 = 150
+    assertEquals(150.0, tracker.getScore(), 0.001);
+
+    tracker.update(300); // Score = 0.5 * 300 + 0.5 * 150 = 225
+    assertEquals(225.0, tracker.getScore(), 0.001);
+  }
+
+  @Test
+  public void testDefaultAlpha() {
+    EwmaLatencyTracker tracker = new EwmaLatencyTracker();
+    tracker.update(100);
+    tracker.update(200);
+
+    double expected =
+        EwmaLatencyTracker.DEFAULT_ALPHA * 200 + (1 - EwmaLatencyTracker.DEFAULT_ALPHA) * 100;
+    assertEquals(expected, tracker.getScore(), 0.001);
+  }
+
+  @Test
+  public void testRecordError() {
+    EwmaLatencyTracker tracker = new EwmaLatencyTracker(0.5);
+    tracker.update(100);
+
+    tracker.recordError(10000); // Score = 0.5 * 10000 + 0.5 * 100 = 5050
+    assertEquals(5050.0, tracker.getScore(), 0.001);
+  }
+
+  @Test
+  public void testInvalidAlpha() {
+    assertThrows(IllegalArgumentException.class, () -> new EwmaLatencyTracker(0.0));
+    assertThrows(IllegalArgumentException.class, () -> new EwmaLatencyTracker(1.1));
+    assertThrows(IllegalArgumentException.class, () -> new EwmaLatencyTracker(-0.1));
+  }
+
+  @Test
+  public void testAlphaOne() {
+    EwmaLatencyTracker tracker = new EwmaLatencyTracker(1.0);
+    tracker.update(100);
+    assertEquals(100.0, tracker.getScore(), 0.001);
+
+    tracker.update(200);
+    assertEquals(200.0, tracker.getScore(), 0.001);
+  }
+}