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

2026-09-25T19:49:10Z

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

Новая страница

= Мониторинг Keycloak =

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

{| class="wikitable"
! Параметр
! Значение
|-
| Версия расширения
| <code>2.3.0</code>
|-
| Идентификатор
| <code>ru.ruscomtech.extension.prometheus-keycloak</code>
|-
| Минимальная версия Ключ-АСТРОМ
| <code>1.309.0</code>
|-
| Минимальная версия EEC
| <code>1.253.0</code>
|-
| Источник данных
| Prometheus
|-
| Количество поддерживаемых метрик
| 297
|}

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

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

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

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

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

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

<pre>
http://localhost:9000/metrics
</pre>

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

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

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

<pre>
http://keycloak.example.local:9000/metrics
</pre>

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

== Подготовка Keycloak ==

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

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

<pre>
bin/kc.sh start --metrics-enabled=true
</pre>

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

<pre>
KC_METRICS_ENABLED=true
</pre>

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

<pre>
http://<host>:9000/metrics
</pre>

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

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

<pre>
curl http://localhost:9000/metrics
</pre>

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

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

=== Метрики Aerogear SPI ===

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

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

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

<pre>
/opt/keycloak/providers/
</pre>

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

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

<pre>
http://keycloak.example.local:8080/realms/master/metrics
</pre>

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

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

<pre>
Manage → Events → Config → Event Listeners → metrics-listener
</pre>

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

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

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

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

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

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

<pre>
http://keycloak.example.local:9000/metrics
</pre>

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

<pre>
http://keycloak.example.local:8080/realms/master/metrics
</pre>

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

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

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

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

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

{| class="wikitable"
! Наборы
! Назначение
|-
| <code>Cache container stats</code>, <code>Cache</code>
| Состояние контейнеров кэша и количество кэшей.
|-
| <code>Statistics</code>, <code>Hit statistics</code>
| Попадания, промахи и эффективность кэша.
|-
| <code>Evictions</code>, <code>Passivations</code>
| Вытеснение и пассивация записей.
|-
| <code>Remove statistics</code>, <code>Store statistics</code>
| Удаление и сохранение записей.
|-
| <code>Local container</code>
| Использование памяти локальным контейнером.
|}

=== Aerogear SPI ===

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

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

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

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

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

== Метки Prometheus ==

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

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

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

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

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

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

<pre>
prometheus:keycloak
</pre>

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

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

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

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

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

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

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

{| class="wikitable"
! Версия
! Изменения
|-
|2.3.0
|
* Ключ-АСТРОМ <code>1.309.0+</code>.
* Добавлен контекст безопасности для сущности экземпляра Keycloak.
* Добавлены страницы анализа для нового интерфейса мониторинга инфраструктуры.
* Добавлена готовая обзорная панель Keycloak.
|}

Мониторинг Keycloak - История изменений