Skip to content

Commit f7681a4

Browse files
jhominaljhominal
authored
Add documentation pages for Caffeine and Guava cache instrumentation libraries (#1262)
* Add documentation pages for Caffeine and Guava cache instrumentation libraries Signed-off-by: Jean Hominal <[email protected]> * Update caffeine.md to take in account modifications from #1251 Signed-off-by: Jean Hominal <[email protected]> --------- Signed-off-by: Jean Hominal <[email protected]>
1 parent 0ee705c commit f7681a4

File tree

2 files changed

+211
-0
lines changed

2 files changed

+211
-0
lines changed

‎docs/content/instrumentation/caffeine.md‎

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
---
2+
title: Caffeine Cache
3+
weight: 1
4+
---
5+
6+
The Caffeine instrumentation module, added in version 1.3.2, translates observability data
7+
provided by caffeine `Cache` objects into prometheus metrics.
8+
9+
{{< tabs "uniqueid" >}}
10+
{{< tab "Gradle" >}}
11+
```
12+
implementation 'io.prometheus:prometheus-metrics-instrumentation-caffeine:1.3.2'
13+
```
14+
{{< /tab >}}
15+
{{< tab "Maven" >}}
16+
```xml
17+
<dependency>
18+
<groupId>io.prometheus</groupId>
19+
<artifactId>prometheus-metrics-instrumentation-caffeine</artifactId>
20+
<version>1.3.2</version>
21+
</dependency>
22+
```
23+
{{< /tab >}}
24+
{{< /tabs >}}
25+
26+
In order to collect metrics:
27+
28+
* A single `CacheMetricsCollector` instance must be registered with the registry;
29+
* Multiple `CacheMetricsCollector` instances cannot be registered with the same registry;
30+
* The `Cache` object must be instantiated with the `recordStats()` option, and then added to the
31+
`CacheMetricsCollector` instance with a unique name, which will be used as the value of the
32+
`cache` label on the exported metrics;
33+
* If the `recordStats` option is not set, most metrics will only return zero values;
34+
35+
```java
36+
var cache = Caffeine.newBuilder().recordStats().build();
37+
var cacheMetrics = CacheMetricsCollector.builder().build();
38+
PrometheusRegistry.defaultRegistry.register(cacheMetrics);
39+
cacheMetrics.addCache("mycache", cache);
40+
```
41+
42+
{{< hint type=note >}}
43+
44+
In version 1.3.5 and older of the caffeine instrumentation library, `CacheMetricsCollector.builder`
45+
does not exist, i.e. a constructor call `new CacheMetricsCollector()` is the only option.
46+
47+
{{< /hint >}}
48+
49+
All example metrics on this page will use the `mycache` label value.
50+
51+
Generic Cache Metrics
52+
---------------------
53+
54+
For all cache instances, the following metrics will be available:
55+
56+
```
57+
# TYPE caffeine_cache_hit counter
58+
# HELP caffeine_cache_hit Cache hit totals
59+
caffeine_cache_hit_total{cache="mycache"} 10.0
60+
# TYPE caffeine_cache_miss counter
61+
# HELP caffeine_cache_miss Cache miss totals
62+
caffeine_cache_miss_total{cache="mycache"} 3.0
63+
# TYPE caffeine_cache_requests counter
64+
# HELP caffeine_cache_requests Cache request totals, hits + misses
65+
caffeine_cache_requests_total{cache="mycache"} 13.0
66+
# TYPE caffeine_cache_eviction counter
67+
# HELP caffeine_cache_eviction Cache eviction totals, doesn't include manually removed entries
68+
caffeine_cache_eviction_total{cache="mycache"} 1.0
69+
# TYPE caffeine_cache_estimated_size
70+
# HELP caffeine_cache_estimated_size Estimated cache size
71+
caffeine_cache_estimated_size{cache="mycache"} 5.0
72+
```
73+
74+
Loading Cache Metrics
75+
---------------------
76+
77+
If the cache is an instance of `LoadingCache`, i.e. it is built with a `loader` function that is
78+
managed by the cache library, then metrics for observing load time and load failures become
79+
available:
80+
81+
```
82+
# TYPE caffeine_cache_load_failure counter
83+
# HELP caffeine_cache_load_failure Cache load failures
84+
caffeine_cache_load_failure_total{cache="mycache"} 10.0
85+
# TYPE caffeine_cache_loads counter
86+
# HELP caffeine_cache_loads Cache loads: both success and failures
87+
caffeine_cache_loads_total{cache="mycache"} 3.0
88+
# TYPE caffeine_cache_load_duration_seconds summary
89+
# HELP caffeine_cache_load_duration_seconds Cache load duration: both success and failures
90+
caffeine_cache_load_duration_seconds_count{cache="mycache"} 7.0
91+
caffeine_cache_load_duration_seconds_sum{cache="mycache"} 0.0034
92+
```
93+
94+
Weighted Cache Metrics
95+
----------------------
96+
97+
Two metrics exist for observability specifically of caches that define a `weigher`:
98+
99+
```
100+
# TYPE caffeine_cache_eviction_weight counter
101+
# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries
102+
caffeine_cache_eviction_weight_total{cache="mycache"} 5.0
103+
# TYPE caffeine_cache_weighted_size gauge
104+
# HELP caffeine_cache_weighted_size Approximate accumulated weight of cache entries
105+
caffeine_cache_weighted_size{cache="mycache"} 30.0
106+
```
107+
108+
{{< hint type=note >}}
109+
110+
`caffeine_cache_weighted_size` is available only if the cache instance defines a `maximumWeight`.
111+
112+
{{< /hint >}}
113+
114+
Up to version 1.3.5 and older, the weighted metrics had a different behavior:
115+
116+
* `caffeine_cache_weighted_size` was not implemented;
117+
* `caffeine_cache_eviction_weight` was exposed as a `gauge`;
118+
119+
It is possible to restore the behavior of version 1.3.5 and older, by either:
120+
121+
* Using the deprecated `new CacheMetricsCollector()` constructor;
122+
* Using the flags provided on the `CacheMetricsCollector.Builder` object to opt-out of each of the
123+
elements of the post-1.3.5 behavior:
124+
* `builder.collectWeightedSize(false)` will disable collection of `caffeine_cache_weighted_size`;
125+
* `builder.collectEvictionWeightAsCounter(false)` will expose `caffeine_cache_eviction_weight` as
126+
a `gauge` metric;

‎docs/content/instrumentation/guava.md‎

Lines changed: 85 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
---
2+
title: Guava Cache
3+
weight: 1
4+
---
5+
6+
The Guava instrumentation module, added in version 1.3.2, translates observability data
7+
provided by Guava `Cache` objects into prometheus metrics.
8+
9+
{{< tabs "uniqueid" >}}
10+
{{< tab "Gradle" >}}
11+
```
12+
implementation 'io.prometheus:prometheus-metrics-instrumentation-guava:1.3.2'
13+
```
14+
{{< /tab >}}
15+
{{< tab "Maven" >}}
16+
```xml
17+
<dependency>
18+
<groupId>io.prometheus</groupId>
19+
<artifactId>prometheus-metrics-instrumentation-guava</artifactId>
20+
<version>1.3.2</version>
21+
</dependency>
22+
```
23+
{{< /tab >}}
24+
{{< /tabs >}}
25+
26+
In order to collect metrics:
27+
28+
* A single `CacheMetricsCollector` instance must be registered with the registry;
29+
* Multiple `CacheMetricsCollector` instances cannot be registered with the same registry;
30+
* The `Cache` object must be instantiated with the `recordStats()` option, and then added to the
31+
`CacheMetricsCollector` instance with a unique name, which will be used as the value of the
32+
`cache` label on the exported metrics;
33+
* If the `recordStats` option is not set, most metrics will only return zero values;
34+
35+
```java
36+
var cache = CacheBuilder.newBuilder().recordStats().build();
37+
var cacheMetrics = new CacheMetricsCollector();
38+
PrometheusRegistry.defaultRegistry.register(cacheMetrics);
39+
cacheMetrics.addCache("mycache", cache);
40+
```
41+
42+
All example metrics on this page will use the `mycache` label value.
43+
44+
Generic Cache Metrics
45+
---------------------
46+
47+
For all cache instances, the following metrics will be available:
48+
49+
```
50+
# TYPE guava_cache_hit counter
51+
# HELP guava_cache_hit Cache hit totals
52+
guava_cache_hit_total{cache="mycache"} 10.0
53+
# TYPE guava_cache_miss counter
54+
# HELP guava_cache_miss Cache miss totals
55+
guava_cache_miss_total{cache="mycache"} 3.0
56+
# TYPE guava_cache_requests counter
57+
# HELP guava_cache_requests Cache request totals
58+
guava_cache_requests_total{cache="mycache"} 13.0
59+
# TYPE guava_cache_eviction counter
60+
# HELP guava_cache_eviction Cache eviction totals, doesn't include manually removed entries
61+
guava_cache_eviction_total{cache="mycache"} 1.0
62+
# TYPE guava_cache_size
63+
# HELP guava_cache_size Cache size
64+
guava_cache_size{cache="mycache"} 5.0
65+
```
66+
67+
Loading Cache Metrics
68+
---------------------
69+
70+
If the cache is an instance of `LoadingCache`, i.e. it is built with a `loader` function that is
71+
managed by the cache library, then metrics for observing load time and load failures become
72+
available:
73+
74+
```
75+
# TYPE guava_cache_load_failure counter
76+
# HELP guava_cache_load_failure Cache load failures
77+
guava_cache_load_failure_total{cache="mycache"} 10.0
78+
# TYPE guava_cache_loads counter
79+
# HELP guava_cache_loads Cache loads: both success and failures
80+
guava_cache_loads_total{cache="mycache"} 3.0
81+
# TYPE guava_cache_load_duration_seconds summary
82+
# HELP guava_cache_load_duration_seconds Cache load duration: both success and failures
83+
guava_cache_load_duration_seconds_count{cache="mycache"} 7.0
84+
guava_cache_load_duration_seconds_sum{cache="mycache"} 0.0034
85+
```

0 commit comments

Comments
 (0)