Document Caffeine cache metrics

Closes #42705

Signed-off-by: Pedro Ruivo <1492066+pruivo@users.noreply.github.com>
Co-authored-by: Pedro Ruivo <1492066+pruivo@users.noreply.github.com>

docs/guides/observability/grafana-dashboards.adoc

@@ -73,6 +73,28 @@ image::observability/keycloak-capacity-planning-dashboard.png[Capacity planning
 . Pick your Prometheus datasource.
 . Click *Import*.
 
+[TIP]
+====
+The Grafana dashboards have labels inserted by Kubernetes.
+It is possible to use the dashboards with bare-metal deployments by adding the missing labels in the Prometheus configuration file, as shown below.
+
+.Prometheus Scrape Configuration
+[source,yaml]
+----
+scrape_configs:
+  - job_name: "Keycloak"
+    static_configs:
+      - targets: ["localhost:9000", "localhost:9001", "localhost:9002"]
+        labels:
+          namespace: 'keycloak'
+          container: 'keycloak'
+          job: 'keycloak/keycloak-metrics'
+    relabel_configs:
+      - source_labels: [__address__]
+        target_label: pod
+----
+====
+
 == Export a dashboard
 
 Exporting a dashboard to JSON format may be useful. For example, you may want to suggest a change in our dashboard repository.

docs/guides/observability/metrics-for-troubleshooting-cache.adoc

@@ -0,0 +1,75 @@
+<#import "/templates/guide.adoc" as tmpl>
+<#import "/templates/links.adoc" as links>
+
+<@tmpl.guide
+title="Local caching metrics"
+summary="Use metrics to monitor health for local caching."
+tileVisible="false">
+
+====
+*Global tags*
+
+`cache=<name>`:: The cache name.
+====
+
+== Size
+
+Monitor the number of entries in your local cache.
+
+|===
+|Metric |Description
+
+m| cache_size
+| The number of cached entries.
+
+|===
+
+== Data Access
+
+The following metrics monitor the cache accesses, such as lookup and evictions.
+
+=== Reads
+
+====
+*Tags*
+
+`result=hit|miss`:: The result of the read/lookup operation.
+If the value is `hit`, the entry was found in the cache.
+====
+
+The read requests can be monitored using a single metric.
+
+|===
+|Metric |Description
+
+m| cache_gets_total
+| The total number of cache lookups.
+
+|===
+
+====
+*Hit Ratio for read operation*
+
+An expression can be used to compute the hit ratio for a cache in systems such as Prometheus.
+For example, the hit ratio for read operations can be expressed as:
+
+----
+cache_gets_total{result="hit"} / cache_gets_total
+
+----
+
+====
+
+=== Evictions
+
+When a cache is limited, eviction is the process of removing the least used entries to make space available for new entries to be cached.
+
+|===
+|Metric |Description
+
+m|cache_evictions_count
+| The number of times the cache was evicted.
+
+|===
+
+</@tmpl.guide>

docs/guides/observability/metrics-for-troubleshooting.adoc

@@ -50,6 +50,7 @@ Grafana dashboards for the metrics below can be found in <@links.observability i
 * <@links.observability id="metrics-for-troubleshooting-jvm"/>
 * <@links.observability id="metrics-for-troubleshooting-database"/>
 * <@links.observability id="metrics-for-troubleshooting-http"/>
+* <@links.observability id="metrics-for-troubleshooting-cache"/>
 * <@links.ha id="single-cluster-introduction" /> metrics
 ** <@links.observability id="metrics-for-troubleshooting-clustering-and-network"/>
 ** <@links.observability id="metrics-for-troubleshooting-embedded-caches"/>

docs/guides/observability/pinned-guides

@@ -7,6 +7,7 @@ metrics-for-troubleshooting-keycloak
 metrics-for-troubleshooting-jvm
 metrics-for-troubleshooting-database
 metrics-for-troubleshooting-http
+metrics-for-troubleshooting-cache
 metrics-for-troubleshooting-clustering-and-network
 metrics-for-troubleshooting-embedded-caches
 metrics-for-troubleshooting-embedded-caches-multi-cluster

quarkus/tests/integration/src/test/java/org/keycloak/it/cli/dist/MetricsDistTest.java

@@ -109,6 +109,11 @@ public class MetricsDistTest {
                 .body(containsString("TYPE vendor_transactions_rollback_times_seconds summary"))
                 .body(containsString("TYPE vendor_transactions_commit_times_seconds summary"))
 
+                // Caffeine Metrics
+                .body(containsString("TYPE cache_gets counter"))
+                .body(containsString("TYPE cache_size gauge"))
+                .body(containsString("TYPE cache_evictions summary"))
+
                 // Test histograms are not available without explicitly enabling the option
                 .body(not(containsString("vendor_statistics_miss_times_seconds_bucket")));
 

services/src/main/java/org/keycloak/device/DeviceRepresentationProviderFactoryImpl.java

@@ -4,6 +4,8 @@ import java.util.List;
 
 import com.github.benmanes.caffeine.cache.Caffeine;
 import com.github.benmanes.caffeine.cache.LoadingCache;
+import io.micrometer.core.instrument.Metrics;
+import io.micrometer.core.instrument.binder.cache.CaffeineStatsCounter;
 import org.keycloak.Config;
 import org.keycloak.models.KeycloakSession;
 import org.keycloak.provider.ProviderConfigProperty;
@@ -30,10 +32,13 @@ public class DeviceRepresentationProviderFactoryImpl implements DeviceRepresenta
 
     @Override
     public void init(Config.Scope config) {
+        CaffeineStatsCounter metrics = new CaffeineStatsCounter(Metrics.globalRegistry, "userAgent");
         cache = Caffeine.newBuilder()
                 .maximumSize(config.getInt(CACHE_SIZE, DEFAULT_CACHE_SIZE))
+                .recordStats(() -> metrics)
                 .softValues()
                 .build(UA_PARSER::parse);
+        metrics.registerSizeMetric(cache);
     }
 
     @Override