带有外部 Infinispan 部署的 Keycloak

本文档包含有关 Keycloak 指标的详细信息，这些指标可用于监控部署的性能。

本文档中描述的部署适用于多站点部署。在此架构中，Keycloak 节点使用外部 Infinispan 来存储缓存数据。

如果您的部署未使用外部 Infinispan，请查看 Keycloak 集群部署 指南。

启用 Keycloak 指标

Keycloak 在管理接口端点 /metrics 上公开指标。要启用，请使用构建时选项 --metrics-enabled=true。

在 Kubernetes 集群中，使用 Keycloak 运算符，可以在 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

接收的字节总数。
启用直方图后，即可使用百分位数桶。这些桶可用于创建热图，但收集和公开百分位数桶可能会对部署性能产生负面影响。

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 增加最大缓存大小

事务

事务性缓存使用单阶段提交和两阶段提交协议来完成事务。这些指标跟踪操作的持续时间。

PESSMISTIC 锁定模式使用单阶段提交，不会创建提交请求。
在健康的集群中，回滚次数应保持为零。死锁应该很少发生，但它们会增加回滚次数。
指标 描述

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

所有提交请求的总持续时间。
启用直方图后，即可使用百分位数桶。这些桶可用于创建热图，但收集和公开百分位数桶可能会对部署性能产生负面影响。