Adding the available event types to the CLI and the docs (#35593)

Closes #35573

Signed-off-by: Alexander Schwartz <aschwart@redhat.com>

docs/guides/observability/event-metrics.adoc

@@ -37,6 +37,7 @@ The following shows how to configure {project_name} to break down the metrics by
 <@kc.start parameters="... --event-metrics-user-tags=realm,idp,clientId ..."/>
 
 You can limit the events for which {project_name} will expose metrics.
+See the {adminguide_link}#event-types[{adminguide_name} on event types] for an overview of the available events.
 
 The following example limits the events collected to `LOGIN` and `LOGOUT` events:
 

docs/guides/templates/options.adoc

@@ -40,7 +40,7 @@ ${option.deprecated.note!}<#if option.deprecated.newOptionsKeys?has_content><#if
 </#if>
 
 |<#if option.expectedValues?has_content>
-<#list option.expectedValues as value>`+${value!}+`<#if option.defaultValue?has_content && value = option.defaultValue> (default)</#if><#if value?has_next>, </#if></#list><#if !option.strictExpectedValues>, or any</#if>
+<#list option.expectedValues as value>`+${value!}+`<#if option.defaultValue?has_content && value = option.defaultValue> (default)</#if><#if option.deprecated?has_content && option.deprecated.deprecatedValues?seq_contains(value)> (deprecated)</#if><#if value?has_next>, </#if></#list><#if !option.strictExpectedValues>, or any</#if>
 <#else>
 <#if option.defaultValue?has_content>[.options-default]#`+${option.defaultValue!}+`# (default)</#if><#if option.type?has_content && option.defaultValue?has_content> or </#if><#if option.type?has_content && !option.expectedValues?has_content>any `+${option.type!}+`</#if>
 </#if>

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

@@ -23,8 +23,24 @@ public class EventOptions {
             .category(OptionCategory.EVENTS)
             .description("Comma-separated list of events to be collected for user event metrics. Reduce the number of metrics. If empty or not set, all events create a metric.")
             .buildTime(false)
+            .expectedValues(sortedListOfEvents())
+            .deprecatedMetadata(DeprecatedMetadata.deprecateValues("Use `remove_credential` instead of `remove_totp`, and `update_credential` instead of `update_totp` and `update_password`.", "remove_totp", "update_totp", "update_password"))
             .build();
 
+    private static List<String> sortedListOfEvents() {
+        List<String> events = new java.util.ArrayList<>(List.of("register", "login", "code_to_token", "logout", "client_login", "refresh_token", "introspect_token", "federated_identity_link",
+                "remove_federated_identity", "update_email", "update_profile",
+                "verify_email", "verify_profile", "grant_consent", "update_consent", "revoke_grant", "send_verify_email", "send_reset_password", "send_identity_provider_link",
+                "reset_password", "restart_authentication", "invalid_signature", "register_node", "unregister_node", "user_info_request", "identity_provider_link_account", "identity_provider_login",
+                "identity_provider_first_login", "identity_provider_post_login", "identity_provider_response", "identity_provider_retrieve_token", "impersonate", "custom_required_action",
+                "execute_actions", "execute_action_token", "client_info", "client_register", "client_update", "client_delete", "client_initiated_account_linking", "token_exchange",
+                "oauth2_device_auth", "oauth2_device_verify_user_code", "oauth2_device_code_to_token", "authreqid_to_token", "permission_token", "delete_account", "pushed_authorization_request",
+                "user_disabled_by_permanent_lockout", "user_disabled_by_temporary_lockout", "oauth2_extension_grant", "federated_identity_override_link", "update_credential", "remove_credential",
+                "invite_org", "remove_totp", "update_totp", "update_password"));
+        events.sort(String::compareToIgnoreCase);
+        return events;
+    }
+
 }
 
 

quarkus/runtime/src/test/java/org/keycloak/config/EventOptionsTest.java

@@ -0,0 +1,66 @@
+/*
+ * Copyright 2024 Red Hat, Inc. and/or its affiliates
+ * and other contributors as indicated by the @author tags.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package org.keycloak.config;
+
+import org.junit.Test;
+import org.keycloak.events.EventType;
+
+import java.util.ArrayList;
+import java.util.List;
+
+import static org.junit.Assert.fail;
+
+public class EventOptionsTest {
+
+    /**
+     * This test ensures that list of CLI options is in-sync with the {@link EventType} enum.
+     * That enum is not directly accessible by the CLI classes, that's why there is this test.
+     */
+    @Test
+    public void testAllEnumsArePresent() {
+        List<String> expectedValues = new ArrayList<>(EventOptions.USER_EVENT_METRICS_EVENTS.getExpectedValues());
+        List<String> deprecatedValues = new ArrayList<>(EventOptions.USER_EVENT_METRICS_EVENTS.getDeprecatedMetadata().get().getDeprecatedValues());
+        List<String> missingOptions = new ArrayList<>();
+        for (EventType event : EventType.values()) {
+            if (event.name().endsWith("_ERROR")) {
+                continue;
+            }
+            if (event == EventType.VALIDATE_ACCESS_TOKEN) {
+                // event is deprecated and no longer used in the code base
+                continue;
+            }
+            String value = event.name().toLowerCase();
+            if (expectedValues.contains(value)) {
+                expectedValues.remove(value);
+            } else {
+                missingOptions.add(value);
+            }
+            deprecatedValues.remove(value);
+        }
+        if (!missingOptions.isEmpty()) {
+            fail("Missing event types " + missingOptions + " in event-metrics-user-events");
+        }
+        if (!expectedValues.isEmpty()) {
+            fail("Unknown event types " + expectedValues + " found in event-metrics-user-events");
+        }
+        if (!deprecatedValues.isEmpty()) {
+            fail("Unknown event types " + deprecatedValues + " found in event-metrics-user-events");
+        }
+    }
+
+}

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

@@ -154,8 +154,10 @@ public class HelpCommandDistTest {
     }
 
     private void assertHelp(CLIResult cliResult) {
-        // normalize the output to prevent changes around the feature toggles to mark the output to differ
-        String output = cliResult.getOutput().replaceAll("((Disables|Enables) a set of one or more features. Possible values are: )[^.]{30,}", "$1<...>");
+        // normalize the output to prevent changes around the feature toggles or events to mark the output to differ
+        String output = cliResult.getOutput()
+                .replaceAll("((Disables|Enables) a set of one or more features. Possible values are: )[^.]{30,}", "$1<...>")
+                .replaceAll("(create a metric. Possible values are:)[^.]{30,}.(Available|only|when|user|event|metrics|are|enabled.| )*", "$1<...>");
 
         String osName = System.getProperty("os.name");
         if(osName.toLowerCase(Locale.ROOT).contains("windows")) {

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

@@ -249,7 +249,7 @@ Events (Preview):
 --event-metrics-user-events <events>
                      Preview: Comma-separated list of events to be collected for user event
                        metrics. Reduce the number of metrics. If empty or not set, all events
-                       create a metric. Available only when user event metrics are enabled.
+                       create a metric. Possible values are:<...>
 --event-metrics-user-tags <tags>
                      Preview: Comma-separated list of tags to be collected for user event metrics.
                        By default only 'realm' is enabled to avoid a high metrics cardinality.

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

@@ -249,7 +249,7 @@ Events (Preview):
 --event-metrics-user-events <events>
                      Preview: Comma-separated list of events to be collected for user event
                        metrics. Reduce the number of metrics. If empty or not set, all events
-                       create a metric. Available only when user event metrics are enabled.
+                       create a metric. Possible values are:<...>
 --event-metrics-user-tags <tags>
                      Preview: Comma-separated list of tags to be collected for user event metrics.
                        By default only 'realm' is enabled to avoid a high metrics cardinality.

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

@@ -450,7 +450,7 @@ Events (Preview):
 --event-metrics-user-events <events>
                      Preview: Comma-separated list of events to be collected for user event
                        metrics. Reduce the number of metrics. If empty or not set, all events
-                       create a metric. Available only when user event metrics are enabled.
+                       create a metric. Possible values are:<...>
 --event-metrics-user-tags <tags>
                      Preview: Comma-separated list of tags to be collected for user event metrics.
                        By default only 'realm' is enabled to avoid a high metrics cardinality.

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

@@ -451,7 +451,7 @@ Events (Preview):
 --event-metrics-user-events <events>
                      Preview: Comma-separated list of events to be collected for user event
                        metrics. Reduce the number of metrics. If empty or not set, all events
-                       create a metric. Available only when user event metrics are enabled.
+                       create a metric. Possible values are:<...>
 --event-metrics-user-tags <tags>
                      Preview: Comma-separated list of tags to be collected for user event metrics.
                        By default only 'realm' is enabled to avoid a high metrics cardinality.

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

@@ -388,7 +388,7 @@ Events (Preview):
 --event-metrics-user-events <events>
                      Preview: Comma-separated list of events to be collected for user event
                        metrics. Reduce the number of metrics. If empty or not set, all events
-                       create a metric. Available only when user event metrics are enabled.
+                       create a metric. Possible values are:<...>
 --event-metrics-user-tags <tags>
                      Preview: Comma-separated list of tags to be collected for user event metrics.
                        By default only 'realm' is enabled to avoid a high metrics cardinality.