Мониторинг Keycloak

Мониторинг Keycloak

Расширение предназначено для мониторинга Keycloak через endpoint метрик Prometheus. Оно собирает показатели JVM, HTTP-сервера, пула подключений к базе данных, кэшей, транзакций, а также необязательные метрики аутентификации и работы с токенами.

Параметр	Значение
Версия расширения	2.3.0
Идентификатор	ru.ruscomtech.extension.prometheus-keycloak
Минимальная версия Ключ-АСТРОМ	1.309.0
Минимальная версия EEC	1.253.0
Источник данных	Prometheus
Количество поддерживаемых метрик	297

Возможности расширения

• Мониторинг экземпляров Keycloak через Prometheus.
• Сбор показателей JVM, памяти, сборки мусора и потоков.
• Контроль HTTP-запросов и ошибок.
• Мониторинг Netty и рабочих пулов.
• Контроль пула подключений Agroal.
• Мониторинг Infinispan-кэшей и состояния кластера.
• Сбор статистики транзакций и блокировок.
• Контроль операций входа, регистрации и обновления токенов при использовании Aerogear SPI.
• Создание сущности экземпляра Keycloak.
• Связывание экземпляра с контролируемым Java-процессом.
• Готовая обзорная панель Keycloak.

Варианты сбора

Расширение поддерживает локальный и удалённый сбор.

Локальный сбор

Расширение выполняется ЕдинымАгентом на сервере Keycloak. В качестве endpoint используется локальный адрес:

http://localhost:9000/metrics

Для локального сбора на хосте должен быть включён EEC.

Удалённый сбор

Расширение выполняется на группе АктивныхШлюзов и подключается к Keycloak по сети:

http://keycloak.example.local:9000/metrics

АктивномуШлюзу должны быть доступны адрес и порт интерфейса управления Keycloak.

Подготовка Keycloak

Встроенные метрики

В современных версиях Keycloak метрики включаются параметром запуска:

bin/kc.sh start --metrics-enabled=true

Или переменной окружения:

KC_METRICS_ENABLED=true

После перезапуска Keycloak метрики должны быть доступны по адресу:

http://<host>:9000/metrics

Порт 9000 используется интерфейсом управления по умолчанию. Если порт или относительный путь изменены в конфигурации Keycloak, укажите фактический адрес endpoint.

Проверить доступность можно следующим запросом:

curl http://localhost:9000/metrics

Ответ должен содержать метрики в текстовом формате Prometheus.

Не рекомендуется публиковать интерфейс управления Keycloak во внешней сети. Ограничьте доступ к нему сервером ЕдиныйАгента или АктивногоШлюза.

Метрики Aerogear SPI

Встроенного endpoint достаточно для мониторинга JVM, HTTP, Netty, Agroal, кэшей и системных показателей.

Для получения расширенных метрик входов, регистраций, пользовательских событий и токенов необходимо отдельно установить Keycloak Metrics SPI от Aerogear.

JAR-файл SPI размещается в каталоге:

/opt/keycloak/providers/

После установки необходимо пересобрать или перезапустить Keycloak в соответствии со способом его установки.

Endpoint Aerogear для дистрибутива Quarkus имеет следующий формат:

http://keycloak.example.local:8080/realms/master/metrics

Указанный endpoint возвращает метрики всех realm независимо от realm, содержащегося в URL.

Для сбора пользовательских и административных событий добавьте обработчик metrics-listener в настройках событий Keycloak:

Manage → Events → Config → Event Listeners → metrics-listener

Aerogear SPI является необязательным. Без него основные встроенные метрики Keycloak продолжают собираться.

Установка расширения

1. Откройте раздел управления расширениями Ключ-АСТРОМ.
2. Загрузите подписанный пакет ru.ruscomtech.extension.prometheus-keycloak-2.3.0.zip.
3. Установите расширение.
4. Добавьте конфигурацию мониторинга.
5. Выберите локальный запуск на ЕдинымАгенте или удалённый запуск на группе АктивныхШлюзов.
6. Добавьте Prometheus endpoint.
7. Выберите необходимые наборы метрик.
8. Сохраните и включите конфигурацию.

Конфигурация endpoint

Параметр	Описание
Endpoint name	Уникальное имя подключения.
URL	Полный URL Prometheus endpoint, включая протокол, порт и путь.
Authentication	Параметры аутентификации, если endpoint защищён.
SSL	Проверка сертификата при использовании HTTPS.
Feature sets	Наборы метрик, которые необходимо собирать.
Security context	Необязательное значение контекста безопасности для создаваемой сущности.

Для встроенных метрик укажите:

http://keycloak.example.local:9000/metrics

Для необязательных метрик Aerogear добавьте отдельный endpoint:

http://keycloak.example.local:8080/realms/master/metrics

Если для разных endpoint создаются отдельные конфигурации, выбирайте только соответствующие им наборы метрик.

Наборы метрик

Основные показатели Keycloak

Наборы	Назначение
JVM, System, Memory pool, Buffer pool	JVM, процессор, память, потоки, сборка мусора и буферы.
HTTP Server, Netty, Worker Pool	HTTP-запросы, ошибки, сетевые буферы и рабочие потоки.
Agroal	Пул подключений Keycloak к базе данных.
Transactions, Lock manager	Транзакции и внутренние блокировки.

Кэши и кластер

Наборы	Назначение
Cache container stats, Cache	Состояние контейнеров кэша и количество кэшей.
Statistics, Hit statistics	Попадания, промахи и эффективность кэша.
Evictions, Passivations	Вытеснение и пассивация записей.
Remove statistics, Store statistics	Удаление и сохранение записей.
Local container	Использование памяти локальным контейнером.

Aerogear SPI

Наборы	Назначение
Aerogear - Requests, Aerogear - Responses	Продолжительность запросов, ответы и ошибки.
Aerogear - User actions	Входы, неуспешные попытки, регистрации и события пользователей.
Aerogear - Token	Выдача и обновление токенов и связанные ошибки.
Aerogear - Process	Процессор, память и файловые дескрипторы процесса.
Aerogear - JVM GC, Aerogear - JVM threads	Сборка мусора и потоки JVM.
Aerogear - JVM memory, Aerogear - JVM classes, Aerogear - JVM buffer	Память, классы и буферы JVM.

Не включайте наборы Aerogear, если соответствующий SPI не установлен: эти метрики не будут присутствовать на стандартном endpoint Keycloak.

Основные метрики

Метрика	Описание
process_cpu_usage	Использование процессора процессом Keycloak.
jvm_memory_used_bytes	Используемая память JVM.
jvm_threads_live_threads	Количество активных потоков JVM.
jvm_gc_pause_seconds	Продолжительность пауз сборщика мусора.
http_server_active_requests	Количество активных HTTP-запросов.
http_server_errors_total.count	Количество ошибок HTTP-сервера.
worker_pool_queue_size	Количество задач, ожидающих выполнения.
agroal_active	Количество активных подключений к базе данных.
agroal_available	Количество доступных подключений.
vendor_cluster_size	Размер кластера Keycloak.
vendor_statistics_hit_ratio	Доля успешных обращений к кэшу.
vendor_statistics_evictions	Количество вытеснений из кэша.
keycloak_logins.count	Количество успешных входов через Aerogear SPI.
keycloak_failed_login_attempts.count	Количество неуспешных попыток входа.
keycloak_refresh_tokens.count	Количество успешных обновлений токена.
keycloak_refresh_tokens_errors.count	Количество ошибок обновления токена.

Полный пакет содержит 297 определений метрик. Фактический набор зависит от версии Keycloak, включённых функций и содержимого Prometheus endpoint.

Метки Prometheus

Метки Prometheus автоматически преобразуются в измерения метрик Ключ-АСТРОМ.

Перед включением Aerogear оцените количество возможных значений следующих меток:

• realm;
• client_id;
• provider;
• тип пользовательского события;
• имя кэша;
• состояние потока JVM.

Большое количество realm, клиентов или событий может значительно увеличить количество временных рядов.

Создаваемые сущности

Расширение создаёт сущность:

prometheus:keycloak

Имя сущности формируется из имени хоста или адреса endpoint. В свойства сущности добавляются сведения о JVM, IP-адрес, порт и контекст безопасности.

Если адрес и порт совпадают с контролируемым Java-процессом, создаётся связь между экземпляром Keycloak и соответствующим экземпляром процесса.

Проверка работы

1. Откройте URL endpoint из браузера или с помощью curl.
2. Убедитесь, что ответ содержит метрики Prometheus.
3. Проверьте состояние конфигурации расширения.
4. Откройте обзорную панель Keycloak.
5. Проверьте появление сущности prometheus:keycloak.
6. Убедитесь, что выбранные метрики поступают в Ключ-АСТРОМ.

Устранение неполадок

Проблема	Решение
Endpoint возвращает 404	Проверьте порт и путь. Встроенные метрики обычно доступны на порту управления по пути /metrics.
Соединение отклонено	Проверьте сетевой доступ, привязку интерфейса управления и правила межсетевого экрана.
Метрики отсутствуют	Убедитесь, что Keycloak запущен с параметром --metrics-enabled=true.
Не собираются входы и токены	Установите Aerogear SPI, включите metrics-listener и настройте endpoint /realms/<realm>/metrics.
Собирается только часть метрик	Проверьте выбранные наборы и наличие соответствующих метрик непосредственно в ответе endpoint.
Не создаётся связь с процессом	Проверьте совпадение IP-адреса и порта сущности с контролируемым Java-процессом.
Создаётся слишком много временных рядов	Ограничьте наборы метрик и количество высококардинальных меток.

История изменений

Версия	Изменения
2.3.0	Ключ-АСТРОМ 1.309.0+. Добавлен контекст безопасности для сущности экземпляра Keycloak. Добавлены страницы анализа для нового интерфейса мониторинга инфраструктуры. Добавлена готовая обзорная панель Keycloak.