Skip to content

Commit ec06ab9

Browse files
jhominaljhominal
authoredJan 20, 2025··
Caffeine instrumentation: add weighted size metric (#1251)
* Change caffeine_cache_eviction_weight from Gauge to Counter Signed-off-by: Jean Hominal <[email protected]> * Add caffeine_cache_weighted_size gauge metric to caffeine-instrumentation Signed-off-by: Jean Hominal <[email protected]> * Add Builder pattern for caffeine CacheMetricsCollector Signed-off-by: Jean Hominal <[email protected]> * Add option collectEvictionWeightAsCounter to collect caffeine_cache_eviction_weight as an incremental counter Signed-off-by: Jean Hominal <[email protected]> * Add option collectWeightedSize to enable collection of caffeine_cache_weighted_size Signed-off-by: Jean Hominal <[email protected]> --------- Signed-off-by: Jean Hominal <[email protected]>
·
v1.3.6
1 parent e05ca38 commit ec06ab9

File tree

2 files changed

+247
-17
lines changed

2 files changed

+247
-17
lines changed
 

‎prometheus-metrics-instrumentation-caffeine/src/main/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollector.java

+98-4
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@
33
import com.github.benmanes.caffeine.cache.AsyncCache;
44
import com.github.benmanes.caffeine.cache.Cache;
55
import com.github.benmanes.caffeine.cache.LoadingCache;
6+
import com.github.benmanes.caffeine.cache.Policy;
67
import com.github.benmanes.caffeine.cache.stats.CacheStats;
78
import io.prometheus.metrics.model.registry.MultiCollector;
89
import io.prometheus.metrics.model.snapshots.CounterSnapshot;
@@ -14,8 +15,10 @@
1415
import java.util.Collections;
1516
import java.util.List;
1617
import java.util.Map;
18+
import java.util.Optional;
1719
import java.util.concurrent.ConcurrentHashMap;
1820
import java.util.concurrent.ConcurrentMap;
21+
import java.util.stream.Collectors;
1922

2023
/**
2124
* Collect metrics from Caffeine's com.github.benmanes.caffeine.cache.Cache.
@@ -25,7 +28,7 @@
2528
* <pre>{@code
2629
* // Note that `recordStats()` is required to gather non-zero statistics
2730
* Cache<String, String> cache = Caffeine.newBuilder().recordStats().build();
28-
* CacheMetricsCollector cacheMetrics = new CacheMetricsCollector();
31+
* CacheMetricsCollector cacheMetrics = CacheMetricsCollector.builder().build();
2932
* PrometheusRegistry.defaultRegistry.register(cacheMetrics);
3033
* cacheMetrics.addCache("mycache", cache);
3134
*
@@ -63,6 +66,7 @@ public class CacheMetricsCollector implements MultiCollector {
6366
private static final String METRIC_NAME_CACHE_LOAD_FAILURE = "caffeine_cache_load_failure";
6467
private static final String METRIC_NAME_CACHE_LOADS = "caffeine_cache_loads";
6568
private static final String METRIC_NAME_CACHE_ESTIMATED_SIZE = "caffeine_cache_estimated_size";
69+
private static final String METRIC_NAME_CACHE_WEIGHTED_SIZE = "caffeine_cache_weighted_size";
6670
private static final String METRIC_NAME_CACHE_LOAD_DURATION_SECONDS =
6771
"caffeine_cache_load_duration_seconds";
6872

@@ -77,9 +81,38 @@ public class CacheMetricsCollector implements MultiCollector {
7781
METRIC_NAME_CACHE_LOAD_FAILURE,
7882
METRIC_NAME_CACHE_LOADS,
7983
METRIC_NAME_CACHE_ESTIMATED_SIZE,
84+
METRIC_NAME_CACHE_WEIGHTED_SIZE,
8085
METRIC_NAME_CACHE_LOAD_DURATION_SECONDS));
8186

8287
protected final ConcurrentMap<String, Cache<?, ?>> children = new ConcurrentHashMap<>();
88+
private final boolean collectEvictionWeightAsCounter;
89+
private final boolean collectWeightedSize;
90+
91+
/**
92+
* Instantiates a {@link CacheMetricsCollector}, with the legacy parameters.
93+
*
94+
* <p>The use of this constructor is discouraged, in favor of a Builder pattern {@link #builder()}
95+
*
96+
* <p>Note that the {@link #builder()} API has different default values than this deprecated
97+
* constructor.
98+
*/
99+
@Deprecated
100+
public CacheMetricsCollector() {
101+
this(false, false);
102+
}
103+
104+
/**
105+
* Instantiate a {@link CacheMetricsCollector}
106+
*
107+
* @param collectEvictionWeightAsCounter If true, {@code caffeine_cache_eviction_weight} will be
108+
* observed as an incrementing counter instead of a gauge.
109+
* @param collectWeightedSize If true, {@code caffeine_cache_weighted_size} will be observed.
110+
*/
111+
protected CacheMetricsCollector(
112+
boolean collectEvictionWeightAsCounter, boolean collectWeightedSize) {
113+
this.collectEvictionWeightAsCounter = collectEvictionWeightAsCounter;
114+
this.collectWeightedSize = collectWeightedSize;
115+
}
83116

84117
/**
85118
* Add or replace the cache with the given name.
@@ -146,10 +179,14 @@ public MetricSnapshots collect() {
146179
.name(METRIC_NAME_CACHE_EVICTION)
147180
.help("Cache eviction totals, doesn't include manually removed entries");
148181

149-
final GaugeSnapshot.Builder cacheEvictionWeight =
182+
final CounterSnapshot.Builder cacheEvictionWeight =
183+
CounterSnapshot.builder()
184+
.name(METRIC_NAME_CACHE_EVICTION_WEIGHT)
185+
.help("Weight of evicted cache entries, doesn't include manually removed entries");
186+
final GaugeSnapshot.Builder cacheEvictionWeightLegacyGauge =
150187
GaugeSnapshot.builder()
151188
.name(METRIC_NAME_CACHE_EVICTION_WEIGHT)
152-
.help("Cache eviction weight");
189+
.help("Weight of evicted cache entries, doesn't include manually removed entries");
153190

154191
final CounterSnapshot.Builder cacheLoadFailure =
155192
CounterSnapshot.builder().name(METRIC_NAME_CACHE_LOAD_FAILURE).help("Cache load failures");
@@ -162,6 +199,11 @@ public MetricSnapshots collect() {
162199
final GaugeSnapshot.Builder cacheSize =
163200
GaugeSnapshot.builder().name(METRIC_NAME_CACHE_ESTIMATED_SIZE).help("Estimated cache size");
164201

202+
final GaugeSnapshot.Builder cacheWeightedSize =
203+
GaugeSnapshot.builder()
204+
.name(METRIC_NAME_CACHE_WEIGHTED_SIZE)
205+
.help("Approximate accumulated weight of cache entries");
206+
165207
final SummarySnapshot.Builder cacheLoadSummary =
166208
SummarySnapshot.builder()
167209
.name(METRIC_NAME_CACHE_LOAD_DURATION_SECONDS)
@@ -175,6 +217,11 @@ public MetricSnapshots collect() {
175217

176218
try {
177219
cacheEvictionWeight.dataPoint(
220+
CounterSnapshot.CounterDataPointSnapshot.builder()
221+
.labels(labels)
222+
.value(stats.evictionWeight())
223+
.build());
224+
cacheEvictionWeightLegacyGauge.dataPoint(
178225
GaugeSnapshot.GaugeDataPointSnapshot.builder()
179226
.labels(labels)
180227
.value(stats.evictionWeight())
@@ -183,6 +230,17 @@ public MetricSnapshots collect() {
183230
// EvictionWeight metric is unavailable, newer version of Caffeine is needed.
184231
}
185232

233+
if (collectWeightedSize) {
234+
final Optional<? extends Policy.Eviction<?, ?>> eviction = c.getValue().policy().eviction();
235+
if (eviction.isPresent() && eviction.get().weightedSize().isPresent()) {
236+
cacheWeightedSize.dataPoint(
237+
GaugeSnapshot.GaugeDataPointSnapshot.builder()
238+
.labels(labels)
239+
.value(eviction.get().weightedSize().getAsLong())
240+
.build());
241+
}
242+
}
243+
186244
cacheHitTotal.dataPoint(
187245
CounterSnapshot.CounterDataPointSnapshot.builder()
188246
.labels(labels)
@@ -235,12 +293,19 @@ public MetricSnapshots collect() {
235293
}
236294
}
237295

296+
if (collectWeightedSize) {
297+
metricSnapshotsBuilder.metricSnapshot(cacheWeightedSize.build());
298+
}
299+
238300
return metricSnapshotsBuilder
239301
.metricSnapshot(cacheHitTotal.build())
240302
.metricSnapshot(cacheMissTotal.build())
241303
.metricSnapshot(cacheRequestsTotal.build())
242304
.metricSnapshot(cacheEvictionTotal.build())
243-
.metricSnapshot(cacheEvictionWeight.build())
305+
.metricSnapshot(
306+
collectEvictionWeightAsCounter
307+
? cacheEvictionWeight.build()
308+
: cacheEvictionWeightLegacyGauge.build())
244309
.metricSnapshot(cacheLoadFailure.build())
245310
.metricSnapshot(cacheLoadTotal.build())
246311
.metricSnapshot(cacheSize.build())
@@ -250,6 +315,35 @@ public MetricSnapshots collect() {
250315

251316
@Override
252317
public List<String> getPrometheusNames() {
318+
if (!collectWeightedSize) {
319+
return ALL_METRIC_NAMES.stream()
320+
.filter(s -> !METRIC_NAME_CACHE_WEIGHTED_SIZE.equals(s))
321+
.collect(Collectors.toList());
322+
}
253323
return ALL_METRIC_NAMES;
254324
}
325+
326+
public static Builder builder() {
327+
return new Builder();
328+
}
329+
330+
public static class Builder {
331+
332+
private boolean collectEvictionWeightAsCounter = true;
333+
private boolean collectWeightedSize = true;
334+
335+
public Builder collectEvictionWeightAsCounter(boolean collectEvictionWeightAsCounter) {
336+
this.collectEvictionWeightAsCounter = collectEvictionWeightAsCounter;
337+
return this;
338+
}
339+
340+
public Builder collectWeightedSize(boolean collectWeightedSize) {
341+
this.collectWeightedSize = collectWeightedSize;
342+
return this;
343+
}
344+
345+
public CacheMetricsCollector build() {
346+
return new CacheMetricsCollector(collectEvictionWeightAsCounter, collectWeightedSize);
347+
}
348+
}
255349
}

‎prometheus-metrics-instrumentation-caffeine/src/test/java/io/prometheus/metrics/instrumentation/caffeine/CacheMetricsCollectorTest.java

+149-13
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,7 @@
1313
import io.prometheus.metrics.model.registry.PrometheusRegistry;
1414
import io.prometheus.metrics.model.snapshots.CounterSnapshot;
1515
import io.prometheus.metrics.model.snapshots.DataPointSnapshot;
16+
import io.prometheus.metrics.model.snapshots.GaugeSnapshot;
1617
import io.prometheus.metrics.model.snapshots.Labels;
1718
import io.prometheus.metrics.model.snapshots.MetricSnapshots;
1819
import io.prometheus.metrics.model.snapshots.SummarySnapshot;
@@ -22,17 +23,112 @@
2223
import java.nio.charset.StandardCharsets;
2324
import java.util.List;
2425
import org.junit.jupiter.api.Test;
26+
import org.junit.jupiter.params.ParameterizedTest;
27+
import org.junit.jupiter.params.provider.EnumSource;
2528

2629
@SuppressWarnings("CheckReturnValue")
2730
class CacheMetricsCollectorTest {
31+
// This enum was added to simplify test parametrization on argument options.
32+
public enum Options {
33+
LEGACY(false, false),
34+
COLLECT_EVICTION_WEIGHT_AS_COUNTER(true, false),
35+
COLLECT_WEIGHTED_SIZE(false, true),
36+
BUILDER_DEFAULT(true, true);
37+
38+
private final boolean collectEvictionWeightAsCounter;
39+
private final boolean collectWeightedSize;
40+
41+
Options(boolean collectEvictionWeightAsCounter, boolean collectWeightedSize) {
42+
this.collectEvictionWeightAsCounter = collectEvictionWeightAsCounter;
43+
this.collectWeightedSize = collectWeightedSize;
44+
}
45+
}
2846

29-
@Test
30-
public void cacheExposesMetricsForHitMissAndEviction() {
47+
@ParameterizedTest
48+
@EnumSource
49+
public void cacheExposesMetricsForHitMissAndEviction(Options options) {
3150
// Run cleanup in same thread, to remove async behavior with evictions
3251
final Cache<String, String> cache =
3352
Caffeine.newBuilder().maximumSize(2).recordStats().executor(Runnable::run).build();
3453

35-
final CacheMetricsCollector collector = new CacheMetricsCollector();
54+
final CacheMetricsCollector collector =
55+
CacheMetricsCollector.builder()
56+
.collectEvictionWeightAsCounter(options.collectEvictionWeightAsCounter)
57+
.collectWeightedSize(options.collectWeightedSize)
58+
.build();
59+
collector.addCache("users", cache);
60+
61+
final PrometheusRegistry registry = new PrometheusRegistry();
62+
registry.register(collector);
63+
64+
cache.getIfPresent("user1");
65+
cache.getIfPresent("user1");
66+
cache.put("user1", "First User");
67+
cache.getIfPresent("user1");
68+
69+
// Add to cache to trigger eviction.
70+
cache.put("user2", "Second User");
71+
cache.put("user3", "Third User");
72+
cache.put("user4", "Fourth User");
73+
74+
assertCounterMetric(registry, "caffeine_cache_hit", "users", 1.0);
75+
assertCounterMetric(registry, "caffeine_cache_miss", "users", 2.0);
76+
assertCounterMetric(registry, "caffeine_cache_requests", "users", 3.0);
77+
assertCounterMetric(registry, "caffeine_cache_eviction", "users", 2.0);
78+
String openMetricEvictionWeightExpectedText;
79+
if (options.collectEvictionWeightAsCounter) {
80+
assertCounterMetric(registry, "caffeine_cache_eviction_weight", "users", 2.0);
81+
openMetricEvictionWeightExpectedText =
82+
"# TYPE caffeine_cache_eviction_weight counter\n"
83+
+ "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
84+
+ "caffeine_cache_eviction_weight_total{cache=\"users\"} 2.0\n";
85+
} else {
86+
assertGaugeMetric(registry, "caffeine_cache_eviction_weight", "users", 2.0);
87+
openMetricEvictionWeightExpectedText =
88+
"# TYPE caffeine_cache_eviction_weight gauge\n"
89+
+ "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
90+
+ "caffeine_cache_eviction_weight{cache=\"users\"} 2.0\n";
91+
}
92+
93+
final String expected =
94+
"# TYPE caffeine_cache_estimated_size gauge\n"
95+
+ "# HELP caffeine_cache_estimated_size Estimated cache size\n"
96+
+ "caffeine_cache_estimated_size{cache=\"users\"} 2.0\n"
97+
+ "# TYPE caffeine_cache_eviction counter\n"
98+
+ "# HELP caffeine_cache_eviction Cache eviction totals, doesn't include manually removed entries\n"
99+
+ "caffeine_cache_eviction_total{cache=\"users\"} 2.0\n"
100+
+ openMetricEvictionWeightExpectedText
101+
+ "# TYPE caffeine_cache_hit counter\n"
102+
+ "# HELP caffeine_cache_hit Cache hit totals\n"
103+
+ "caffeine_cache_hit_total{cache=\"users\"} 1.0\n"
104+
+ "# TYPE caffeine_cache_miss counter\n"
105+
+ "# HELP caffeine_cache_miss Cache miss totals\n"
106+
+ "caffeine_cache_miss_total{cache=\"users\"} 2.0\n"
107+
+ "# TYPE caffeine_cache_requests counter\n"
108+
+ "# HELP caffeine_cache_requests Cache request totals, hits + misses\n"
109+
+ "caffeine_cache_requests_total{cache=\"users\"} 3.0\n"
110+
+ "# EOF\n";
111+
112+
assertThat(convertToOpenMetricsFormat(registry)).isEqualTo(expected);
113+
}
114+
115+
@ParameterizedTest
116+
@EnumSource
117+
public void weightedCacheExposesMetricsForHitMissAndEvictionWeightedSize(Options options) {
118+
// Run cleanup in same thread, to remove async behavior with evictions
119+
final Cache<String, String> cache =
120+
Caffeine.newBuilder()
121+
.weigher((String k, String v) -> k.length() + v.length())
122+
.maximumWeight(35)
123+
.recordStats()
124+
.executor(Runnable::run)
125+
.build();
126+
127+
final CacheMetricsCollector collector =
128+
CacheMetricsCollector.builder()
129+
.collectEvictionWeightAsCounter(options.collectEvictionWeightAsCounter)
130+
.collectWeightedSize(options.collectWeightedSize)
131+
.build();
36132
collector.addCache("users", cache);
37133

38134
final PrometheusRegistry registry = new PrometheusRegistry();
@@ -52,6 +148,29 @@ public void cacheExposesMetricsForHitMissAndEviction() {
52148
assertCounterMetric(registry, "caffeine_cache_miss", "users", 2.0);
53149
assertCounterMetric(registry, "caffeine_cache_requests", "users", 3.0);
54150
assertCounterMetric(registry, "caffeine_cache_eviction", "users", 2.0);
151+
String openMetricEvictionWeightExpectedText;
152+
if (options.collectEvictionWeightAsCounter) {
153+
assertCounterMetric(registry, "caffeine_cache_eviction_weight", "users", 31.0);
154+
openMetricEvictionWeightExpectedText =
155+
"# TYPE caffeine_cache_eviction_weight counter\n"
156+
+ "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
157+
+ "caffeine_cache_eviction_weight_total{cache=\"users\"} 31.0\n";
158+
} else {
159+
assertGaugeMetric(registry, "caffeine_cache_eviction_weight", "users", 31.0);
160+
openMetricEvictionWeightExpectedText =
161+
"# TYPE caffeine_cache_eviction_weight gauge\n"
162+
+ "# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries\n"
163+
+ "caffeine_cache_eviction_weight{cache=\"users\"} 31.0\n";
164+
}
165+
String openMetricWeightedSizeExpectedText;
166+
if (options.collectWeightedSize) {
167+
openMetricWeightedSizeExpectedText =
168+
"# TYPE caffeine_cache_weighted_size gauge\n"
169+
+ "# HELP caffeine_cache_weighted_size Approximate accumulated weight of cache entries\n"
170+
+ "caffeine_cache_weighted_size{cache=\"users\"} 31.0\n";
171+
} else {
172+
openMetricWeightedSizeExpectedText = "";
173+
}
55174

56175
final String expected =
57176
"# TYPE caffeine_cache_estimated_size gauge\n"
@@ -60,9 +179,7 @@ public void cacheExposesMetricsForHitMissAndEviction() {
60179
+ "# TYPE caffeine_cache_eviction counter\n"
61180
+ "# HELP caffeine_cache_eviction Cache eviction totals, doesn't include manually removed entries\n"
62181
+ "caffeine_cache_eviction_total{cache=\"users\"} 2.0\n"
63-
+ "# TYPE caffeine_cache_eviction_weight gauge\n"
64-
+ "# HELP caffeine_cache_eviction_weight Cache eviction weight\n"
65-
+ "caffeine_cache_eviction_weight{cache=\"users\"} 2.0\n"
182+
+ openMetricEvictionWeightExpectedText
66183
+ "# TYPE caffeine_cache_hit counter\n"
67184
+ "# HELP caffeine_cache_hit Cache hit totals\n"
68185
+ "caffeine_cache_hit_total{cache=\"users\"} 1.0\n"
@@ -72,6 +189,7 @@ public void cacheExposesMetricsForHitMissAndEviction() {
72189
+ "# TYPE caffeine_cache_requests counter\n"
73190
+ "# HELP caffeine_cache_requests Cache request totals, hits + misses\n"
74191
+ "caffeine_cache_requests_total{cache=\"users\"} 3.0\n"
192+
+ openMetricWeightedSizeExpectedText
75193
+ "# EOF\n";
76194

77195
assertThat(convertToOpenMetricsFormat(registry)).isEqualTo(expected);
@@ -87,7 +205,7 @@ public void loadingCacheExposesMetricsForLoadsAndExceptions() throws Exception {
87205
.thenReturn("Third User");
88206

89207
final LoadingCache<String, String> cache = Caffeine.newBuilder().recordStats().build(loader);
90-
final CacheMetricsCollector collector = new CacheMetricsCollector();
208+
final CacheMetricsCollector collector = CacheMetricsCollector.builder().build();
91209

92210
collector.addCache("loadingusers", cache);
93211

@@ -117,9 +235,14 @@ public void loadingCacheExposesMetricsForLoadsAndExceptions() throws Exception {
117235
assertThat(loadDuration.getSum()).isGreaterThan(0);
118236
}
119237

120-
@Test
121-
public void getPrometheusNamesHasSameSizeAsMetricSizeWhenScraping() {
122-
final CacheMetricsCollector collector = new CacheMetricsCollector();
238+
@ParameterizedTest
239+
@EnumSource
240+
public void getPrometheusNamesHasSameSizeAsMetricSizeWhenScraping(Options options) {
241+
final CacheMetricsCollector collector =
242+
CacheMetricsCollector.builder()
243+
.collectEvictionWeightAsCounter(options.collectEvictionWeightAsCounter)
244+
.collectWeightedSize(options.collectWeightedSize)
245+
.build();
123246

124247
final PrometheusRegistry registry = new PrometheusRegistry();
125248
registry.register(collector);
@@ -130,9 +253,14 @@ public void getPrometheusNamesHasSameSizeAsMetricSizeWhenScraping() {
130253
assertThat(prometheusNames).hasSize(metricSnapshots.size());
131254
}
132255

133-
@Test
134-
public void collectedMetricNamesAreKnownPrometheusNames() {
135-
final CacheMetricsCollector collector = new CacheMetricsCollector();
256+
@ParameterizedTest
257+
@EnumSource
258+
public void collectedMetricNamesAreKnownPrometheusNames(Options options) {
259+
final CacheMetricsCollector collector =
260+
CacheMetricsCollector.builder()
261+
.collectEvictionWeightAsCounter(options.collectEvictionWeightAsCounter)
262+
.collectWeightedSize(options.collectWeightedSize)
263+
.build();
136264

137265
final PrometheusRegistry registry = new PrometheusRegistry();
138266
registry.register(collector);
@@ -153,6 +281,14 @@ private void assertCounterMetric(
153281
assertThat(dataPointSnapshot.getValue()).isEqualTo(value);
154282
}
155283

284+
private void assertGaugeMetric(
285+
PrometheusRegistry registry, String name, String cacheName, double value) {
286+
final GaugeSnapshot.GaugeDataPointSnapshot dataPointSnapshot =
287+
(GaugeSnapshot.GaugeDataPointSnapshot) getDataPointSnapshot(registry, name, cacheName);
288+
289+
assertThat(dataPointSnapshot.getValue()).isEqualTo(value);
290+
}
291+
156292
private DataPointSnapshot getDataPointSnapshot(
157293
PrometheusRegistry registry, String name, String cacheName) {
158294
final Labels labels = Labels.of(new String[] {"cache"}, new String[] {cacheName});

0 commit comments

Comments
 (0)
Please sign in to comment.