Add option collectEvictionWeightAsCounter to collect caffeine_cache_eviction_weight as an incremental counter

jhominal · jhominal · commit 5515d62cf47b · 2025-01-18T02:09:09.000+01:00
Signed-off-by: Jean Hominal &lt;jhominal@gmail.com&gt;
diff --git a/prometheus-metrics-instrumentation-caffeine/src/main/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollector.java b/prometheus-metrics-instrumentation-caffeine/src/main/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollector.java
@@ -84,6 +84,30 @@ public class CacheMetricsCollector implements MultiCollector {
               METRIC_NAME_CACHE_LOAD_DURATION_SECONDS));
 
   protected final ConcurrentMap<String, Cache<?, ?>> children = new ConcurrentHashMap<>();
+  private final boolean collectEvictionWeightAsCounter;
+
+  /**
+   * Instantiates a {@link CacheMetricsCollector}, with the legacy parameters.
+   *
+   * <p>The use of this constructor is discouraged, in favor of a Builder pattern {@link #builder()}
+   *
+   * <p>Note that the {@link #builder()} API has different default values than this deprecated
+   * constructor.
+   */
+  @Deprecated
+  public CacheMetricsCollector() {
+    this(false);
+  }
+
+  /**
+   * Instantiate a {@link CacheMetricsCollector}
+   *
+   * @param collectEvictionWeightAsCounter If true, {@code caffeine_cache_eviction_weight} will be
+   *     observed as an incrementing counter instead of a gauge.
+   */
+  protected CacheMetricsCollector(boolean collectEvictionWeightAsCounter) {
+    this.collectEvictionWeightAsCounter = collectEvictionWeightAsCounter;
+  }
 
   /**
    * Add or replace the cache with the given name.
@@ -154,6 +178,10 @@ public MetricSnapshots collect() {
         CounterSnapshot.builder()
             .name(METRIC_NAME_CACHE_EVICTION_WEIGHT)
             .help("Weight of evicted cache entries, doesn't include manually removed entries");
+    final GaugeSnapshot.Builder cacheEvictionWeightLegacyGauge =
+        GaugeSnapshot.builder()
+            .name(METRIC_NAME_CACHE_EVICTION_WEIGHT)
+            .help("Weight of evicted cache entries, doesn't include manually removed entries");
 
     final CounterSnapshot.Builder cacheLoadFailure =
         CounterSnapshot.builder().name(METRIC_NAME_CACHE_LOAD_FAILURE).help("Cache load failures");
@@ -188,6 +216,11 @@ public MetricSnapshots collect() {
                 .labels(labels)
                 .value(stats.evictionWeight())
                 .build());
+        cacheEvictionWeightLegacyGauge.dataPoint(
+            GaugeSnapshot.GaugeDataPointSnapshot.builder()
+                .labels(labels)
+                .value(stats.evictionWeight())
+                .build());
       } catch (Exception e) {
         // EvictionWeight metric is unavailable, newer version of Caffeine is needed.
       }
@@ -258,7 +291,10 @@ public MetricSnapshots collect() {
         .metricSnapshot(cacheMissTotal.build())
         .metricSnapshot(cacheRequestsTotal.build())
         .metricSnapshot(cacheEvictionTotal.build())
-        .metricSnapshot(cacheEvictionWeight.build())
+        .metricSnapshot(
+            collectEvictionWeightAsCounter
+                ? cacheEvictionWeight.build()
+                : cacheEvictionWeightLegacyGauge.build())
         .metricSnapshot(cacheLoadFailure.build())
         .metricSnapshot(cacheLoadTotal.build())
         .metricSnapshot(cacheSize.build())
@@ -277,8 +313,16 @@ public static Builder builder() {
   }
 
   public static class Builder {
+
+    private boolean collectEvictionWeightAsCounter = true;
+
+    public Builder collectEvictionWeightAsCounter(boolean collectEvictionWeightAsCounter) {
+      this.collectEvictionWeightAsCounter = collectEvictionWeightAsCounter;
+      return this;
+    }
+
     public CacheMetricsCollector build() {
-      return new CacheMetricsCollector();
+      return new CacheMetricsCollector(collectEvictionWeightAsCounter);
     }
   }
 }
diff --git a/prometheus-metrics-instrumentation-caffeine/src/test/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollectorTest.java b/prometheus-metrics-instrumentation-caffeine/src/test/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollectorTest.java
@@ -13,6 +13,7 @@
 import io.prometheus.metrics.model.registry.PrometheusRegistry;
 import io.prometheus.metrics.model.snapshots.CounterSnapshot;
 import io.prometheus.metrics.model.snapshots.DataPointSnapshot;
+import io.prometheus.metrics.model.snapshots.GaugeSnapshot;
 import io.prometheus.metrics.model.snapshots.Labels;
 import io.prometheus.metrics.model.snapshots.MetricSnapshots;
 import io.prometheus.metrics.model.snapshots.SummarySnapshot;
@@ -22,17 +23,34 @@
 import java.nio.charset.StandardCharsets;
 import java.util.List;
 import org.junit.jupiter.api.Test;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.EnumSource;
 
 @SuppressWarnings("CheckReturnValue")
 class CacheMetricsCollectorTest {
+  // This enum was added to simplify test parametrization on argument options.
+  public enum Options {
+    LEGACY(false),
+    COLLECT_EVICTION_WEIGHT_AS_COUNTER(true);
 
-  @Test
-  public void cacheExposesMetricsForHitMissAndEviction() {
+    private final boolean collectEvictionWeightAsCounter;
+
+    Options(boolean collectEvictionWeightAsCounter) {
+      this.collectEvictionWeightAsCounter = collectEvictionWeightAsCounter;
+    }
+  }
+
+  @ParameterizedTest
+  @EnumSource
+  public void cacheExposesMetricsForHitMissAndEviction(Options options) {
     // Run cleanup in same thread, to remove async behavior with evictions
     final Cache<String, String> cache =
         Caffeine.newBuilder().maximumSize(2).recordStats().executor(Runnable::run).build();
 
-    final CacheMetricsCollector collector = CacheMetricsCollector.builder().build();
+    final CacheMetricsCollector collector =
+        CacheMetricsCollector.builder()
+            .collectEvictionWeightAsCounter(options.collectEvictionWeightAsCounter)
+            .build();
     collector.addCache("users", cache);
 
     final PrometheusRegistry registry = new PrometheusRegistry();
@@ -52,7 +70,20 @@ public void cacheExposesMetricsForHitMissAndEviction() {
     assertCounterMetric(registry, "caffeine_cache_miss", "users", 2.0);
     assertCounterMetric(registry, "caffeine_cache_requests", "users", 3.0);
     assertCounterMetric(registry, "caffeine_cache_eviction", "users", 2.0);
-    assertCounterMetric(registry, "caffeine_cache_eviction_weight", "users", 2.0);
+    String openMetricEvictionWeightExpectedText;
+    if (options.collectEvictionWeightAsCounter) {
+      assertCounterMetric(registry, "caffeine_cache_eviction_weight", "users", 2.0);
+      openMetricEvictionWeightExpectedText =
+          "# TYPE caffeine_cache_eviction_weight counter\n"
+              + "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
+              + "caffeine_cache_eviction_weight_total{cache=\"users\"} 2.0\n";
+    } else {
+      assertGaugeMetric(registry, "caffeine_cache_eviction_weight", "users", 2.0);
+      openMetricEvictionWeightExpectedText =
+          "# TYPE caffeine_cache_eviction_weight gauge\n"
+              + "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
+              + "caffeine_cache_eviction_weight{cache=\"users\"} 2.0\n";
+    }
 
     final String expected =
         "# TYPE caffeine_cache_estimated_size gauge\n"
@@ -61,9 +92,7 @@ public void cacheExposesMetricsForHitMissAndEviction() {
             + "# TYPE caffeine_cache_eviction counter\n"
             + "# HELP caffeine_cache_eviction Cache eviction totals, doesn't include manually removed entries\n"
             + "caffeine_cache_eviction_total{cache=\"users\"} 2.0\n"
-            + "# TYPE caffeine_cache_eviction_weight counter\n"
-            + "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
-            + "caffeine_cache_eviction_weight_total{cache=\"users\"} 2.0\n"
+            + openMetricEvictionWeightExpectedText
             + "# TYPE caffeine_cache_hit counter\n"
             + "# HELP caffeine_cache_hit Cache hit totals\n"
             + "caffeine_cache_hit_total{cache=\"users\"} 1.0\n"
@@ -78,8 +107,9 @@ public void cacheExposesMetricsForHitMissAndEviction() {
     assertThat(convertToOpenMetricsFormat(registry)).isEqualTo(expected);
   }
 
-  @Test
-  public void weightedCacheExposesMetricsForHitMissAndEvictionWeightedSize() {
+  @ParameterizedTest
+  @EnumSource
+  public void weightedCacheExposesMetricsForHitMissAndEvictionWeightedSize(Options options) {
     // Run cleanup in same thread, to remove async behavior with evictions
     final Cache<String, String> cache =
         Caffeine.newBuilder()
@@ -89,7 +119,10 @@ public void weightedCacheExposesMetricsForHitMissAndEvictionWeightedSize() {
             .executor(Runnable::run)
             .build();
 
-    final CacheMetricsCollector collector = CacheMetricsCollector.builder().build();
+    final CacheMetricsCollector collector =
+        CacheMetricsCollector.builder()
+            .collectEvictionWeightAsCounter(options.collectEvictionWeightAsCounter)
+            .build();
     collector.addCache("users", cache);
 
     final PrometheusRegistry registry = new PrometheusRegistry();
@@ -109,7 +142,20 @@ public void weightedCacheExposesMetricsForHitMissAndEvictionWeightedSize() {
     assertCounterMetric(registry, "caffeine_cache_miss", "users", 2.0);
     assertCounterMetric(registry, "caffeine_cache_requests", "users", 3.0);
     assertCounterMetric(registry, "caffeine_cache_eviction", "users", 2.0);
-    assertCounterMetric(registry, "caffeine_cache_eviction_weight", "users", 31.0);
+    String openMetricEvictionWeightExpectedText;
+    if (options.collectEvictionWeightAsCounter) {
+      assertCounterMetric(registry, "caffeine_cache_eviction_weight", "users", 31.0);
+      openMetricEvictionWeightExpectedText =
+          "# TYPE caffeine_cache_eviction_weight counter\n"
+              + "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
+              + "caffeine_cache_eviction_weight_total{cache=\"users\"} 31.0\n";
+    } else {
+      assertGaugeMetric(registry, "caffeine_cache_eviction_weight", "users", 31.0);
+      openMetricEvictionWeightExpectedText =
+          "# TYPE caffeine_cache_eviction_weight gauge\n"
+              + "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
+              + "caffeine_cache_eviction_weight{cache=\"users\"} 31.0\n";
+    }
 
     final String expected =
         "# TYPE caffeine_cache_estimated_size gauge\n"
@@ -118,9 +164,7 @@ public void weightedCacheExposesMetricsForHitMissAndEvictionWeightedSize() {
             + "# TYPE caffeine_cache_eviction counter\n"
             + "# HELP caffeine_cache_eviction Cache eviction totals, doesn't include manually removed entries\n"
             + "caffeine_cache_eviction_total{cache=\"users\"} 2.0\n"
-            + "# TYPE caffeine_cache_eviction_weight counter\n"
-            + "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
-            + "caffeine_cache_eviction_weight_total{cache=\"users\"} 31.0\n"
+            + openMetricEvictionWeightExpectedText
             + "# TYPE caffeine_cache_hit counter\n"
             + "# HELP caffeine_cache_hit Cache hit totals\n"
             + "caffeine_cache_hit_total{cache=\"users\"} 1.0\n"
@@ -178,9 +222,13 @@ public void loadingCacheExposesMetricsForLoadsAndExceptions() throws Exception {
     assertThat(loadDuration.getSum()).isGreaterThan(0);
   }
 
-  @Test
-  public void getPrometheusNamesHasSameSizeAsMetricSizeWhenScraping() {
-    final CacheMetricsCollector collector = CacheMetricsCollector.builder().build();
+  @ParameterizedTest
+  @EnumSource
+  public void getPrometheusNamesHasSameSizeAsMetricSizeWhenScraping(Options options) {
+    final CacheMetricsCollector collector =
+        CacheMetricsCollector.builder()
+            .collectEvictionWeightAsCounter(options.collectEvictionWeightAsCounter)
+            .build();
 
     final PrometheusRegistry registry = new PrometheusRegistry();
     registry.register(collector);
@@ -191,9 +239,13 @@ public void getPrometheusNamesHasSameSizeAsMetricSizeWhenScraping() {
     assertThat(prometheusNames).hasSize(metricSnapshots.size());
   }
 
-  @Test
-  public void collectedMetricNamesAreKnownPrometheusNames() {
-    final CacheMetricsCollector collector = CacheMetricsCollector.builder().build();
+  @ParameterizedTest
+  @EnumSource
+  public void collectedMetricNamesAreKnownPrometheusNames(Options options) {
+    final CacheMetricsCollector collector =
+        CacheMetricsCollector.builder()
+            .collectEvictionWeightAsCounter(options.collectEvictionWeightAsCounter)
+            .build();
 
     final PrometheusRegistry registry = new PrometheusRegistry();
     registry.register(collector);
@@ -214,6 +266,14 @@ private void assertCounterMetric(
     assertThat(dataPointSnapshot.getValue()).isEqualTo(value);
   }
 
+  private void assertGaugeMetric(
+      PrometheusRegistry registry, String name, String cacheName, double value) {
+    final GaugeSnapshot.GaugeDataPointSnapshot dataPointSnapshot =
+        (GaugeSnapshot.GaugeDataPointSnapshot) getDataPointSnapshot(registry, name, cacheName);
+
+    assertThat(dataPointSnapshot.getValue()).isEqualTo(value);
+  }
+
   private DataPointSnapshot getDataPointSnapshot(
       PrometheusRegistry registry, String name, String cacheName) {
     final Labels labels = Labels.of(new String[] {"cache"}, new String[] {cacheName});
