🚀 Try it for free in the new Phase Two keycloak managed service. Go to Phase Two for more information.

⚠️ This is Phase Two's fork of kokuwaio/keycloak-event-metrics. It does not work in the same way. Please report issues to the main repo, or here if you are using it in the context of the Phase Two docker image.

Keycloak Metrics

Provides metrics for Keycloak user/admin events and user/client/session count. Tested on Keycloak 21-24.

Why?

aerogear/keycloak-metrics-spi is an alternative to this plugin but is not well maintained. This implementation is different:

• no Prometheus push (event store custom implementation only adds counter to Micrometer)
• no realm specific Prometheus endpoint, only /metrics (from Quarkus)
• no jvm/http metrics, this is already included in Keycloak
• different metric names, can relace model ids with name (see configuration)
• deployed to maven central and very small (15 kb vs. 151 KB aerogear/keycloak-metrics-spi)
• gauge for active/offline sessions and user/client count

What?

Resuses micrometer from Quarkus distribution to add metrics for Keycloak for events.

User Events

User events are added with key keycloak_event_user_total and tags:

• type: EventType from Event#type
• realm: realm id from Event#realmId
• client: client id from Event#clientId
• error: error from Event#error, only present for error types

Examples:

keycloak_event_user_total{client="test",realm="9039a0b5-e8c9-437a-a02e-9d91b04548a4",type="LOGIN",error="",} 2.0
keycloak_event_user_total{client="test",realm="1fdb3465-1675-49e8-88ad-292e2f42ee72",type="LOGIN",error="",} 1.0
keycloak_event_user_total{client="test",realm="1fdb3465-1675-49e8-88ad-292e2f42ee72",type="LOGIN_ERROR",error="invalid_user_credentials",} 1.0

Admin Events

Admin events are added with key keycloak_event_admin_total and tags:

• realm: realm id from AdminEvent#realmId
• operation: OperationType from AdminEvent#operationType
• resource: ResourceType from AdminEvent#resourceType
• error: error from AdminEvent#error, only present for error types

Examples:

keycloak_event_admin_total{error="",operation="CREATE",realm="1fdb3465-1675-49e8-88ad-292e2f42ee72",resource="USER",} 1.0
keycloak_event_admin_total{error="",operation="CREATE",realm="9039a0b5-e8c9-437a-a02e-9d91b04548a4",resource="USER",} 1.0

Configuration

KC_COMMUNITY_EVENTS_METRICS_ENABLED

Set to true (the default false) than the events metrics gets counted using micrometer

KC_METRICS_EVENT_REPLACE_IDS

Set to true (the default value) than replace model ids from events with names:

• RealmModel#getId() with RealmModel#getName()

Metrics:

keycloak_event_user_total{client="test-client",error="",realm="test-realm",type="LOGIN",} 2.0
keycloak_event_user_total{client="other-client",error="",realm="other-realm",type="LOGIN",} 1.0
keycloak_event_user_total{client="other-client",error="invalid_user_credentials",realm="other-realm",type="LOGIN_ERROR",} 1.0

KC_METRICS_STATS_ENABLED

Set to true (default is false) to provide metrics for user/client count per realm and session count per client. Metrics:

# HELP keycloak_users  
# TYPE keycloak_users gauge
keycloak_users{realm="master",} 1.0
keycloak_users{realm="my-realm",} 2.0
keycloak_users{realm="other-realm",} 1.0# HELP keycloak_active_user_sessions
# TYPE keycloak_active_user_sessions gauge
keycloak_active_user_sessions{client="admin-cli",realm="userCount_1",} 0.0
keycloak_active_user_sessions{client="admin-cli",realm="userCount_2",} 0.0
keycloak_active_user_sessions{client="admin-cli",realm="master",} 1.0
# TYPE keycloak_active_client_sessions gauge
keycloak_active_client_sessions{client="admin-cli",realm="userCount_1",} 0.0
keycloak_active_client_sessions{client="admin-cli",realm="userCount_2",} 0.0
keycloak_active_client_sessions{client="admin-cli",realm="master",} 0.0
# TYPE keycloak_offline_sessions gauge
keycloak_offline_sessions{client="admin-cli",realm="userCount_1",} 0.0
keycloak_offline_sessions{client="admin-cli",realm="userCount_2",} 0.0
keycloak_offline_sessions{client="admin-cli",realm="master",} 0.0

KC_METRICS_STATS_INTERVAL

If KC_METRICS_STATS_ENABLED is true this will define the interval for scraping. If not configured PT60s will be used.

KC_METRICS_STATS_INFO_THRESHOLD and KC_METRICS_STATS_WARN_THRESHOLD

If KC_METRICS_STATS_ENABLED is true this envs will define logging if scraping takes to long. Both envs are parsed as java.lang.Duration.

Default values:

• KC_METRICS_STATS_INFO_THRESHOLD: 50% of KC_METRICS_STATS_INTERVAL = 30s
• KC_METRICS_STATS_WARN_THRESHOLD: 75% of KC_METRICS_STATS_INTERVAL = 45s

If scrapping takes less than KC_METRICS_STATS_INFO_THRESHOLD duration will be logged on debug level.

Installation

Grafana Dashboard

Can be found here: kokuwaio/keycloak keycloak-metrics.json

Testcontainers

For usage in Testcontainers see KeycloakExtension.java

Docker

Check: kokuwaio/keycloak

Dockerfile:

###
### download keycloak event metrics
###

FROM debian:stable-slim AS metrics

RUN apt-get -qq update
RUN apt-get -qq install --yes --no-install-recommends ca-certificates wget

ARG METRICS_VERSION=1.0.0
ARG METRICS_FILE=keycloak-event-metrics-${METRICS_VERSION}.jar
ARG METRICS_URL=https://repo1.maven.org/maven2/io/kokuwa/keycloak/keycloak-event-metrics/${METRICS_VERSION}

RUN wget --quiet --no-hsts ${METRICS_URL}/${METRICS_FILE}
RUN wget --quiet --no-hsts ${METRICS_URL}/${METRICS_FILE}.sha1
RUN echo "$(cat ${METRICS_FILE}.sha1) ${METRICS_FILE}" sha1sum --quiet --check --strict -
RUN mkdir -p /opt/keycloak/providers
RUN mv ${METRICS_FILE} /opt/keycloak/providers

###
### build keycloak with metrics
###

FROM quay.io/keycloak/keycloak:23.0.7

ENV KEYCLOAK_ADMIN=admin
ENV KEYCLOAK_ADMIN_PASSWORD=password
ENV KC_HEALTH_ENABLED=true
ENV KC_METRICS_ENABLED=true
ENV KC_LOG_CONSOLE_COLOR=true

COPY --from=metrics /opt/keycloak/providers /opt/keycloak/providers
RUN /opt/keycloak/bin/kc.sh build

Run:

docker build . --tag keycloak:metrics
docker run --rm -p8080 keycloak:metrics start-dev