Keycloak 集群部署

此文件包含監控 Keycloak 部署效能的指標詳細資訊。

本文檔中描述的部署適用於單站點部署。在此架構中，Keycloak 節點利用 Infinispan 內嵌叢集快取來形成叢集。

如果使用外部 Infinispan，請查看使用外部 Infinispan 部署的 Keycloak指南。

啟用 Keycloak 指標

Keycloak 在管理介面端點 /metrics 上公開指標。若要啟用，請使用建置時選項 --metrics-enabled=true。

在 Kubernetes 叢集上，使用 Keycloak Operator，可以透過 Keycloak CR addionalOptions 啟用指標，如下所示

apiVersion: k8s.keycloak.org/v2alpha1
kind: Keycloak
metadata:
  labels:
    app: keycloak
  name: keycloak
spec:
  additionalOptions:
    - name: metrics-enabled
      value: 'true'

可以在此處找到更多資訊。

Keycloak HTTP 指標

本節說明用於監控 Keycloak HTTP 請求處理的指標。

處理時間

這些指標會公開處理時間，以監控 Keycloak 的效能以及處理請求所需的時間。

在健康的叢集上，平均處理時間將保持穩定。處理時間的尖峰或增加可能是某些節點負載過重的早期跡象。

標籤

  • outcome：更一般的結果標籤。

  • status：HTTP 狀態碼。

  • uri：請求的 URI。

指標 描述

http_server_requests_seconds_count

已處理的請求總數。

http_server_requests_seconds_sum

所有已處理請求的總持續時間。
當啟用直方圖時，可以使用百分位數儲存桶。這些對於建立熱圖很有用，但收集和公開百分位數儲存桶可能會對部署效能產生負面影響。

作用中的請求

目前的作用中請求數量也可用。

指標 描述

http_server_active_requests

目前的作用中請求數量

頻寬

以下指標有助於監控 Keycloak 使用的頻寬和消耗的流量，以及接收或傳送的請求和回應所消耗的流量。

指標 描述

http_server_bytes_written_count

傳送的回應總數。

http_server_bytes_written_sum

傳送的總位元組數。

http_server_bytes_read_count

接收的請求總數。

http_server_bytes_read_sum

接收的總位元組數。
當啟用直方圖時，可以使用百分位數儲存桶。這些對於建立熱圖很有用，但收集和公開百分位數儲存桶可能會對部署效能產生負面影響。

叢集和網路

部署多個 Keycloak 節點可讓負載分散在它們之間，但這需要節點之間的通訊。本節說明一些有助於監控 Keycloak 之間通訊的指標，以便識別可能的故障。

全域標籤

  • cluster=<name>：叢集名稱。如果正在收集來自多個叢集的指標，則此標籤有助於識別它們所屬的位置。

  • node=<node>：報告指標的節點名稱。

回應時間

以下指標會公開遠端請求的回應時間。回應時間是在兩個節點之間測量的，包括處理時間。所有請求都由這些指標測量，並且回應時間應在叢集生命週期中保持穩定。

在健康的叢集中，回應時間將保持穩定。回應時間增加可能表示叢集已降級或節點負載過重。

標籤

  • node=<node>：它會識別傳送者節點。

  • target_node=<node>：它會識別接收者節點。

指標 描述

vendor_jgroups_stats_sync_requests_seconds_count

對接收者節點的同步請求數。

vendor_jgroups_stats_sync_requests_seconds_sum

對接收者節點的同步請求總持續時間
當啟用直方圖時，可以使用百分位數儲存桶。這些對於建立熱圖很有用，但收集和公開百分位數儲存桶可能會對部署效能產生負面影響。

頻寬

Keycloak 接收和傳送的所有位元組都由這些指標收集。此外，所有內部訊息（如心跳訊號）也會被計算在內。它們允許計算每個節點目前使用的頻寬。

指標名稱取決於使用的 JGroups 傳輸協定。
指標 協定 描述

vendor_jgroups_tcp_get_num_bytes_received

TCP

節點接收的總位元組數。

vendor_jgroups_udp_get_num_bytes_received

UDP

vendor_jgroups_tunnel_get_num_bytes_received

TUNNEL

vendor_jgroups_tcp_get_num_bytes_sent

TCP

節點傳送的總位元組數。

vendor_jgroups_tunnel_get_num_bytes_sent

UDP

vendor_jgroups_tunnel_get_num_bytes_sent

TUNNEL

執行緒集區

監控執行緒集區大小是一個很好的指標，可以判斷節點是否處於高負載狀態。接收的所有請求都會新增至執行緒集區進行處理，當執行緒集區已滿時，會捨棄請求。重新傳輸機制可確保可靠的通訊，但會增加資源使用量。

在健康的叢集中，執行緒集區永遠不應接近其最大大小（預設為 200 個執行緒）。
虛擬執行緒無法使用執行緒集區指標。
指標名稱取決於使用的 JGroups 傳輸協定。
指標 協定 描述

vendor_jgroups_tcp_get_thread_pool_size

TCP

執行緒集區中的目前執行緒數。

vendor_jgroups_udp_get_thread_pool_size

UDP

vendor_jgroups_tunnel_get_thread_pool_size

TUNNEL

vendor_jgroups_tcp_get_largest_size

TCP

集區中曾經同時存在的最大執行緒數。

vendor_jgroups_udp_get_largest_size

UDP

vendor_jgroups_tunnel_get_largest_size

TUNNEL

流量控制

流量控制負責將訊息傳送者的速率調整為最慢接收者的速率。這是透過以信用為基礎的系統來實作，其中每個傳送者在傳送時會遞減其信用。當信用低於 0 時，傳送者會遭到封鎖，只有在收到接收者的補充訊息時才會繼續傳送訊息。

以下指標顯示封鎖的訊息數量和平均封鎖時間。當值不為零時，可能表示接收者已過載，並可能降低叢集效能。

每個節點都有兩個獨立的流量控制協定，UFC 用於單播訊息，而 MFC 用於多播訊息。

健康的叢集會顯示所有指標的值都為零。
指標 描述

vendor_jgroups_ufc_get_number_of_blockings

流量控制封鎖傳送者以傳送單播訊息的次數。

vendor_jgroups_ufc_get_average_time_blocked

嘗試傳送單播訊息時，流量控制中封鎖的平均時間（以毫秒為單位）。

vendor_jgroups_mfc_get_number_of_blockings

流量控制封鎖傳送者以傳送多播訊息的次數。

vendor_jgroups_mfc_get_average_time_blocked

嘗試傳送多播訊息時，流量控制中封鎖的平均時間（以毫秒為單位）。

重新傳輸

JGroups 提供訊息的可靠傳遞。當訊息在網路上遭到捨棄，或接收者無法處理訊息時，則需要重新傳輸。重新傳輸會增加資源使用量，而且通常表示系統已過載。

隨機提前捨棄 (RED) 會監控傳送者佇列。當佇列幾乎已滿時，會捨棄訊息，且必須發生重新傳輸。它可以防止執行緒遭到已滿的傳送者佇列封鎖。

健康的叢集會顯示所有指標的值都為零。
指標 描述

vendor_jgroups_unicast3_get_num_xmits

重新傳輸的訊息數。

vendor_jgroups_red_get_dropped_messages

傳送者捨棄的訊息總數。

vendor_jgroups_red_get_drop_rate

傳送者捨棄的所有訊息的百分比。

網路分割

叢集大小

叢集大小指標會報告叢集中存在的節點數。如果不同，可能表示節點正在加入、關閉或，在最壞的情況下，正在發生網路分割。

健康的叢集會顯示所有節點的值都相同。
指標 描述

vendor_cluster_size

叢集中的節點數。

網路分割事件

叢集中的網路分割可能是由各種原因引起的。此指標並無助於預測網路分割，但會表示它已發生，且叢集已合併。

健康的叢集會顯示此指標的值為零。
指標 描述

vendor_jgroups_merge3_get_num_merge_events

偵測到並修復網路分割的次數。

Infinispan 快取

Keycloak 將資料快取在內嵌的 Infinispan 快取中。本節中的指標有助於監控快取健康狀況和叢集複寫。

全域標籤

  • cache=<name>：快取名稱。

大小

使用這兩個指標監控快取中的項目數。如果快取已叢集化，則每個項目都有一個擁有者節點和零個或多個不同節點的備份複本。

將唯一項目大小指標加總，以取得叢集的項目總數。
指標 描述

vendor_statistics_approximate_entries

節點儲存的大約項目數，包括備份複本。

vendor_statistics_approximate_entries_unique

節點儲存的大約項目數，不包括備份複本。

資料存取

以下指標會監控快取存取，例如讀取、寫入及其持續時間。

儲存

儲存操作是寫入操作，會寫入或更新快取中儲存的值。

指標 描述

vendor_statistics_store_times_seconds_count

儲存請求的總數。

vendor_statistics_store_times_seconds_sum

所有儲存請求的總持續時間。
當啟用直方圖時，可以使用百分位數儲存桶。這些對於建立熱圖很有用，但收集和公開百分位數儲存桶可能會對部署效能產生負面影響。

讀取

讀取操作會從快取中讀取值。它分為兩組，如果找到值，則為命中；如果找不到，則為未命中。

指標 描述

vendor_statistics_hit_times_seconds_count

讀取命中請求的總數。

vendor_statistics_hit_times_seconds_sum

所有讀取命中請求的總持續時間。

vendor_statistics_miss_times_seconds_count

讀取未命中請求的總數。

vendor_statistics_miss_times_seconds_sum

所有讀取未命中請求的總持續時間。
當啟用直方圖時，可以使用百分位數儲存桶。這些對於建立熱圖很有用，但收集和公開百分位數儲存桶可能會對部署效能產生負面影響。

移除

移除操作會從快取中移除一個值。它分為兩組，如果值存在則為命中，如果值不存在則為未命中。

指標 描述

vendor_statistics_remove_hit_times_seconds_count

移除命中請求的總數。

vendor_statistics_remove_hit_times_seconds_sum

所有移除命中請求的總持續時間。

vendor_statistics_remove_miss_times_seconds_count

移除未命中請求的總數。

vendor_statistics_remove_miss_times_seconds_sum

所有移除未命中請求的總持續時間。
當啟用直方圖時，可以使用百分位數儲存桶。這些對於建立熱圖很有用，但收集和公開百分位數儲存桶可能會對部署效能產生負面影響。

對於 users 和 realms 快取，資料庫失效會轉化為移除操作。這些指標可以很好地指示資料庫實體被修改的頻率，因此也會從快取中移除的頻率。

讀取和移除操作的命中率

可以使用表達式來計算系統（如 Prometheus）中快取的命中率。例如，讀取操作的命中率可以表示為

vendor_statistics_hit_times_seconds_count/(vendor_statistics_hit_times_seconds_count+vendor_statistics_miss_times_seconds_count)

讀/寫比率

可以使用表達式並使用上述指標來計算快取的讀寫比率

(vendor_statistics_hit_times_seconds_count+vendor_statistics_miss_times_seconds_count)/(vendor_statistics_hit_times_seconds_count+vendor_statistics_miss_times_seconds_count+vendor_statistics_remove_hit_times_seconds_count+vendor_statistics_remove_miss_times_seconds_count+vendor_statistics_store_times_seconds_count)

逐出

逐出是限制快取大小的過程，當快取已滿時，會移除一個條目，以便為新的快取條目騰出空間。由於 Keycloak 將資料庫實體快取在 users、realms 和 authorization 中，因此資料庫存取總是會發生逐出事件。

指標 描述

vendor_statistics_evictions

逐出事件的總數。

逐出率

逐出次數快速增加且資料庫 CPU 使用率非常高，表示 users 或 realms 快取對於 Keycloak 的順暢運作而言太小，因為資料需要經常從資料庫重新載入，這會減慢回應速度。如果可用記憶體足夠，請考慮使用 CLI 選項 cache-embedded-users-max-count 或 cache-embedded-realms-max-count 來增加最大快取大小

鎖定

寫入和移除操作會持有鎖定，直到該值複製到本機叢集和遠端站點。

在健全的叢集上，持有的鎖定數量應該保持不變，但死鎖可能會造成暫時性的峰值。
指標 描述

vendor_lock_manager_number_of_locks_held

此節點目前持有的鎖定數量。

交易

交易快取使用單階段提交和兩階段提交協定來完成交易。這些指標會追蹤操作持續時間。

PESSIMISTIC 鎖定模式使用單階段提交，並且不會建立提交請求。
在健全的叢集中，回滾次數應保持為零。死鎖應該很少發生，但它們會增加回滾次數。
指標 描述

vendor_transactions_prepare_times_seconds_count

準備請求的總數。

vendor_transactions_prepare_times_seconds_sum

所有準備請求的總持續時間。

vendor_transactions_rollback_times_seconds_count

回滾請求的總數。

vendor_transactions_rollback_times_seconds_sum

所有回滾請求的總持續時間。

vendor_transactions_commit_times_seconds_count

提交請求的總數。

vendor_transactions_commit_times_seconds_sum

所有提交請求的總持續時間。
當啟用直方圖時，可以使用百分位數儲存桶。這些對於建立熱圖很有用，但收集和公開百分位數儲存桶可能會對部署效能產生負面影響。

狀態轉移

當節點加入或離開叢集時，會發生狀態轉移。這是平衡儲存的資料並保證所需副本數量的必要步驟。

此操作會增加資源使用量，並且會對整體效能產生負面影響。

指標 描述

vendor_state_transfer_manager_inflight_transactional_segment_count

本機節點從其他節點請求的傳輸中交易區段數量。

vendor_state_transfer_manager_inflight_segment_transfer_count

本機節點從其他節點請求的傳輸中區段數量。

叢集資料複製

叢集資料複製可能是失敗的主要原因。這些指標不僅會報告回應時間（即複製更新所需的時間），還會報告失敗次數。

在健全的叢集中，平均複製時間將保持穩定或變化不大。失敗次數不應增加。
指標 描述

vendor_rpc_manager_replication_count

成功複製的總數。

vendor_rpc_manager_replication_failures

失敗複製的總數。

vendor_rpc_manager_average_replication_time

在叢集中複製資料所花費的平均時間（以毫秒為單位）。

成功率

可以使用表達式來計算複製成功率

(vendor_rpc_manager_replication_count)/(vendor_rpc_manager_replication_count+vendor_rpc_manager_replication_failures)