[automatic failover] Implement sliding time window metrics tracker (#3521)

* abstract clock for easy testing

* Improve LockFreeSlidingWindowMetrics: fix bugs and add tests

Bug Fixes:
- Fix: Ensure snapshot metrics remain accurate after a full window rotation
- Fix: events recorded exactly at bucket boundaries were miscounted
- Enforce window size % bucket size == 0
- Move LockFreeSlidingWindowMetricsUnitTests to correct package
  (io.lettuce.core.failover.metrics)

* remove unused reset methods

* extract interface for MetricsSnapshot

   - remove snapshotTime - not used & not correctly calcualted
   - remove reset metrics - unused as of now

* add LockFreeSlidingWindowMetrics benchmark test

* performance tests moved to metrics package

* replace with port from reselience4j

* update copyrights

* format

* clean up javadocs

* clean up
   - fix incorrect javadoc
   - fix failing benchmark

* [automatic failover] Hide failover metrics implementation

 - CircuitBreakerMetrics, MetricsSnapshot - public
 - metrics implementation details stay inside io.lettuce.core.failover.metrics
 - Update CircuitBreaker to obtain its metrics via CircuitBreakerMetricsFactory.createLockFree()

* Apply suggestions from code review

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* rename createLockFree -> createDefaultMetrics

* address review comments by @atakavci

    - remove CircuitBreakerMetrics, CircuitBreakerMetricsImpl
    - rename SlidingWindowMetrics -> CircuitBreakerMetrics

* format

* Enforce min-window size of 2 buckets

  Current implementation requires at least 2 buckets window
        With windowSize=1, only one node is created with next=null
        When updateWindow() advances the window it sets HEAD to headNext, which is null for a single-node window
        On the next call to updateWindow(), tries to access head.next but head is now null, causing:
        NullPointerException: Cannot read field "next" because "head" is null

* Clean-up benchmark

   - benchmark matrix
       threads (1,4)
       window_size ("2", "30", "180")
   - performs 1_000_000 ops in simulated 5min test window
   - benchmark record events
   - benchmark record & read snapshot

* remove MetricsPerformanceTests.java

  - no reliable way to assert on performance, instead added basic benchmark test to benchmark  recording/snapshot reading average times
 - gc benchmarks are available for local testing

* reset method removed

* Apply suggestion from @Copilot

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Apply suggestion from @atakavci

Co-authored-by: atakavci <a_takavci@yahoo.com>

* Update src/main/java/io/lettuce/core/failover/metrics/CircuitBreakerMetrics.java

Co-authored-by: Tihomir Krasimirov Mateev <tihomir.mateev@redis.com>

* add missing license header and javadoc

* add missing license header and javadoc

* correct author for jmh failover metrics

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: atakavci <a_takavci@yahoo.com>
Co-authored-by: Tihomir Krasimirov Mateev <tihomir.mateev@redis.com>

Author: 4 people

pom.xml

@@ -1296,7 +1296,7 @@
                                         <argument>-classpath</argument>
                                         <classpath />
                                         <argument>org.openjdk.jmh.Main</argument>
-                                        <argument>.*</argument>
+                                        <argument>.*failover.*</argument>
                                         <argument>-tu</argument>
                                         <!--
                               Override time unit in benchmark results. Available

src/main/java/io/lettuce/core/failover/CircuitBreaker.java

@@ -17,7 +17,7 @@
 import io.lettuce.core.RedisConnectionException;
 import io.lettuce.core.failover.api.CircuitBreakerStateListener;
 import io.lettuce.core.failover.metrics.CircuitBreakerMetrics;
-import io.lettuce.core.failover.metrics.CircuitBreakerMetricsImpl;
+import io.lettuce.core.failover.metrics.MetricsFactory;
 import io.lettuce.core.failover.metrics.MetricsSnapshot;
 
 /**
@@ -45,7 +45,7 @@ public class CircuitBreaker implements Closeable {
      * Create a circuit breaker instance.
      */
     public CircuitBreaker(CircuitBreakerConfig config) {
-        this.metrics = new CircuitBreakerMetricsImpl();
+        this.metrics = MetricsFactory.createDefaultMetrics();
         this.config = config;
         this.trackedExceptions = new HashSet<>(config.trackedExceptions);
     }
@@ -54,7 +54,7 @@ public CircuitBreaker(CircuitBreakerConfig config) {
      * Get the metrics tracked by this circuit breaker.
      * <p>
      * This is only for internal use and testing purposes.
-     * 
+     *
      * @return the circuit breaker metrics
      */
     CircuitBreakerMetrics getMetrics() {

src/main/java/io/lettuce/core/failover/metrics/CircuitBreakerMetrics.java

@@ -1,12 +1,15 @@
 package io.lettuce.core.failover.metrics;
 
 /**
- * Interface for circuit breaker metrics tracking successes and failures within a time-based sliding window. Thread-safe and
- * lock-free using atomic operations.
+ * Interface for sliding window metrics. Allows tracking of success and failure counts within a configurable window.
  *
  * <p>
- * This interface defines the contract for tracking metrics over a configurable time period. Old data outside the window is
- * automatically expired and cleaned up.
+ * Implementations must be:
+ * <ul>
+ * <li>Thread-safe: Safe for concurrent access from multiple threads</li>
+ * <li>Efficient: Minimal memory overhead and fast operations</li>
+ * <li>Time-based: Automatic expiration of old data outside the window</li>
+ * </ul>
  * </p>
  *
  * @author Ali Takavci
@@ -15,26 +18,21 @@
 public interface CircuitBreakerMetrics {
 
     /**
-     * Record a successful command execution. Lock-free operation.
+     * Record a successful command execution.
      */
     void recordSuccess();
 
     /**
-     * Record a failed command execution. Lock-free operation.
+     * Record a failed command execution.
      */
     void recordFailure();
 
     /**
-     * Get a snapshot of the current metrics within the time window. Use the snapshot to access success count, failure count,
-     * total count, and failure rate.
+     * Get a snapshot of the current metrics within the time window. This is a point-in-time view and does not change after
+     * being returned. Use the snapshot to access success count, failure count, total count, and failure rate.
      *
      * @return an immutable snapshot of current metrics
      */
     MetricsSnapshot getSnapshot();
 
-    /**
-     * Reset all metrics to zero.
-     */
-    void reset();
-
 }

src/main/java/io/lettuce/core/failover/metrics/CircuitBreakerMetricsImpl.java

@@ -0,0 +1,56 @@
+/*
+ * Copyright 2011-Present, Redis Ltd. and Contributors
+ * All rights reserved.
+ *
+ * Licensed under the MIT License.
+ *
+ * This file contains contributions from third-party contributors
+ * 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.
+ *
+ * ---
+ *
+ * Ported from Resilience4j's LockFreeSlidingTimeWindowMetrics
+ * Copyright 2024 Florentin Simion and Rares Vlasceanu
+ * Licensed under the Apache License, Version 2.0
+ * https://github.com/resilience4j/resilience4j
+ *
+ * Modifications:
+ * - Ported to be compatible with Java 8: Replaced VarHandle with AtomicReference
+ * - Stripped down unused metrics: Removed duration and slow call tracking
+ */
+
+package io.lettuce.core.failover.metrics;
+
+/**
+ * Clock abstraction for obtaining the current time in nanoseconds.
+ * <p>
+ * This interface allows for testable time-dependent code by enabling injection of custom clock implementations.
+ * </p>
+ *
+ * @since 7.1
+ */
+interface Clock {
+
+    /**
+     * System clock implementation using {@link System#nanoTime()}.
+     */
+    Clock SYSTEM = System::nanoTime;
+
+    /**
+     * Get the current time in nanoseconds.
+     *
+     * @return the current time in nanoseconds
+     */
+    long monotonicTime();
+
+}

src/main/java/io/lettuce/core/failover/metrics/Clock.java

@@ -0,0 +1,45 @@
+/*
+ * Copyright 2011-Present, Redis Ltd. and Contributors
+ * All rights reserved.
+ *
+ * Licensed under the MIT License.
+ *
+ * This file contains contributions from third-party contributors
+ * 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.
+ *
+ * ---
+ *
+ * Ported from Resilience4j's LockFreeSlidingTimeWindowMetrics
+ * Copyright 2024 Florentin Simion and Rares Vlasceanu
+ * Licensed under the Apache License, Version 2.0
+ * https://github.com/resilience4j/resilience4j
+ *
+ * Modifications:
+ * - Ported to be compatible with Java 8: Replaced VarHandle with AtomicReference
+ * - Stripped down unused metrics: Removed duration and slow call tracking
+ */
+package io.lettuce.core.failover.metrics;
+
+/**
+ * Interface for measurement implementations that accumulate calls and outcomes.
+ */
+interface CumulativeMeasurement extends MeasurementData {
+
+    /**
+     * Records the outcome of a call.
+     *
+     * @param outcome the outcome of the call
+     */
+    void record(Outcome outcome);
+
+}