David Martin One thing about this one.

The metrics endpoint itself returns already a description of each metrics. It follows this format:

# HELP keycloak_user_event_LOGOUT Generic KeyCloak User event

# TYPE keycloak_user_event_LOGOUT counter

keycloak_user_event_LOGOUT{realm="test",} 3.0

Where "Generic KeyCloak User event" is the description in this case. Maybe instead of creating a whole new document, we could write proper descriptions in the SPI so that the user don't need to find any documentation about it but read it directly. More over, if any metrics are removed / added, we don't have to worry about the docs, we just have to update the code. The description is set like this: https://github.com/aerogear/keycloak-metrics-spi/blob/master/src/main/java/org/jboss/aerogear/keycloak/metrics/PrometheusExporter.java#L67-L69

We could, however, describe what the endpoint returns in a brief section in the SPI readme.