Keycloak
Introduction
Keycloak is an open-source Identity and Access Management (IAM) solution developed by Red Hat. It provides authentication, authorization, and user management capabilities for web applications and services. Keycloak is built on top of widely used standards such as OAuth 2.0, OpenID Connect, and SAML.
Getting Started
Compatibility
Keycloak O11ySource is compatible with Keycloak version 22.0.5, and metrics are collected through the Prometheus endpoint.
Data Collection Method
vuSmartMaps collects health and performance data for Keycloak using VuNet's Internal Data Collector.
Prerequisites
Inputs for Configuring Data Source
- Keycloak Server: The IP Address/FQDN of the Keycloak server. This field is the key to identify each server you add here.
- Period (in seconds): How frequently data is gathered. period should be between 60 seconds – 3000 seconds.
- URL: The base server URL of the Keycloak instance (host and port only, no path). Used to collect global JVM/process metrics from <URL>/metrics and, when Realms are specified below, realm metrics from <URL>/realms/<realm>/metrics. Eg: http://127.0.0.1:8080 or https://127.0.0.1:8443
- Realm: Realm name to collect realm-specific metrics for (e.g. master,demo). Leave blank to skip realm-level metrics.
Firewall Requirement
To collect data from this O11ySource, ensure the following ports are opened:
| Source IP | Destination IP | Destination Port | Protocol | Direction |
|---|---|---|---|---|
| vuSmartMaps IP | Keycloak Server | 8080* | TCP | Outbound |
*Before providing the firewall requirements, please update the port based on the customer environment.
Configuring the Target
Health and Performance metrics from prometheus endpoint. User has to add the Keycloak Metrics SPI - a Service Provider that adds a metrics endpoint to Keycloak. This endpoint returns metrics data ready to be scraped by Prometheus. Please click here to download the keycloak-metrics-spi-5.0.0.jar.
Steps to Install the Keycloak Metrics SPI JAR
Follow the steps below to install and enable the Keycloak Metrics SPI plugin: 1.Download the keycloak-metrics-spi-5.0.0.jar file from the Aerogear GitHub releases page: 2.Mount or copy the downloaded JAR file to the Keycloak providers directory. 3.Restart the Keycloak service or pod for the plugin changes to take effect. 4.Enable the metrics-listener event listener for each required realm using the Keycloak Admin API.
Once these steps are completed, Keycloak will be ready to expose metrics through the installed Metrics SPI plugin.
Two distinct providers are defined:
- MetricsEventListener to record the internal Keycloak events
- MetricsEndpoint to expose the data through a custom endpoint
The endpoint is available under <base url>/realms/<realm>/metrics (Quarkus). It will return data for all realms.
Configuration Steps
Enablethe O11ySource.- Select the sources tab and press the
+button to add a new instance that has to be monitored. - Provide the required configurations:
- *Keycloak Server
- *Period (in seconds)
- *URL
- Click
Saveto close the data source window.
Metrics Collected
| Name | Description | Data Type |
|---|---|---|
| @timestamp | Time when the metric was collected by Telegraf | String |
| timestamp | Precise time when the metric was collected (with milliseconds) | DateTime64(3) |
| vublock_name | Name of the VU block in Keycloak | LowCardinality(String) |
| target | Target system or service being monitored | String |
| host | Name or IP of the Keycloak instance host | String |
| tenant_id | ID of the tenant in Keycloak | LowCardinality(String) |
| bu_id | ID of the business unit in Keycloak | LowCardinality(String) |
| tags_host | Host-related tags in the context of the Keycloak environment | String |
| tags_pool | Tags representing the connection pool used by Keycloak | LowCardinality(String) |
| tags_gc | Tags related to garbage collection within Keycloak | LowCardinality(String) |
| tags_runtime | Tags indicating the runtime environment of Keycloak | LowCardinality(String) |
| tags_url | Tags related to the URL being accessed in Keycloak | LowCardinality(String) |
| tags_area | Tags defining different areas or domains within Keycloak | LowCardinality(String) |
| tags_state | Tags related to the state of Keycloak components or services | LowCardinality(String) |
| tags_realm | Tags identifying the realm in Keycloak | LowCardinality(String) |
| tags_resource | Tags specifying the resource being accessed or protected in Keycloak | LowCardinality(String) |
| tags_client_id | ID of the client in Keycloak | LowCardinality(String) |
| tags_provider | Tags indicating the identity provider (IdP) used in Keycloak | LowCardinality(String) |
| tags_method | HTTP method used in the Keycloak request (GET, POST, etc.) | LowCardinality(String) |
| tags_code | HTTP status code returned by Keycloak | LowCardinality(String) |
| tags_error | Error returned by Keycloak | LowCardinality(String) |
| tags_le | Latency-related tags used to track Keycloak request durations | LowCardinality(String) |
| name | Name of the specific Keycloak metric | LowCardinality(String) |
| metric_name | Identifier for the metric being collected | LowCardinality(String) |
| metric_value | The actual value of the Keycloak metric | Float64 |
| metric_value_diff | Difference in metric value since the last collection | Float64 |
| tags_action | GC action reported for JVM garbage collection pauses (e.g. end of minor GC, end of major GC) | LowCardinality(String) |
| tags_cause | Cause of the JVM garbage collection event (e.g. Allocation Failure, Ergonomics) | LowCardinality(String) |
| tags_datasource | Name of the Keycloak/Quarkus datasource connection pool (Agroal) the metric belongs to | LowCardinality(String) |
| tags_id | Identifier of the JVM buffer pool or memory area the metric belongs to (e.g. direct, mapped, PS Eden Space) | LowCardinality(String) |
| tags_pool_name | Name of the Vert.x worker thread pool the metric belongs to | LowCardinality(String) |
| tags_pool_type | Type of the Vert.x worker thread pool (e.g. worker) | LowCardinality(String) |
| tags_vendor | JVM vendor running the Keycloak instance (e.g. Red Hat, Inc.) | LowCardinality(String) |
| tags_version | JVM runtime version running the Keycloak instance | LowCardinality(String) |
| tags_name | Name of the garbage collector reported by the JVM base GC metrics (e.g. PS MarkSweep, PS Scavenge) | LowCardinality(String) |
