From 3ceb37aa33bd217a144f5aca1dd8b8cba7b91781 Mon Sep 17 00:00:00 2001 From: Jean Hominal Date: Sun, 19 Jan 2025 15:23:58 +0100 Subject: [PATCH 1/2] Add documentation pages for Caffeine and Guava cache instrumentation libraries Signed-off-by: Jean Hominal --- docs/content/instrumentation/caffeine.md | 101 +++++++++++++++++++++++ docs/content/instrumentation/guava.md | 85 +++++++++++++++++++ 2 files changed, 186 insertions(+) create mode 100644 docs/content/instrumentation/caffeine.md create mode 100644 docs/content/instrumentation/guava.md diff --git a/docs/content/instrumentation/caffeine.md b/docs/content/instrumentation/caffeine.md new file mode 100644 index 000000000..0d2e41d86 --- /dev/null +++ b/docs/content/instrumentation/caffeine.md @@ -0,0 +1,101 @@ +--- +title: Caffeine Cache +weight: 1 +--- + +The Caffeine instrumentation module, added in version 1.3.2, translates observability data +provided by caffeine `Cache` objects into prometheus metrics. + +{{< tabs "uniqueid" >}} +{{< tab "Gradle" >}} +``` +implementation 'io.prometheus:prometheus-metrics-instrumentation-caffeine:1.3.2' +``` +{{< /tab >}} +{{< tab "Maven" >}} +```xml + + io.prometheus + prometheus-metrics-instrumentation-caffeine + 1.3.2 + +``` +{{< /tab >}} +{{< /tabs >}} + +In order to collect metrics: + + * A single `CacheMetricsCollector` instance must be registered with the registry; + * Multiple `CacheMetricsCollector` instances cannot be registered with the same registry; + * The `Cache` object must be instantiated with the `recordStats()` option, and then added to the + `CacheMetricsCollector` instance with a unique name, which will be used as the value of the + `cache` label on the exported metrics; + * If the `recordStats` option is not set, most metrics will only return zero values; + +```java +var cache = Caffeine.newBuilder().recordStats().build(); +var cacheMetrics = new CacheMetricsCollector(); +PrometheusRegistry.defaultRegistry.register(cacheMetrics); +cacheMetrics.addCache("mycache", cache); +``` + +All example metrics on this page will use the `mycache` label value. + +Generic Cache Metrics +--------------------- + +For all cache instances, the following metrics will be available: + +``` +# TYPE caffeine_cache_hit counter +# HELP caffeine_cache_hit Cache hit totals +caffeine_cache_hit_total{cache="mycache"} 10.0 +# TYPE caffeine_cache_miss counter +# HELP caffeine_cache_miss Cache miss totals +caffeine_cache_miss_total{cache="mycache"} 3.0 +# TYPE caffeine_cache_requests counter +# HELP caffeine_cache_requests Cache request totals, hits + misses +caffeine_cache_requests_total{cache="mycache"} 13.0 +# TYPE caffeine_cache_eviction counter +# HELP caffeine_cache_eviction Cache eviction totals, doesn't include manually removed entries +caffeine_cache_eviction_total{cache="mycache"} 1.0 +# TYPE caffeine_cache_estimated_size +# HELP caffeine_cache_estimated_size Estimated cache size +caffeine_cache_estimated_size{cache="mycache"} 5.0 +``` + +Loading Cache Metrics +--------------------- + +If the cache is an instance of `LoadingCache`, i.e. it is built with a `loader` function that is +managed by the cache library, then metrics for observing load time and load failures become +available: + +``` +# TYPE caffeine_cache_load_failure counter +# HELP caffeine_cache_load_failure Cache load failures +caffeine_cache_load_failure_total{cache="mycache"} 10.0 +# TYPE caffeine_cache_loads counter +# HELP caffeine_cache_loads Cache loads: both success and failures +caffeine_cache_loads_total{cache="mycache"} 3.0 +# TYPE caffeine_cache_load_duration_seconds summary +# HELP caffeine_cache_load_duration_seconds Cache load duration: both success and failures +caffeine_cache_load_duration_seconds_count{cache="mycache"} 7.0 +caffeine_cache_load_duration_seconds_sum{cache="mycache"} 0.0034 +``` + +Weighted Cache Metrics +---------------------- + +If the cache is weighted, i.e. it defines a `weigher` function, then the following metrics +become interesting: + +``` +# TYPE caffeine_cache_eviction_weight gauge +# HELP caffeine_cache_eviction_weight Cache eviction weight +caffeine_cache_eviction_weight{cache="mycache"} 5.0 +``` + +Note: while `caffeine_cache_eviction_weight` is exported as a `gauge` metric, it represents +a monotonicaly increasing value. Also, in the case where the cache does not define a `weigher` +function, it will return the same values as `caffeine_cache_eviction_total`. \ No newline at end of file diff --git a/docs/content/instrumentation/guava.md b/docs/content/instrumentation/guava.md new file mode 100644 index 000000000..33cadae97 --- /dev/null +++ b/docs/content/instrumentation/guava.md @@ -0,0 +1,85 @@ +--- +title: Guava Cache +weight: 1 +--- + +The Guava instrumentation module, added in version 1.3.2, translates observability data +provided by Guava `Cache` objects into prometheus metrics. + +{{< tabs "uniqueid" >}} +{{< tab "Gradle" >}} +``` +implementation 'io.prometheus:prometheus-metrics-instrumentation-guava:1.3.2' +``` +{{< /tab >}} +{{< tab "Maven" >}} +```xml + + io.prometheus + prometheus-metrics-instrumentation-guava + 1.3.2 + +``` +{{< /tab >}} +{{< /tabs >}} + +In order to collect metrics: + +* A single `CacheMetricsCollector` instance must be registered with the registry; + * Multiple `CacheMetricsCollector` instances cannot be registered with the same registry; +* The `Cache` object must be instantiated with the `recordStats()` option, and then added to the + `CacheMetricsCollector` instance with a unique name, which will be used as the value of the + `cache` label on the exported metrics; + * If the `recordStats` option is not set, most metrics will only return zero values; + +```java +var cache = CacheBuilder.newBuilder().recordStats().build(); +var cacheMetrics = new CacheMetricsCollector(); +PrometheusRegistry.defaultRegistry.register(cacheMetrics); +cacheMetrics.addCache("mycache", cache); +``` + +All example metrics on this page will use the `mycache` label value. + +Generic Cache Metrics +--------------------- + +For all cache instances, the following metrics will be available: + +``` +# TYPE guava_cache_hit counter +# HELP guava_cache_hit Cache hit totals +guava_cache_hit_total{cache="mycache"} 10.0 +# TYPE guava_cache_miss counter +# HELP guava_cache_miss Cache miss totals +guava_cache_miss_total{cache="mycache"} 3.0 +# TYPE guava_cache_requests counter +# HELP guava_cache_requests Cache request totals +guava_cache_requests_total{cache="mycache"} 13.0 +# TYPE guava_cache_eviction counter +# HELP guava_cache_eviction Cache eviction totals, doesn't include manually removed entries +guava_cache_eviction_total{cache="mycache"} 1.0 +# TYPE guava_cache_size +# HELP guava_cache_size Cache size +guava_cache_size{cache="mycache"} 5.0 +``` + +Loading Cache Metrics +--------------------- + +If the cache is an instance of `LoadingCache`, i.e. it is built with a `loader` function that is +managed by the cache library, then metrics for observing load time and load failures become +available: + +``` +# TYPE guava_cache_load_failure counter +# HELP guava_cache_load_failure Cache load failures +guava_cache_load_failure_total{cache="mycache"} 10.0 +# TYPE guava_cache_loads counter +# HELP guava_cache_loads Cache loads: both success and failures +guava_cache_loads_total{cache="mycache"} 3.0 +# TYPE guava_cache_load_duration_seconds summary +# HELP guava_cache_load_duration_seconds Cache load duration: both success and failures +guava_cache_load_duration_seconds_count{cache="mycache"} 7.0 +guava_cache_load_duration_seconds_sum{cache="mycache"} 0.0034 +``` From 2e6318189b7cb6b16a14705a6f97a421bc6f2565 Mon Sep 17 00:00:00 2001 From: Jean Hominal Date: Mon, 20 Jan 2025 21:39:56 +0100 Subject: [PATCH 2/2] Update caffeine.md to take in account modifications from #1251 Signed-off-by: Jean Hominal --- docs/content/instrumentation/caffeine.md | 43 +++++++++++++++++++----- 1 file changed, 34 insertions(+), 9 deletions(-) diff --git a/docs/content/instrumentation/caffeine.md b/docs/content/instrumentation/caffeine.md index 0d2e41d86..dde7e561a 100644 --- a/docs/content/instrumentation/caffeine.md +++ b/docs/content/instrumentation/caffeine.md @@ -34,11 +34,18 @@ In order to collect metrics: ```java var cache = Caffeine.newBuilder().recordStats().build(); -var cacheMetrics = new CacheMetricsCollector(); +var cacheMetrics = CacheMetricsCollector.builder().build(); PrometheusRegistry.defaultRegistry.register(cacheMetrics); cacheMetrics.addCache("mycache", cache); ``` +{{< hint type=note >}} + +In version 1.3.5 and older of the caffeine instrumentation library, `CacheMetricsCollector.builder` +does not exist, i.e. a constructor call `new CacheMetricsCollector()` is the only option. + +{{< /hint >}} + All example metrics on this page will use the `mycache` label value. Generic Cache Metrics @@ -87,15 +94,33 @@ caffeine_cache_load_duration_seconds_sum{cache="mycache"} 0.0034 Weighted Cache Metrics ---------------------- -If the cache is weighted, i.e. it defines a `weigher` function, then the following metrics -become interesting: +Two metrics exist for observability specifically of caches that define a `weigher`: ``` -# TYPE caffeine_cache_eviction_weight gauge -# HELP caffeine_cache_eviction_weight Cache eviction weight -caffeine_cache_eviction_weight{cache="mycache"} 5.0 +# TYPE caffeine_cache_eviction_weight counter +# HELP caffeine_cache_eviction_weight Weight of evicted cache entries, doesn't include manually removed entries +caffeine_cache_eviction_weight_total{cache="mycache"} 5.0 +# TYPE caffeine_cache_weighted_size gauge +# HELP caffeine_cache_weighted_size Approximate accumulated weight of cache entries +caffeine_cache_weighted_size{cache="mycache"} 30.0 ``` -Note: while `caffeine_cache_eviction_weight` is exported as a `gauge` metric, it represents -a monotonicaly increasing value. Also, in the case where the cache does not define a `weigher` -function, it will return the same values as `caffeine_cache_eviction_total`. \ No newline at end of file +{{< hint type=note >}} + +`caffeine_cache_weighted_size` is available only if the cache instance defines a `maximumWeight`. + +{{< /hint >}} + +Up to version 1.3.5 and older, the weighted metrics had a different behavior: + + * `caffeine_cache_weighted_size` was not implemented; + * `caffeine_cache_eviction_weight` was exposed as a `gauge`; + +It is possible to restore the behavior of version 1.3.5 and older, by either: + + * Using the deprecated `new CacheMetricsCollector()` constructor; + * Using the flags provided on the `CacheMetricsCollector.Builder` object to opt-out of each of the + elements of the post-1.3.5 behavior: + * `builder.collectWeightedSize(false)` will disable collection of `caffeine_cache_weighted_size`; + * `builder.collectEvictionWeightAsCounter(false)` will expose `caffeine_cache_eviction_weight` as + a `gauge` metric;