Enable Infinispan metrics automatically if overall metrics are enabled

Closes keycloak#27724

Signed-off-by: Alexander Schwartz <[email protected]>

docs/documentation/upgrading/topics/changes/changes-25_0_0.adoc

@@ -1,3 +1,8 @@
+= Metrics for embedded caches enabled by default
+
+Metrics for the embedded caches are now enabled by default.
+To enable histograms for latencies, set the option `cache-metrics-histograms-enabled` to `true`.
+
 = Nonce claim is only added to the ID token
 
 The nonce claim is now only added to the ID token strictly following the OpenID Connect Core 1.0 specification. As indicated in the specification, the claim is compulsory inside the https://openid.net/specs/openid-connect-core-1_0.html#IDToken[ID token] when the same parameter was sent in the authorization request. The specification also recommends to not add the `nonce` after a https://openid.net/specs/openid-connect-core-1_0.html#RefreshTokenResponse[refresh request]. Previously, the claim was set to all the tokens (Access, Refresh and ID) in all the responses (refresh included).

docs/guides/server/caching.adoc

@@ -258,26 +258,13 @@ For more information about securing cache communication, see the https://infinis
 
 == Exposing metrics from caches
 
-By default, metrics from caches are not automatically exposed when the metrics are enabled.
-For more details about how to enable metrics, see <@links.server id="configuration-metrics"/>.
+Metrics from caches are automatically exposed when the metrics are enabled.
 
-To enable global metrics for all caches within the `cache-container`, you need to change your cache configuration file (e.g.: `conf/cache-ispn.xml`) to enable `statistics` at the `cache-container` level as follows:
+To enable histograms for the cache metrics, set `cache-metrics-histograms-enabled` to `true`.
+While these metrics provide more insights into the latency distribution, collecting them might have a performance impact, so you should be cautious to activate them in an already saturated system.
 
-.enabling metrics for all caches
-[source]
-----
-<cache-container name="keycloak" statistics="true">
-    ...
-</cache-container>
-----
+<@kc.start parameters="--metrics-enabled true --cache-metrics-histograms-enabled true"/>
 
-Similarly, you can enable metrics individually for each cache by enabling `statistics` as follows:
-
-.enabling metrics for a specific cache
-----
-<local-cache name="realms" statistics="true">
-    ...
-</local-cache>
-----
+For more details about how to enable metrics, see <@links.server id="configuration-metrics"/>.
 
 </@tmpl.guide>

quarkus/config-api/src/main/java/org/keycloak/config/CachingOptions.java

@@ -19,6 +19,9 @@ public class CachingOptions {
     public static final String CACHE_REMOTE_USERNAME_PROPERTY = CACHE_REMOTE_PREFIX + "-username";
     public static final String CACHE_REMOTE_PASSWORD_PROPERTY = CACHE_REMOTE_PREFIX + "-password";
 
+    private static final String CACHE_METRICS_PREFIX = "cache-metrics";
+    public static final String CACHE_METRICS_HISTOGRAMS_ENABLED_PROPERTY = CACHE_METRICS_PREFIX + "-histograms-enabled";
+
     public enum Mechanism {
         ispn,
         local
@@ -117,4 +120,9 @@ public enum Stack {
                     CACHE_CONFIG_FILE_PROPERTY, CACHE_REMOTE_HOST_PROPERTY, CACHE_REMOTE_USERNAME_PROPERTY))
             .build();
 
+    public static final Option<Boolean> CACHE_METRICS_HISTOGRAMS_ENABLED = new OptionBuilder<>(CACHE_METRICS_HISTOGRAMS_ENABLED_PROPERTY, Boolean.class)
+            .category(OptionCategory.CACHE)
+            .description("Enable histograms for metrics for the embedded caches.")
+            .build();
+
 }

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/CachingPropertyMappers.java

@@ -61,6 +61,11 @@ public static PropertyMapper<?>[] getClusteringPropertyMappers() {
                         .paramLabel("password")
                         .isMasked(true)
                         .build(),
+
+                fromOption(CachingOptions.CACHE_METRICS_HISTOGRAMS_ENABLED)
+                        .isEnabled(MetricsPropertyMappers::metricsEnabled, MetricsPropertyMappers.METRICS_ENABLED_MSG)
+                        .build(),
+
         };
     }
 

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/configuration/mappers/MetricsPropertyMappers.java

@@ -2,11 +2,14 @@
 
 import org.keycloak.config.MetricsOptions;
 
+import static org.keycloak.quarkus.runtime.configuration.Configuration.isTrue;
 import static org.keycloak.quarkus.runtime.configuration.mappers.PropertyMapper.fromOption;
 
 
 final class MetricsPropertyMappers {
 
+    public static final String METRICS_ENABLED_MSG = "metrics are enabled";
+
     private MetricsPropertyMappers(){}
 
     public static PropertyMapper<?>[] getMetricsPropertyMappers() {
@@ -18,4 +21,7 @@ public static PropertyMapper<?>[] getMetricsPropertyMappers() {
         };
     }
 
+    public static boolean metricsEnabled() {
+        return isTrue(MetricsOptions.METRICS_ENABLED);
+    }
 }

quarkus/runtime/src/main/java/org/keycloak/quarkus/runtime/storage/legacy/infinispan/CacheManagerFactory.java

@@ -50,6 +50,7 @@
 import static org.keycloak.config.CachingOptions.CACHE_EMBEDDED_MTLS_KEYSTORE_PASSWORD_PROPERTY;
 import static org.keycloak.config.CachingOptions.CACHE_EMBEDDED_MTLS_TRUSTSTORE_FILE_PROPERTY;
 import static org.keycloak.config.CachingOptions.CACHE_EMBEDDED_MTLS_TRUSTSTORE_PASSWORD_PROPERTY;
+import static org.keycloak.config.CachingOptions.CACHE_METRICS_HISTOGRAMS_ENABLED_PROPERTY;
 import static org.keycloak.config.CachingOptions.CACHE_REMOTE_HOST_PROPERTY;
 import static org.keycloak.config.CachingOptions.CACHE_REMOTE_PASSWORD_PROPERTY;
 import static org.keycloak.config.CachingOptions.CACHE_REMOTE_PORT_PROPERTY;
@@ -110,6 +111,12 @@ private DefaultCacheManager startCacheManager() {
         if (metricsEnabled) {
             builder.getGlobalConfigurationBuilder().addModule(MicrometerMeterRegisterConfigurationBuilder.class);
             builder.getGlobalConfigurationBuilder().module(MicrometerMeterRegisterConfigurationBuilder.class).meterRegistry(Metrics.globalRegistry);
+            builder.getGlobalConfigurationBuilder().cacheContainer().statistics(true);
+            builder.getGlobalConfigurationBuilder().metrics().namesAsTags(true);
+            if (booleanProperty(CACHE_METRICS_HISTOGRAMS_ENABLED_PROPERTY)) {
+                builder.getGlobalConfigurationBuilder().metrics().histograms(true);
+            }
+            builder.getNamedConfigurationBuilders().forEach((s, configurationBuilder) -> configurationBuilder.statistics().enabled(true));
         }
 
         // For Infinispan 10, we go with the JBoss marshalling.

quarkus/runtime/src/main/resources/cache-ispn.xml

@@ -23,7 +23,6 @@
 
     <cache-container name="keycloak">
         <transport lock-timeout="60000"/>
-        <metrics names-as-tags="true" />
         <local-cache name="realms" simple-cache="true">
             <encoding>
                 <key media-type="application/x-java-object"/>

quarkus/runtime/src/main/resources/cache-local.xml

@@ -22,7 +22,6 @@
         xmlns="urn:infinispan:config:14.0">
 
     <cache-container name="keycloak">
-        <metrics names-as-tags="true" />
         <local-cache name="default">
             <transaction transaction-manager-lookup="org.infinispan.transaction.lookup.JBossStandaloneJTAManagerLookup"/>
         </local-cache>

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

@@ -21,15 +21,11 @@
 import static org.hamcrest.Matchers.containsString;
 import static org.hamcrest.Matchers.not;
 
-import java.nio.file.Paths;
 import java.util.List;
 import java.util.concurrent.CompletableFuture;
 import java.util.concurrent.TimeUnit;
-import java.util.function.Consumer;
 import org.junit.jupiter.api.Test;
-import org.keycloak.it.junit5.extension.BeforeStartDistribution;
 import org.keycloak.it.junit5.extension.DistributionTest;
-import org.keycloak.it.junit5.extension.RawDistOnly;
 import org.keycloak.it.utils.KeycloakDistribution;
 
 import io.quarkus.test.junit.main.Launch;
@@ -52,24 +48,19 @@ void testMetricsEndpoint() {
         when().get("/metrics").then()
                 .statusCode(200)
                 .body(containsString("jvm_gc_"))
-                .body(not(containsString("vendor_cache_manager_keycloak_cache_realms_")));
+                .body(containsString("vendor_statistics_hit_ratio"))
+                .body(not(containsString("vendor_statistics_miss_times_seconds_bucket")));
+
+        when().get("/health").then()
+                .statusCode(404);
     }
 
     @Test
-    @Launch({ "start-dev", "--metrics-enabled=true", "--cache-config-file=cache-local.xml" })
-    @BeforeStartDistribution(EnableCachingStatistics.class)
-    @RawDistOnly(reason = "No support mounting files to containers. Testing raw dist is enough.")
-    void testExposeCachingMetrics() {
+    @Launch({ "start-dev", "--metrics-enabled=true", "--cache-metrics-histograms-enabled=true" })
+    void testMetricsEndpointWithCacheMetricsHistograms() {
         when().get("/metrics").then()
                 .statusCode(200)
-                .body(containsString("vendor_cache_manager_keycloak_cache_"));
-    }
-
-    @Test
-    @Launch({ "start-dev", "--metrics-enabled=true" })
-    void testMetricsEndpointDoesNotEnableHealth() {
-        when().get("/health").then()
-                .statusCode(404);
+                .body(containsString("vendor_statistics_miss_times_seconds_bucket"));
     }
 
     @Test
@@ -113,10 +104,4 @@ public void run() {
         }
     }
 
-    public static class EnableCachingStatistics implements Consumer<KeycloakDistribution> {
-        @Override
-        public void accept(KeycloakDistribution dist) {
-            dist.copyOrReplaceFileFromClasspath("/cache-local.xml", Paths.get("conf", "cache-local.xml"));
-        }
-    }
 }

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartDevHelpAll.unix.approved.txt

@@ -39,6 +39,9 @@ Cache:
                        'cache-mtls-truststore.p12' under conf/ directory.
 --cache-embedded-mtls-trust-store-password <password>
                      The password to access the Truststore.
+--cache-metrics-histograms-enabled <true|false>
+                     Enable histograms for metrics for the embedded caches. Default: false.
+                       Available only when metrics are enabled.
 --cache-remote-host <hostname>
                      The hostname of the remote server for the remote store configuration. It
                        replaces the 'host' attribute of 'remote-server' tag of the configuration

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartHelpAll.unix.approved.txt

@@ -40,6 +40,9 @@ Cache:
                        'cache-mtls-truststore.p12' under conf/ directory.
 --cache-embedded-mtls-trust-store-password <password>
                      The password to access the Truststore.
+--cache-metrics-histograms-enabled <true|false>
+                     Enable histograms for metrics for the embedded caches. Default: false.
+                       Available only when metrics are enabled.
 --cache-remote-host <hostname>
                      The hostname of the remote server for the remote store configuration. It
                        replaces the 'host' attribute of 'remote-server' tag of the configuration

quarkus/tests/integration/src/test/resources/org/keycloak/it/cli/dist/approvals/cli/help/HelpCommandDistTest.testStartOptimizedHelpAll.unix.approved.txt

@@ -32,6 +32,9 @@ Cache:
                        'cache-mtls-truststore.p12' under conf/ directory.
 --cache-embedded-mtls-trust-store-password <password>
                      The password to access the Truststore.
+--cache-metrics-histograms-enabled <true|false>
+                     Enable histograms for metrics for the embedded caches. Default: false.
+                       Available only when metrics are enabled.
 --cache-remote-host <hostname>
                      The hostname of the remote server for the remote store configuration. It
                        replaces the 'host' attribute of 'remote-server' tag of the configuration