红帽全球峰会Observability 指南
第 1 章 使用健康检查跟踪实例状态
通过调用其健康 REST 端点，检查实例是否已完成启动并准备好为请求提供服务。
红帽构建的 Keycloak 构建为支持健康检查而构建。本章论述了如何启用和使用红帽构建的 Keycloak 健康检查。默认情况下，红帽构建的 Keycloak 健康检查会在管理端口 9000 上公开。如需了解更多详细信息 ，请参阅配置管理界面
1.1. Red Hat build of Keycloak 健康检查端点
红帽构建的 Keycloak 会公开 4 个健康端点：
-
/health/live -
/health/ready -
/health/started -
/health
有关每个端点的含义的信息，请参阅 Quarkus SmallRye Health docs。
这些端点在成功或失败时响应 HTTP 状态 200 OK 或 503 Service Unavailable，以及类似如下的 JSON 对象：
成功响应端点，而无需额外的每个检查信息：
{
"status": "UP",
"checks": []
}使用数据库连接信息成功对端点的响应：
{
"status": "UP",
"checks": [
{
"name": "Keycloak database connections health check",
"status": "UP"
}
]
}1.2. 启用健康检查
可以使用构建时间选项 启用健康检查 ：
bin/kc.[sh|bat] build --health-enabled=true默认情况下，不会从健康端点返回任何检查。
1.3. 使用健康检查
建议外部 HTTP 请求监控健康端点。由于从红帽构建的 Keycloak 容器镜像中删除 curl 和其他软件包的安全措施，本地基于命令的监控将无法轻松正常工作。
如果您没有在容器中使用红帽构建的 Keycloak，请使用您要访问健康检查端点的任何信息。
1.3.1. curl
您可以使用简单的 HTTP HEAD 请求来确定红帽构建的 Keycloak 的实时或 就绪状态。curl 是适合此目的的 HTTP 客户端。
如果容器中部署了红帽构建的 Keycloak，您必须因为前面提到的安全措施而从其外部运行此命令。例如：
curl --head -fsS http://localhost:9000/health/ready
如果命令返回状态为 0，则红帽构建的 Keycloak 为 live 或 ready，具体取决于您调用的端点。否则，会出现问题。
1.3.2. Kubernetes
定义一个 HTTP 探测，以便 Kubernetes 可以在外部监控健康端点。不要使用 liveness 命令。
1.3.3. HEALTHCHECK
Containerfile HEALTHCHECK 指令定义了一个命令，它将在运行时定期在容器内执行。Red Hat build of Keycloak 容器没有安装任何 CLI HTTP 客户端。考虑将 curl 安装为额外的 RPM，如 在容器中运行红帽构建的 Keycloak 部分所述。请注意，容器的安全性可能较低。
1.4. 可用的检查
下表显示了可用的检查。
| 检查 | 描述 | 需要指标 |
|---|---|---|
| 数据库 | 返回数据库连接池的状态。 | 是 |
对于某些检查，您还需要启用 Requires Metrics 列指示的指标。要启用指标，请使用 启用了 metrics 的选项，如下所示：
bin/kc.[sh|bat] build --health-enabled=true --metrics-enabled=true1.5. 相关选项
| value | |
|---|---|
|
CLI: |
|
第 2 章 获取指标数据的见解
收集指标以获取运行红帽构建的 Keycloak 实例的状态和活动。
红帽构建的 Keycloak 构建为对指标的支持。本章论述了如何启用和配置服务器指标。
2.1. 启用指标
可以使用构建时间选项 启用指标 ：
bin/kc.[sh|bat] start --metrics-enabled=true2.2. 查询指标
红帽构建的 Keycloak 在管理界面中的以下端点公开指标：
-
/metrics
有关管理界面的更多信息 ，请参阅配置管理界面。端点的响应使用 application/openmetrics-text 内容类型，它基于 Prometheus (OpenMetrics)文本格式。以下是响应的示例：
# HELP base_gc_total Displays the total number of collections that have occurred. This attribute lists -1 if the collection count is undefined for this collector.
# TYPE base_gc_total counter
base_gc_total{name="G1 Young Generation",} 14.0
# HELP jvm_memory_usage_after_gc_percent The percentage of long-lived heap pool used after the last GC event, in the range [0..1]
# TYPE jvm_memory_usage_after_gc_percent gauge
jvm_memory_usage_after_gc_percent{area="heap",pool="long-lived",} 0.0
# HELP jvm_threads_peak_threads The peak live thread count since the Java virtual machine started or peak was reset
# TYPE jvm_threads_peak_threads gauge
jvm_threads_peak_threads 113.0
# HELP agroal_active_count Number of active connections. These connections are in use and not available to be acquired.
# TYPE agroal_active_count gauge
agroal_active_count{datasource="default",} 0.0
# HELP base_memory_maxHeap_bytes Displays the maximum amount of memory, in bytes, that can be used for memory management.
# TYPE base_memory_maxHeap_bytes gauge
base_memory_maxHeap_bytes 1.6781410304E10
# HELP process_start_time_seconds Start time of the process since unix epoch.
# TYPE process_start_time_seconds gauge
process_start_time_seconds 1.675188449054E9
# HELP system_load_average_1m The sum of the number of runnable entities queued to available processors and the number of runnable entities running on the available processors averaged over a period of time
# TYPE system_load_average_1m gauge
system_load_average_1m 4.005859375
...2.3. 后续步骤
请阅读章节，使用指标通过服务级别 调用 和故障排除 监控性能，以查看如何使用指标。
2.4. 相关选项
| value | |
|---|---|
|
CLI: 仅在启用指标时可用 |
|
|
CLI: 仅在启用指标时可用 |
|
|
CLI: 仅在启用指标时可用 | |
|
CLI: |
|
第 3 章 使用事件指标监控用户活动
事件指标提供红帽构建的 Keycloak 实例中用户活动的聚合视图。
目前，只捕获用户事件的指标。例如，您可以监控执行的登录、登录失败或令牌刷新的数量。
指标使用标准指标端点公开，您可以在您自己的指标集合系统中使用它来创建仪表板和警报。
指标报告为每个红帽构建的 Keycloak 实例的计数器。计数器会在实例重启时重置。如果您在一个集群中运行多个实例，则需要从所有实例收集指标并聚合它们以为每个集群视图获取。
3.1. 启用事件指标
要开始收集事件指标，请启用指标并启用用户事件的指标。
以下显示了所需的启动参数：
bin/kc.[sh|bat] start --metrics-enabled=true --event-metrics-user-enabled=true ...
默认情况下，每个域都有单独的指标。要按客户端和身份提供程序划分指标，您可以使用配置选项 event-metrics-user-tags 添加这些指标维度。这对带有少量客户端和 IDP 的安装很有用。对于有大量客户端或 IDP 的安装，我们不建议这样做，因为它会增加红帽构建的 Keycloak 的内存用量，因为它会增加监控系统的负载。
下面显示了如何配置红帽构建的 Keycloak，以破坏所有三个指标维度的指标：
bin/kc.[sh|bat] start ... --event-metrics-user-tags=realm,idp,clientId ...您可以限制红帽构建的 Keycloak 将公开指标的事件。有关可用 事件概述，请参阅有关事件类型的服务器管理指南。
以下示例将收集的事件限制为 LOGIN 和 LOGOUT 事件：
bin/kc.[sh|bat] start ... --event-metrics-user-events=login,logout ...有关收集的指标描述，请参阅 自助提供的指标。
3.2. 相关选项
| value | |
|---|---|
|
CLI: |
|
| wagon
CLI: 仅在启用指标并启用了 user-event-metrics 功能时才可用 |
|
|
CLI: 仅在启用用户事件指标时可用
使用 |
|
|
CLI: 仅在启用用户事件指标时可用 |
|
第 4 章 使用服务级别通知器监控性能
使用服务级别指示器(SLI)和服务级目标(SLO)的用户跟踪性能和可靠性。
Service Level Indicators (SLI)和服务级别目标(SLO)是监控和维护红帽在生产环境中构建的 Keycloak 的性能和可靠性的基本组件。
Google Site Reliability 工程书定义了如下：
- Service Level Indicator (SLI)是对所提供的服务级别的一些方面精心定义的定量度量。
- 服务级别目标(SLO)是由 SLI 测量的服务级别的目标值或值范围。
通过同意它们与利益相关者并跟踪这些，服务所有者可以确保部署与用户的预期一致，以及它们在他们提供的服务上既不是过更好。
4.1. 先决条件
-
需要为 Keycloak 构建启用指标，并且需要将
http-metrics-slos选项设置为测量以下定义的 SLO 的延迟。如需更多详细信息 ，请参阅与指标相关的见解 章节。 - 一个监控系统收集指标数据。以下段落假定使用 Prometheus 或类似的系统来支持 PromQL 查询语言。
4.2. 提供的服务的定义
后续步骤中使用以下服务定义来识别适当的 SLI 和 SLO。它应该捕获其用户观察到的行为。
作为红帽构建的 Keycloak 用户，
- 我想要登录，
- 刷新我的令牌，
- 注销，
因此，我可以使用使用红帽构建的 Keycloak 的应用程序进行身份验证。
4.3. SLI 和 SLO 定义
根据上面的服务描述以及红帽构建的 Keycloak 中提供的指标，以下提供了 SLI 和 SLO 示例。
虽然这些 SLO 独立于实际负载，但预期是因为单个用户在获得缓慢响应时不会关心系统负载。
同时，如果您输入具有利益相关者的服务级别协议(SLA)，因为运行红帽构建的 Keycloak 的负载会导致定义红帽构建的 Keycloak 接收的流量，因为响应时间会延长，错误率可能会随着系统负载增加并达到扩展阈值时增加。
| 特性 | Service Level Indicator | 服务级别目标* | 指标源 |
|---|---|---|---|
| 可用性 | 红帽构建的 Keycloak 能够按照监控系统测量的请求的百分比 | 红帽 Keycloak 的构建应在一个月内可用，时间为 99.9%（每月有44 分钟不可用）。 |
使用 Prometheus |
| latency | 服务器测量的与身份验证相关的 HTTP 请求的响应时间 | 在 30 天内，所有与身份验证相关的请求应比 250 毫秒快。 |
红帽构建的 Keycloak 服务器端指标，以跟踪特定端点的延迟，以及使用 |
| 错误 | 服务器测量导致服务器问题导致的身份验证请求失败 | 身份验证请求的服务器问题造成的错误率应该在 30 天内小于 0.1%。 |
通过过滤标签 |
* 这些 SLO 目标值是一个示例，应该根据您的用例和部署进行定制。
4.4. PromQL 查询
这些是在 Kubernetes 环境中创建的查询示例，用于将 Prometheus 用作监控工具。它们作为蓝图提供，您需要针对不同的运行时或监控环境进行调整。
对于生产环境，您可能想要将这些查询或子查询替换为 记录规则，以确保它们没有使用太多的资源用于警报或实时仪表板。
4.4.1. 可用性
如果红帽构建的 Keycloak 实例可用并响应 Prometheus scrape 请求，则此指标将具有至少一个值，如果服务停机或无法访问，则为 0。
然后，使用 Grafana 等工具显示 30 天时间范围，并可以计算该时间窗中指标的平均值。
count_over_time(
sum (up{
container="keycloak",
namespace="$namespace"
} > 0)[30d:15s]
)
/
count_over_time(vector(1)[30d:15s])
在 Grafana 中，您可以将 30d:15s 替换为 $range:$间隔 到为仪表板选择的时间范围中的计算可用性 SLI。
4.4.2. 身份验证请求的延迟
此 Prometheus 查询计算在 0.25 秒内完成的身份验证请求的百分比，相对于红帽构建的 Keycloak 端点的所有身份验证请求，并在过去 30 天内针对特定的命名空间和 pod。
这个示例要求红帽构建 Keycloak 配置 http-metrics-slos 的值 250，表示应记录超过 250 ms 的请求的存储桶。将 http-metrics-histograms-enabled 设置为 true 会捕获额外的存储桶，这有助于进行性能故障排除。
sum(
rate(
http_server_requests_seconds_bucket{
uri=~"/realms/{realm}/protocol/{protocol}.*|/realms/{realm}/login-actions.*",
le="0.25",
container="keycloak",
namespace="$namespace"}
[30d]
)
) without (le,uri,status,outcome,method,pod,instance)
/
sum(
rate(
http_server_requests_seconds_count{
uri=~"/realms/{realm}/protocol/{protocol}.*|/realms/{realm}/login-actions.*",
container="keycloak",
namespace="$namespace"}
[30d]
)
) without (le,uri,status,outcome,method,pod,instance)
在 Grafana 中，您可以在为仪表板选择的时间范围中将 30d 替换为 $_range 到 compute latency SLI。
4.4.3. 身份验证请求的错误
此 Prometheus 查询计算过去 30 天内返回所有身份验证请求的服务器端错误的身份验证请求百分比。
sum(
rate(
http_server_requests_seconds_count{
uri=~"/realms/{realm}/protocol/{protocol}.*|/realms/{realm}/login-actions.*",
outcome="SERVER_ERROR",
container="keycloak",
namespace="$namespace"}
[30d]
)
) without (le,uri,status,outcome,method,pod,instance)
/
sum(
rate(
http_server_requests_seconds_count{
uri=~"/realms/{realm}/protocol/{protocol}.*|/realms/{realm}/login-actions.*",
container="keycloak",
namespace="$namespace"}
[30d]
)
) without (le,uri,status,outcome,method,pod,instance)
在 Grafana 中，您可以在为仪表板选择的时间范围中将 30d 替换为 $_range 到 compute 错误 SLI。
4.5. 深入阅读
第 5 章 使用指标进行故障排除
使用指标对错误和性能问题进行故障排除。
对于运行红帽构建的 Keycloak 部署，务必要了解系统如何执行以及是否满足您的服务级别目标(SLO)。有关 SLO 的详情，请使用服务级别指示器继续监控性能。
本指南将提供回答问题的指示："当不满足 SLO 时，我该怎么做？"
Red Hat build of Keycloak 由多个组件组成，其中其中一个组件可能会将您的服务级别指示器移到不正常的数字中。
以下示例中演示了本指南提供的指导：
观察： 不满足延迟服务级别目标。
指示问题的指标 ：
- 红帽构建的 Keycloak 的数据库连接池通常会耗尽，有线程排队来从池中检索连接。
-
红帽构建的 Keycloak
的用户缓存命中率低于 5%。这意味着只有 20 个用户搜索可以从缓存中获取用户数据，其余则需要从数据库中加载它。
建议可能的缓解方案：
-
将用户缓存大小增加到更高数字，这会减少对数据库的读取数量。 - 增加连接池中的连接数量。这将需要检查您的数据库的指标，并将其调优为更高的负载，例如通过增加可用处理器的数量。
- 本指南重点介绍红帽构建的 Keycloak 指标。数据库本身故障排除不超出范围。
- 本指南提供常规指导。您应该始终通过将问题的指标与旧配置和新配置进行比较来确认配置更改。
以下指标的 Grafana 仪表板可在仪表板中 可视化活动 一章中找到。
5.1. 红帽构建的 Keycloak 密钥指标列表
- 自我提供的指标
- JVM 指标
- 数据库指标
- HTTP 指标
单一站点指标（没有外部 Data Grid）
多站点指标（如多站点部署中所述）
5.2. 自我提供的指标
了解红帽构建的 Keycloak 提供的关键指标。
这是使用指标进行故障排除 一章的一部分。
5.2.1. 先决条件
- 需要为红帽构建的 Keycloak 启用指标。如需更多详细信息 ，请参阅指标数据 的见解章节。
- 一个监控系统收集指标数据。
5.2.2. 指标
5.2.2.1. 用户事件指标
默认禁用用户事件指标。如需有关如何启用它们以及如何配置记录哪些标签的信息，请参阅使用事件指标监控用户活动。
| 指标 | 描述 |
|---|---|
|
| 计算发生的用户事件。 |
Tags
默认情况下，标签 client_id 和 idp 被禁用，以避免过于高。
realm- realm
client_id- 客户端 ID
idp- 身份供应商
event-
用户事件，如
登录或注销。有关可用 事件概述，请参阅有关事件类型的服务器管理指南。 错误-
特定于事件的错误，如事件登录的
invalid_user_credentials。如果没有发生错误，则空字符串。
以下是指标端点提供的响应示例：
# HELP keycloak_user_events_total Keycloak user events
# TYPE keycloak_user_events_total counter
keycloak_user_events_total{client_id="security-admin-console",error="",event="code_to_token",idp="",realm="master",} 1.0
keycloak_user_events_total{client_id="security-admin-console",error="",event="login",idp="",realm="master",} 1.0
keycloak_user_events_total{client_id="security-admin-console",error="",event="logout",idp="",realm="master",} 1.0
keycloak_user_events_total{client_id="security-admin-console",error="invalid_user_credentials",event="login",idp="",realm="master",} 1.05.2.2.2. 密码哈希
| 指标 | 描述 |
|---|---|
|
| 计算密码哈希验证数. |
Tags
realm- realm
algorithm-
用于哈希密码的算法，如
argon2 hashing_strength-
字符串注意哈希算法的强度，例如，根据算法的迭代数量。例如：
Argon2id-1.3[m=7168,t=5,p=1] 结果密码验证结果。可能的值：
valid- 密码正确
invalid- 密码不正确
错误- 创建密码哈希时出错
要配置可用的标签，请将以逗号分隔的标签名称列表提供给以下选项 spi-credential-keycloak-password-validations-counter-tags。默认情况下，所有标签都已启用。
以下是指标端点提供的响应示例：
# HELP keycloak_credentials_password_hashing_validations_total Password validations
# TYPE keycloak_credentials_password_hashing_validations_total counter
keycloak_credentials_password_hashing_validations_total{algorithm="argon2",hashing_strength="Argon2id-1.3[m=7168,t=5,p=1]",outcome="valid",realm="realm-0",} 39949.05.2.3. 后续步骤
使用指标返回到故障排除，或继续到 JVM 指标。
5.3. JVM 指标
使用 JVM 指标观察红帽构建的 Keycloak 的性能。
这是使用指标进行故障排除 一章的一部分。
5.3.1. 先决条件
- 需要为红帽构建的 Keycloak 启用指标。如需更多详细信息 ，请参阅指标数据 的见解章节。
- 一个监控系统收集指标数据。
5.3.2. 指标
5.3.2.1. JVM 信息
| 指标 | 描述 |
|---|---|
|
| 有关 JVM 的信息，如版本、运行时和供应商。 |
5.3.2.2. 堆内存用量
| 指标 | 描述 |
|---|---|
|
| JVM 已提交使用的内存量，反映出保证 JVM 可以使用的分配内存部分。 |
|
| JVM 当前使用的内存量，指示应用和 JVM 内部的实际内存消耗。 |
5.3.2.3. 垃圾回收
| 指标 | 描述 |
|---|---|
|
| 由于特定原因，垃圾回收的最大持续时间（以秒为单位）暂停 JVM 体验，这有助于快速区分 GC （次，主）暂停的类型。 |
|
| 垃圾回收中花费的总累计时间暂停，表示 GC 暂停 JVM 中应用程序性能的影响。 |
|
| 计算垃圾回收暂停事件总数，帮助评估 JVM 中 GC 暂停的频率。 |
|
| 对垃圾回收所花费的 CPU 时间的百分比，表示 GC 对 JVM 应用性能的影响。它指的是专用于执行垃圾回收(GC)操作的总 CPU 处理时间比例，而不是运行应用程序代码或执行其他任务。此指标有助于确定 GC 引入了多少开销，影响红帽构建的 Keycloak JVM 的整体性能。 |
5.3.2.4. Kubernetes 中的 CPU 用量
| 指标 | 描述 |
|---|---|
|
| 容器消耗的累积 CPU 时间（以 core-seconds 为单位）。 |
5.3.3. 后续步骤
使用指标返回故障排除，或继续 数据库指标。
5.4. 数据库指标
使用指标描述红帽构建的 Keycloak 与数据库的连接。
这是使用指标进行故障排除 一章的一部分。
5.4.1. 先决条件
- 需要为红帽构建的 Keycloak 启用指标。如需更多详细信息 ，请参阅指标数据 的见解章节。
- 一个监控系统收集指标数据。
5.4.2. 数据库连接池指标
配置红帽构建的 Keycloak 以使用固定大小数据库连接池。如需更多信息，请参阅数据库连接池 的概念 章节。
如果等待数据库连接的线程数量很高，增加数据库连接池大小并非始终是最佳选择。它可能会过载数据库，然后会成为瓶颈。请考虑以下选项：
-
使用
http-pool-max-threads选项减少 HTTP worker 线程数量，使其与可用数据库连接匹配，从而减少红帽构建的 Keycloak 中的竞争和资源使用情况，并增加吞吐量。 -
检查在数据库上执行了哪些数据库语句。例如，如果您看到许多有关正在获取的客户端和服务器的信息，并且用户和域缓存已满，这可能表明是增加这些缓存的大小的时间，并查看这是否减少了您的数据库负载。
| 指标 | 描述 |
|---|---|
|
| 空闲的数据库连接。 |
|
| 持续事务中使用的数据库连接。 |
|
| 等待数据库连接可用的线程。 |
5.4.3. 后续步骤
使用指标返回到故障排除，或继续 HTTP 指标。
5.5. HTTP 指标
使用指标监控红帽构建的 Keycloak HTTP 请求处理。
这是使用指标进行故障排除 一章的一部分。
5.5.1. 先决条件
- 需要为红帽构建的 Keycloak 启用指标。如需更多详细信息 ，请参阅指标数据 的见解章节。
- 一个监控系统收集指标数据。
5.5.2. 指标
5.5.2.1. 处理时间
处理时间由这些指标公开，以监控红帽构建的 Keycloak 性能以及处理请求所需的时间。
在健康的集群中，平均处理时间将保持稳定。处理时间高峰或增加时间可能是一些节点负载的早期签名。
Tags
方法- HTTP 方法。
结果- 更为通用的结果标签。
status- HTTP 状态代码。
uri- 请求的 URI。
| 指标 | 描述 |
|---|---|
|
| 处理的请求总数。 |
|
| 处理的所有请求的总持续时间。 |
您可以通过将 http-metrics-histograms-enabled 设置为 true 来启用此指标的直方图，并使用选项 http-metrics-slos 为服务级别目标添加额外的存储桶。
启用直方图后，可以使用百分比的存储桶。它们可用于创建 heat 映射并分析延迟，仍然收集并公开百分比存储桶，这会增加监控系统的负载。
5.5.2.2. 活跃请求
当前活跃的请求数量也可用。
| 指标 | 描述 |
|---|---|
|
| 当前活跃的请求数量 |
5.5.2.3. bandwidth
以下指标有助于监控红帽构建的 Keycloak 使用的带宽和消耗流量，并由收到或发送的请求和响应使用。
| 指标 | 描述 |
|---|---|
|
| 发送的响应总数。 |
|
| 发送的字节数。 |
|
| 收到的请求总数。 |
|
| 收到的字节数。 |
启用直方图后，可以使用百分比的存储桶。它们可用于创建 heat 映射并分析延迟，仍然收集并公开百分比存储桶，这会增加监控系统的负载。
5.5.3. 后续步骤
- 对于单站点部署，请执行集群指标，
- 对于多个站点部署，对于多站点部署，请继续嵌入式 Infinispan 指标
5.5.4. 相关选项
| value | |
|---|---|
|
CLI: 仅在启用指标时可用 |
|
|
CLI: 仅在启用指标时可用 |
5.6. 集群指标
使用指标来监控红帽构建的 Keycloak 节点之间的通信。
这是使用指标进行故障排除 一章的一部分。
5.6.1. 先决条件
- 需要为红帽构建的 Keycloak 启用指标。如需更多详细信息 ，请参阅指标数据 的见解章节。
- 一个监控系统收集指标数据。
5.6.2. 指标
部署多个红帽构建的 Keycloak 节点允许负载分布，但这需要节点间的通信。本节论述了用于监控红帽构建的 Keycloak 之间的通信的指标，以识别可能的错误。
这只适用于单一站点部署。当使用多个 站点时，如多站点部署 中所述，红帽构建的 Keycloak 节点不会一起集群，因此它们之间没有直接通信。
全局标签
cluster=<name>- 集群名称。如果要收集来自多个集群的指标，此标签可帮助识别它们所属的位置。
node=<node>- 报告指标的节点名称。
所有前缀为 vendor_jgroups_ 的指标名称都仅用于故障排除和调试目的。指标名称可在不进一步通知的情况下更改红帽构建的 Keycloak 版本。因此，我们建议不要在仪表板或监控和警报中使用它们。
5.6.2.1. 响应时间
以下指标公开远程请求的响应时间。响应时间在两个节点之间测量，包括处理时间。所有请求都由这些指标测量，响应时间应保持在集群生命周期的稳定状态。
在健康的集群中，响应时间保持稳定。响应时间的增加可能会表示降级集群或负载过重的节点。
Tags
node=<node>- 它标识发送者节点。
target_node=<node>- 它标识接收器节点。
| 指标 | 描述 |
|---|---|
|
| 向接收器节点同步请求数量。 |
|
| 向接收器节点同步请求的总持续时间 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.6.2.2. bandwidth
红帽构建的 Keycloak 接收和发送的所有字节都由这些指标收集。另外，所有内部消息作为心跳也计算出来。它们允许计算每个节点当前使用的带宽。
指标名称取决于使用的 JGroups 传输协议。
| 指标 | 协议 | 描述 |
|---|---|---|
|
|
| 节点接收的字节数。 |
|
|
| |
|
|
| |
|
|
| 节点发送的字节数。 |
|
|
| |
|
|
|
5.6.2.3. 线程池
监控线程池大小是节点负载过重的良好指示器。收到的所有请求都会添加到线程池中，并在它已满后，请求将被丢弃。重新传输机制可确保与增加资源使用量进行可靠的通信。
在健康的集群中，线程池永远不会接近其最大大小（默认为 200 个线程）。
线程池指标不适用于虚拟线程。使用 OpenJDK 21 运行时，虚拟线程会被默认启用。
指标名称取决于使用的 JGroups 传输协议。默认传输协议是 TCP。
| 指标 | 协议 | 描述 |
|---|---|---|
|
|
| 线程池中当前的线程数。 |
|
|
| |
|
|
| |
|
|
| 池中同时存在的最大线程数量。 |
|
|
| |
|
|
|
5.6.2.4. 流控制
流控制负责调整消息发送方的速度，到最慢的接收器的速度。这通过基于信用的系统实施，在发送时每个发送者都会减少其学分。发送者块当学号低于 0 时，只有在它从接收器收到回复时，才会恢复发送消息。
以下指标显示阻塞的消息数量以及平均阻塞时间。当值与零不同时，可能会表示接收方过载，并可能会降低集群性能。
每个节点有两个独立的流控制协议，UFC 用于单播消息，MFC 用于多播消息。
健康的集群显示所有指标的值为零。
| 指标 | 描述 |
|---|---|
|
| 流控制的次数会阻止单播消息的发送者。 |
|
| 尝试发送单播消息时，在流控制中平均时间被阻止（以 ms 为单位）。 |
|
| 流控制的次数会阻止多播消息的发送者。 |
|
| 尝试发送多播消息时，在流控制中平均时间会阻塞（以 ms 为单位）。 |
5.6.2.5. 重新传输
JGroups 提供可靠的消息交付。当网络中丢弃消息时，或者接收方无法处理消息时，需要重新传输。重新传输会增加资源使用量，通常是过载系统的信号。
Random Early Drop (RED)监控发送者队列。当队列接近满时，消息将被丢弃，且必须重新传输。它可防止整个发送者队列阻止线程。
健康的集群显示所有指标的值为零。
| 指标 | 描述 |
|---|---|
|
| 重新传输的消息数量。 |
|
| 发送者丢弃的消息总数。 |
|
| 发送者丢弃的所有消息的百分比。 |
5.6.2.6. 网络分区
5.6.2.6.1. 集群大小
集群大小指标报告集群中存在的节点数量。如果不同，这可能表示节点正在加入、关闭或最糟糕的情况，则网络分区会发生。
健康的集群显示所有节点中的值相同。
| 指标 | 描述 |
|---|---|
|
| 集群中的节点数。 |
5.6.2.6.2. 网络分区事件
由于各种原因，集群中的网络分区可能会发生。这些指标不会帮助预测网络分割，但会发出信号，并且集群已合并。
健康的集群显示此指标的值为零。
| 指标 | 描述 |
|---|---|
|
| 检测到网络分割并修复的时间。 |
5.6.3. 后续步骤
使用指标返回故障排除，或继续 为单站点部署进行嵌入式 Infinispan 指标。
5.7. 单一站点部署的嵌入式 Infinispan 指标
使用指标来监控缓存健康和集群复制。
这是使用指标进行故障排除 一章的一部分。
5.7.1. 先决条件
- 需要为红帽构建的 Keycloak 启用指标。如需更多详细信息 ，请参阅指标数据 的见解章节。
- 一个监控系统收集指标数据。
5.7.2. 指标
全局标签
cache=<name>- 缓存名称。
5.7.2.1. Size
使用这两个指标监控缓存中的条目数量。如果集群缓存，每个条目都有一个所有者节点，以及不同节点的零个或多个备份副本。
总和唯一的条目大小指标，以获取集群总数。
| 指标 | 描述 |
|---|---|
|
| 节点存储的条目数量，包括备份副本。 |
|
| 节点存储的大约数量，不包括备份副本。 |
5.7.2.2. 数据访问
以下指标监控缓存访问，如读取、写入及其持续时间。
5.7.2.2.1. 存储
存储操作是一个写入操作，用于写入或更新存储在缓存中的值。
| 指标 | 描述 |
|---|---|
|
| 存储请求的总数。 |
|
| 所有存储请求的总持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.7.2.2.2. 读取
读取操作从缓存中读取值。它被分成两个组，如果找到了值，则按 键，如果未找到，则未命中。
| 指标 | 描述 |
|---|---|
|
| 读取点击请求的总数。 |
|
| 所有读取点击请求的持续时间。 |
|
| 读取丢失请求的总数。 |
|
| 所有读取丢失请求的持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.7.2.2.3. 删除
删除操作从缓存中删除值。它将分成两个组，一个点击（如果存在值）和miss （如果值不存在）。
| 指标 | 描述 |
|---|---|
|
| 删除 hits 请求的总数。 |
|
| 所有删除 hits 请求的总持续时间。 |
|
| 删除丢失的请求总数。 |
|
| 所有删除丢失请求的持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
对于用户 和域 缓存，数据库无效转换为删除操作。这些指标是修改数据库实体的频率的良好指示符，因此从缓存中删除了数据库实体。
读和删除操作的命中率
表达式可用于计算 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)5.7.2.2.4. Eviction
驱除是限制缓存大小的流程，并在满时删除条目，以便缓存新条目。当红帽构建的 Keycloak 将数据库实体缓存 用户、域 和授权 时，数据库访问总是继续进行驱除事件。
| 指标 | 描述 |
|---|---|
|
| 驱除事件总数。 |
驱除率
快速增加驱除和非常高的数据库 CPU 使用量 意味着用户 或域 缓存对于平滑的红帽 Keycloak 操作而言太小，因为数据需要从数据库重新加载，这会减慢响应速度。如果有足够的内存可用，请考虑使用 CLI 选项 cache-embedded-users-max-count 或 cache-embedded-realms-max-count来增加最大缓存大小
5.7.2.3. 锁定
写入和删除操作会保存锁，直到值在本地集群中复制并复制到远程站点。
在健康的集群中，锁定的数量应该保持恒定的状态，但死锁可能会创建临时激增。
| 指标 | 描述 |
|---|---|
|
| 此节点当前持有的锁定数。 |
5.7.2.4. Transactions
事务缓存同时使用 One-Phase-Commit 和 Two-Phase-Commit 协议来完成事务。这些指标跟踪操作持续时间。
PESSMISTIC 锁定模式使用 One-Phase-Commit，不创建提交请求。
在健康的集群中，回滚的数量应该保持零。死锁应该比较罕见，但会增加回滚数量。
| 指标 | 描述 |
|---|---|
|
| 准备请求总数。 |
|
| 所有准备请求的总持续时间。 |
|
| 回滚请求总数。 |
|
| 所有回滚请求的总持续时间。 |
|
| 提交请求的总数。 |
|
| 所有提交请求的总持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.7.2.5. 状态传输
当节点加入或离开集群时，会发生状态转移。需要平衡存储的数据并保证所需的副本数。
此操作会增加资源使用量，它会影响整体性能。
| 指标 | 描述 |
|---|---|
|
| 来自其他节点的本地节点的 in-flight 事务片段数。 |
|
| 从其他节点请求的本地节点的数量。 |
5.7.2.6. 集群数据复制
集群数据复制可以是故障的主要来源。这些指标不仅报告响应时间，即复制更新所需的时间，还要报告故障。
在健康的集群中，平均复制时间为稳定或稍有不同。不应增加的故障数量。
| 指标 | 描述 |
|---|---|
|
| 成功复制总数。 |
|
| 失败的复制总数。 |
|
| 在集群中复制数据的平均时间（以毫秒为单位）。 |
成功比率
表达式可用于计算复制成功比率：
(vendor_rpc_manager_replication_count)
/
(vendor_rpc_manager_replication_count
+ vendor_rpc_manager_replication_failures)5.7.3. 后续步骤
5.8. 用于多站点部署的嵌入式 Infinispan 指标
使用指标来监控缓存健康状况。
这是使用指标进行故障排除 一章的一部分。
5.8.1. 先决条件
- 需要为红帽构建的 Keycloak 启用指标。如需更多详细信息 ，请参阅指标数据 的见解章节。
- 一个监控系统收集指标数据。
5.8.2. 指标
全局标签
cache=<name>- 缓存名称。
5.8.2.1. Size
使用这两个指标监控缓存中的条目数量。如果集群缓存，每个条目都有一个所有者节点，以及不同节点的零个或多个备份副本。
总和唯一的条目大小指标，以获取集群总数。
| 指标 | 描述 |
|---|---|
|
| 节点存储的条目数量，包括备份副本。 |
|
| 节点存储的大约数量，不包括备份副本。 |
5.8.2.2. 数据访问
以下指标监控缓存访问，如读取、写入及其持续时间。
5.8.2.2.1. 存储
存储操作是一个写入操作，用于写入或更新存储在缓存中的值。
| 指标 | 描述 |
|---|---|
|
| 存储请求的总数。 |
|
| 所有存储请求的总持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.8.2.2.2. 读取
读取操作从缓存中读取值。它被分成两个组，如果找到了值，则按 键，如果未找到，则未命中。
| 指标 | 描述 |
|---|---|
|
| 读取点击请求的总数。 |
|
| 所有读取点击请求的持续时间。 |
|
| 读取丢失请求的总数。 |
|
| 所有读取丢失请求的持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.8.2.2.3. 删除
删除操作从缓存中删除值。它将分成两个组，一个点击（如果存在值）和miss （如果值不存在）。
| 指标 | 描述 |
|---|---|
|
| 删除 hits 请求的总数。 |
|
| 所有删除 hits 请求的总持续时间。 |
|
| 删除丢失的请求总数。 |
|
| 所有删除丢失请求的持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
对于用户 和域 缓存，数据库无效转换为删除操作。这些指标是修改数据库实体的频率的良好指示符，因此从缓存中删除了数据库实体。
读和删除操作的命中率
表达式可用于计算 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)5.8.2.2.4. Eviction
驱除是限制缓存大小的流程，并在满时删除条目，以便缓存新条目。当红帽构建的 Keycloak 将数据库实体缓存 用户、域 和授权 时，数据库访问总是继续进行驱除事件。
| 指标 | 描述 |
|---|---|
|
| 驱除事件总数。 |
驱除率
快速增加驱除和非常高的数据库 CPU 使用量 意味着用户 或域 缓存对于平滑的红帽 Keycloak 操作而言太小，因为数据需要从数据库重新加载，这会减慢响应速度。如果有足够的内存可用，请考虑使用 CLI 选项 cache-embedded-users-max-count 或 cache-embedded-realms-max-count来增加最大缓存大小
5.8.2.3. Transactions
事务缓存同时使用 One-Phase-Commit 和 Two-Phase-Commit 协议来完成事务。这些指标跟踪操作持续时间。
PESSMISTIC 锁定模式使用 One-Phase-Commit，不创建提交请求。
在健康的集群中，回滚的数量应该保持零。死锁应该比较罕见，但会增加回滚数量。
| 指标 | 描述 |
|---|---|
|
| 准备请求总数。 |
|
| 所有准备请求的总持续时间。 |
|
| 回滚请求总数。 |
|
| 所有回滚请求的总持续时间。 |
|
| 提交请求的总数。 |
|
| 所有提交请求的总持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.8.3. 后续步骤
使用指标返回故障排除，或继续 外部 Data Grid 指标。
5.9. 外部网格指标
使用指标来监控外部 Data Grid 性能。
这是使用指标进行故障排除 一章的一部分。
5.9.1. 先决条件
5.9.1.1. 启用的 Data Grid 服务器指标
Data Grid 在端点 /metrics 中公开指标。默认情况下启用它们。我们建议启用属性 name-as-tags，因为它使指标名称独立于缓存名称。
要在 Data Grid 服务器中配置指标，就像以下 XML 所示启用。
infinispan.xml
<infinispan>
<cache-container statistics="true">
<metrics gauges="true" histograms="false" name-as-tags="true" />
</cache-container>
</infinispan>
在 Kubernetes 中使用 Data Grid Operator，可以使用带有自定义配置的 ConfigMap 来启用指标。下面是一个示例。
ConfigMap
apiVersion: v1
kind: ConfigMap
metadata:
name: cluster-config
data:
infinispan-config.yaml: >
infinispan:
cacheContainer:
metrics:
gauges: true
namesAsTags: true
histograms: falseinfinispan.yaml CR
apiVersion: infinispan.org/v1
kind: Infinispan
metadata:
name: infinispan
annotations:
infinispan.org/monitoring: 'true'
spec:
configMapName: "cluster-config" 其他信息可在 Infinispan 文档和 Infinispan 操作器 文档中找到。
5.9.2. 集群和网络
这部分论述了监控 Data Grid 节点之间的通信的指标，以识别可能的网络问题。
全局标签
cluster=<name>- 集群名称。如果要收集来自多个集群的指标，此标签可帮助识别它们所属的位置。
node=<node>- 报告指标的节点名称。
所有前缀为 vendor_jgroups_ 的指标名称都仅用于故障排除和调试目的。指标名称可在不进一步通知的情况下更改红帽构建的 Keycloak 版本。因此，我们建议不要在仪表板或监控和警报中使用它们。
5.9.2.1. 响应时间
以下指标公开远程请求的响应时间。响应时间在两个节点之间测量，包括处理时间。所有请求都由这些指标测量，响应时间应保持在集群生命周期的稳定状态。
在健康的集群中，响应时间保持稳定。响应时间的增加可能会表示降级集群或负载过重的节点。
Tags
node=<node>- 它标识发送者节点。
target_node=<node>- 它标识接收器节点。
| 指标 | 描述 |
|---|---|
|
| 向接收器节点同步请求数量。 |
|
| 向接收器节点同步请求的总持续时间 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.9.2.2. bandwidth
Data Grid 接收和发送的所有字节都由这些指标收集。另外，所有内部消息作为心跳也计算出来。它们允许计算每个节点当前使用的带宽。
指标名称取决于使用的 JGroups 传输协议。
| 指标 | 协议 | 描述 |
|---|---|---|
|
|
| 节点接收的字节数。 |
|
|
| |
|
|
| |
|
|
| 节点发送的字节数。 |
|
|
| |
|
|
|
5.9.2.3. 线程池
监控线程池大小是节点负载过重的良好指示器。收到的所有请求都会添加到线程池中，并在它已满后，请求将被丢弃。重新传输机制可确保与增加资源使用量进行可靠的通信。
在健康的集群中，线程池永远不会接近其最大大小（默认为 200 个线程）。
线程池指标不适用于虚拟线程。使用 OpenJDK 21 运行时，虚拟线程会被默认启用。
指标名称取决于使用的 JGroups 传输协议。默认传输协议是 TCP。
| 指标 | 协议 | 描述 |
|---|---|---|
|
|
| 线程池中当前的线程数。 |
|
|
| |
|
|
| |
|
|
| 池中同时存在的最大线程数量。 |
|
|
| |
|
|
|
5.9.2.4. 流控制
流控制负责调整消息发送方的速度，到最慢的接收器的速度。这通过基于信用的系统实施，在发送时每个发送者都会减少其学分。发送者块当学号低于 0 时，只有在它从接收器收到回复时，才会恢复发送消息。
以下指标显示阻塞的消息数量以及平均阻塞时间。当值与零不同时，可能会表示接收方过载，并可能会降低集群性能。
每个节点有两个独立的流控制协议，UFC 用于单播消息，MFC 用于多播消息。
健康的集群显示所有指标的值为零。
| 指标 | 描述 |
|---|---|
|
| 流控制的次数会阻止单播消息的发送者。 |
|
| 尝试发送单播消息时，在流控制中平均时间被阻止（以 ms 为单位）。 |
|
| 流控制的次数会阻止多播消息的发送者。 |
|
| 尝试发送多播消息时，在流控制中平均时间会阻塞（以 ms 为单位）。 |
5.9.2.5. 重新传输
JGroups 提供可靠的消息交付。当网络中丢弃消息时，或者接收方无法处理消息时，需要重新传输。重新传输会增加资源使用量，通常是过载系统的信号。
Random Early Drop (RED)监控发送者队列。当队列接近满时，消息将被丢弃，且必须重新传输。它可防止整个发送者队列阻止线程。
健康的集群显示所有指标的值为零。
| 指标 | 描述 |
|---|---|
|
| 重新传输的消息数量。 |
|
| 发送者丢弃的消息总数。 |
|
| 发送者丢弃的所有消息的百分比。 |
5.9.2.6. 网络分区
5.9.2.6.1. 集群大小
集群大小指标报告集群中存在的节点数量。如果不同，这可能表示节点正在加入、关闭或最糟糕的情况，则网络分区会发生。
健康的集群显示所有节点中的值相同。
| 指标 | 描述 |
|---|---|
|
| 集群中的节点数。 |
5.9.2.6.2. 跨站点状态
跨站点状态向其他站点报告连接状态。如果是在线，则返回 1 值（如果离线）或 0 ( 如果离线)。在状态未知的节点上使用 2 值；不是所有节点都建立到远程站点的连接，且不包含此信息。
健康的集群显示一个大于零的值。
| 指标 | 描述 |
|---|---|
|
| 单一站点状态（如果在线则为 1）。 |
Tags
site=<name>- 目标站点的名称。
5.9.2.6.3. 网络分区事件
由于各种原因，集群中的网络分区可能会发生。这些指标不会帮助预测网络分割，但会发出信号，并且集群已合并。
健康的集群显示此指标的值为零。
| 指标 | 描述 |
|---|---|
|
| 检测到网络分割并修复的时间。 |
5.9.3. Data Grid Caches
本节中的指标有助于监控 Data Grid 缓存健康和集群复制。
全局标签
cache=<name>- 缓存名称。
5.9.3.1. Size
使用这两个指标监控缓存中的条目数量。如果集群缓存，每个条目都有一个所有者节点，以及不同节点的零个或多个备份副本。
总和唯一的条目大小指标，以获取集群总数。
| 指标 | 描述 |
|---|---|
|
| 节点存储的条目数量，包括备份副本。 |
|
| 节点存储的大约数量，不包括备份副本。 |
5.9.3.2. 数据访问
以下指标监控缓存访问，如读取、写入及其持续时间。
5.9.3.2.1. 存储
存储操作是一个写入操作，用于写入或更新存储在缓存中的值。
| 指标 | 描述 |
|---|---|
|
| 存储请求的总数。 |
|
| 所有存储请求的总持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.9.3.2.2. 读取
读取操作从缓存中读取值。它被分成两个组，如果找到了值，则按 键，如果未找到，则未命中。
| 指标 | 描述 |
|---|---|
|
| 读取点击请求的总数。 |
|
| 所有读取点击请求的持续时间。 |
|
| 读取丢失请求的总数。 |
|
| 所有读取丢失请求的持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.9.3.2.3. 删除
删除操作从缓存中删除值。它将分成两个组，一个点击（如果存在值）和miss （如果值不存在）。
| 指标 | 描述 |
|---|---|
|
| 删除 hits 请求的总数。 |
|
| 所有删除 hits 请求的总持续时间。 |
|
| 删除丢失的请求总数。 |
|
| 所有删除丢失请求的持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.9.3.3. 锁定
写入和删除操作会保存锁，直到值在本地集群中复制并复制到远程站点。
在健康的集群中，锁定的数量应该保持恒定的状态，但死锁可能会创建临时激增。
| 指标 | 描述 |
|---|---|
|
| 此节点当前持有的锁定数。 |
5.9.3.4. Transactions
事务缓存同时使用 One-Phase-Commit 和 Two-Phase-Commit 协议来完成事务。这些指标跟踪操作持续时间。
PESSMISTIC 锁定模式使用 One-Phase-Commit，不创建提交请求。
在健康的集群中，回滚的数量应该保持零。死锁应该比较罕见，但会增加回滚数量。
| 指标 | 描述 |
|---|---|
|
| 准备请求总数。 |
|
| 所有准备请求的总持续时间。 |
|
| 回滚请求总数。 |
|
| 所有回滚请求的总持续时间。 |
|
| 提交请求的总数。 |
|
| 所有提交请求的总持续时间。 |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.9.3.5. 状态传输
当节点加入或离开集群时，会发生状态转移。需要平衡存储的数据并保证所需的副本数。
此操作会增加资源使用量，它会影响整体性能。
| 指标 | 描述 |
|---|---|
|
| 来自其他节点的本地节点的 in-flight 事务片段数。 |
|
| 从其他节点请求的本地节点的数量。 |
5.9.3.6. 集群数据复制
集群数据复制可以是故障的主要来源。这些指标不仅报告响应时间，即复制更新所需的时间，还要报告故障。
在健康的集群中，平均复制时间为稳定或稍有不同。不应增加的故障数量。
| 指标 | 描述 |
|---|---|
|
| 成功复制总数。 |
|
| 失败的复制总数。 |
|
| 在集群中复制数据的平均时间（以毫秒为单位）。 |
成功比率
表达式可用于计算复制成功比率：
(vendor_rpc_manager_replication_count)
/
(vendor_rpc_manager_replication_count
+ vendor_rpc_manager_replication_failures)5.9.3.7. 跨站点数据复制
与集群数据复制一样，本节中的指标会测量将数据复制到其他站点所需的时间。
在健康的集群中，平均跨站点复制时间将稳定或很少的差异。
Tags
site=<name>- 表示接收的站点。
| 指标 | 描述 |
|---|---|
|
| 跨站点请求的总数。 |
|
| 所有跨站点请求的总持续时间。 |
|
| 跨站点请求的总数。此指标比每个站点计数器更为详细。 |
|
| 所有跨站点请求的总持续时间。此指标在各站点持续时间内更为详细。 |
|
| 此节点处理的跨站点请求总数。此指标比每个站点计数器更为详细。 |
|
|
站点状态。值 1 表示它在线。这个值对 Data Grid CLI 命令进行了响应， |
启用直方图后，将有百分比的存储桶可用。它们可用于创建 heat 映射，但收集和公开百分比存储桶可能会对部署性能造成负面影响。
5.9.4. 后续步骤
第 6 章 使用追踪进行根本原因分析
使用 OpenTelementry tracing 在请求生命周期内记录信息，以识别红帽构建的 Keycloak 和连接的系统的延迟和错误的根情况。
本章解释了如何使用 OpenTelemetry (OTel)在 Red Hat build of Keycloak (OTel)中启用和配置分布式追踪。追踪允许对每个请求的生命周期进行详细监控，这有助于快速识别和诊断问题，从而更有效地调试和维护。
它提供了对性能瓶颈的宝贵见解，有助于优化系统的整体效率和系统边界。Red Hat build of Keycloak 使用受支持的 Quarkus OTel 扩展，它提供平稳集成和公开应用程序 trace。
6.1. 启用追踪
可以使用构建时间选项 tracing-enabled 启用公开的 trace，如下所示：
bin/kc.[sh|bat] start --tracing-enabled=true
默认情况下，trace exporters 使用 gRPC 协议和端点 http://localhost:4317 在批处理中发送数据。
默认服务名称是 keycloak，它通过 tracing-service-name 属性指定，它优先于 tracing-resource-attributes 属性中定义的 service.name。
有关可通过 tracing-resource-attributes 属性提供的资源属性的更多信息，请参阅 Quarkus OpenTelemetry 资源 指南。
只有在启用 opentelemetry 功能时（默认）才能启用追踪。
有关更多追踪设置，请参阅以下的所有可能配置。
6.2. 开发设置
要查看捕获的红帽 Keycloak 跟踪程序，可以使用使用 Jaeger tracing 平台的基本设置。对于开发目的，Jaeger-all-in-one 可用于尽可能轻松地查看 trace。
jaeger-all-in-one 包括 Jaeger 代理、OTel 收集器和查询服务/UI。您不需要安装单独的收集器，因为您可以直接将 trace 数据发送到 Jaeger。
podman run --name jaeger \
-p 16686:16686 \
-p 4317:4317 \
-p 4318:4318 \
jaegertracing/all-in-one6.2.1. 公开端口
16686- Jaeger UI
4317- OpenTelemetry 协议 gRPC 接收器（默认）
4318- OpenTelemetry 协议 HTTP 接收器
您可以访问 http://localhost:16686/ 上的 Jaeger UI 来查看追踪信息。Jaeger UI 可能与任意红帽构建的 Keycloak 跟踪类似：
6.3. 跟踪信息
6.3.1. span
红帽构建的 Keycloak 为以下活动创建 span：
- 传入的 HTTP 请求
- 传出数据库，包括获取数据库连接
- 传出 LDAP 请求，包括连接到 LDAP 服务器
- 传出 HTTP 请求，包括 IdP 代理
6.3.2. Tags
红帽构建的 Keycloak 根据请求类型在 trace 中添加标签。所有标签都以 kc. 前缀。
标签示例：
kc.clientId- 客户端 ID
kc.realmName- realm 名称
kc.sessionId- 用户会话 ID
kc.token.id-
令牌中所述的 ID
kc.token.issuer-
令牌中所述的
签发者 kc.token.sid-
如令牌中所述的 SID kc.authenticationSessionId- 身份验证会话 ID
kc.authenticationTabId- Authentication Tab ID
6.3.3. 日志
如果对 trace 进行抽样，它将包含请求期间创建的任何用户事件。这包括 LOGIN、LOGOUT 或 REFRESH_TOKEN 事件，其中包含用户事件中找到的所有详情和 ID。
LDAP 通信错误显示为记录的 trace 中的日志条目，以及故障操作的堆栈追踪和详情。
6.4. 跟踪日志中的 ID
启用追踪后，追踪 ID 会包含在所有启用的日志处理程序的日志消息中（请参阅 配置日志记录）。它可用于将日志事件关联到请求执行，这可能会提供更好的可追溯性和调试。所有来自同一请求的日志行将在日志中具有相同的 traceId。
日志消息还包含 sampled 标志，它与下面描述的抽样相关，并指示 span 是否被抽样 - 发送到收集器。
日志记录的格式可能如下所示：
2024-08-05 15:27:07,144 traceId=b636ac4c665ceb901f7fdc3fc7e80154, parentId=d59cea113d0c2549, spanId=d59cea113d0c2549, sampled=true WARN [org.keycloak.events] ...6.4.1. 在日志中隐藏追踪 ID
您可以通过指定与 Keycloak 选项 log-<handler-name>-include-trace 相关联的红帽构建来隐藏特定日志处理程序 中的追踪 ID，其中 & lt;handler-name > 是日志处理程序的名称。例如，要在控制台日志中禁用 trace 信息，您可以将其关闭，如下所示：
bin/kc.[sh|bat] start --tracing-enabled=true --log=console --log-console-include-trace=false
当您明确覆盖特定日志处理程序的日志格式时，*-include-trace 选项没有任何效果，且不会包含追踪。
6.5. Sampling
sampler 决定 trace 是否应该被丢弃或转发，从而通过限制发送到收集器的追踪数量来降低开销。它有助于管理资源消耗，从而可以避免跟踪每个请求和潜在性能损失的大量存储成本。
对于生产环境环境，应正确设置抽样功能，以最大程度降低基础架构成本。
Red Hat build of Keycloak 支持几个内置 OpenTelemetry 示例程序，例如：
-
always_on -
always_off -
traceidratio（默认） -
parentbased_always_on -
parentbased_always_off -
parentbased_traceidratio
已使用的 sampler 可以通过 tracing-sampler-type 属性来更改。
6.5.1. 默认 sampler
红帽构建的 Keycloak 的默认 sampler 是 traceidratio，它根据通过 tracing-sampler-ratio 属性可配置的指定比例控制 trace 抽样率。
6.5.1.1. 跟踪比率
默认追踪比率为 1.0，这意味着所有 trace 都抽样 - 发送到收集器。比率是 [0,1] 范围内的浮动号。例如，当比率为 0.1 时，只有 10% 的 trace 会抽样。
对于生产环境就绪环境，追踪率应该是较小的数字，以防止大量追踪存储基础架构并避免性能开销。
比率可以设置为 0.0，在运行时 完全禁用抽样。
6.5.1.2. rationale
sampler 根据抽样范围的当前比例做出自己的抽样决策，而不管父范围上做出的决定，正如使用 parentbased_traceidratio sampler 一样。
parentbased_traceidratio 抽样器可以是首选的默认类型，因为它可确保 parent 和 child 范围之间的抽样一致性。具体来说，如果对父范围进行抽样，则其所有子范围也会被抽样。它有助于将所有 span 保留为一起，并防止存储不完整的 trace。
但是，它可能会引入某些安全风险，从而导致 DoS 攻击。外部调用者可以操作 trace 标头，父范围可以注入，追踪存储可能会超负。需要评估正确的 HTTP 标头（特别是 tracestate）过滤和适当的调用者信任措施。
如需更多信息，请参阅 W3C Trace 上下文 文档。
6.6. 在 Kubernetes 环境中追踪
当使用红帽构建的 Keycloak Operator 时启用追踪时，有关部署的某些信息会被传播到底层容器中。
6.6.1. 通过 Keycloak CR 配置
您可以通过 Keycloak CR 更改追踪配置。如需更多信息，请参阅高级配置。
6.6.2. 根据 Kubernetes 属性过滤 trace
您可以根据其标签过滤追踪后端中所需的 trace：
-
service.name- 红帽构建的 Keycloak 部署名称 -
k8s.namespace.name- Namespace -
host.name- Pod 名称
红帽 Keycloak Operator 的构建会自动设置 KC_TRACING_SERVICE_NAME 和 KC_TRACING_RESOURCE_ATTRIBUTES 环境变量，用于其管理的 pod 中包含的每个红帽构建 Keycloak 容器。
KC_TRACING_RESOURCE_ATTRIBUTES 变量始终包含（如果未覆盖）代表当前命名空间的 k8s.namespace.name 属性。
6.7. 相关选项
| value | |
|---|---|
|
CLI: 仅在激活 Console 日志处理程序和 Tracing 时可用 |
|
|
CLI: 仅在激活文件日志处理程序和跟踪时才可用 |
|
|
CLI: 仅在激活 Syslog 处理程序和 Tracing 时可用 |
|
|
CLI: 仅在启用 Tracing 时可用 |
|
| wagon
CLI: 仅在启用 'opentelemetry' 功能时才可用 |
|
|
CLI: 仅在启用 Tracing 时可用 | (default) |
| 🛠
CLI: 仅在启用 Tracing 时可用 |
|
|
CLI: 仅在启用 Tracing 时可用 |
|
|
CLI: 仅在启用 Tracing 时可用 | |
|
CLI: 仅在启用 Tracing 时可用 | （默认） |
| wagon
CLI: 仅在启用 Tracing 时可用 |
|
|
CLI: 仅在启用 Tracing 时可用 | （默认） |
第 7 章 在仪表板中视觉化活动
安装红帽构建的 Keycloak Grafana 仪表板，以视觉化捕获部署状态和活动的指标。
红帽构建的 Keycloak 提供指标来观察部署内发生的情况。要了解指标如何随着时间的推移发展，以图形方式收集和视觉化它们会很有帮助。
本指南提供如何在运行的 Grafana 实例中视觉化收集红帽构建的 Keycloak 指标的说明。
7.1. 先决条件
- 启用红帽构建的 Keycloak 指标。如需更多详细信息 ，请参阅与指标相关的见解 章节。
- Grafana 实例正在运行，红帽构建的 Keycloak 指标会收集到 Prometheus 实例中。
-
要使 HTTP 请求延迟 heatmaps 正常工作，请通过将
http-metrics-histograms-enabled设置为true来启用 HTTP 指标的直方图。
7.2. Red Hat build of Keycloak Grafana 仪表板
Grafana 仪表板以 JSON 文件的形式发布，该文件导入到 Grafana 实例中。红帽构建的 Keycloak Grafana 仪表板的 JSON 定义包括在 keycloak/keycloak-grafana-dashboard GitHub 存储库中。
按照以下步骤下载 JSON 文件定义。
从下表中识别要使用的
keycloak-grafana-dashboards中的分支。Expand Red Hat build of Keycloak 版本 keycloak-grafana-dashboards分支>= 26.1
main克隆 GitHub 存储库
git clone -b BRANCH_FROM_STEP_1 https://github.com/keycloak/keycloak-grafana-dashboard.git-
仪表板位于目录
keycloak-grafana-dashboard/dashboards中。
以下小节描述了每个仪表板的目的。
此仪表板包括在 JSON 文件中： keycloak-troubleshooting-dashboard.json。
在仪表板的顶部，图形 通过 Service Level Indicators 显示监控性能 中定义的服务级别指示器。当 SLI 图形没有显示预期结果时，在对Keycloak 部署进行故障排除时，也可以使用此仪表板。???
图 7.1. 仪表板故障排除
7.2.2. Keycloak 容量规划仪表板
此仪表板包括在 JSON 文件中： keycloak-capacity-planning-dashboard.json。
此仪表板显示估算红帽构建的 Keycloak 部署负载时很重要的指标。例如，它显示了由红帽构建 Keycloak 执行的密码验证或登录流的数量。有关这些指标的详情，请查看 自助提供指标章节。
必须启用红帽构建的 Keycloak 事件指标，才能使此仪表板正常工作。要启用它们，请参阅 使用事件指标监控用户活动 一章。
图 7.2. 容量规划仪表板
7.3. 导入仪表板
- 从左侧的 Grafana 菜单打开仪表板页面。
- 单击 New and Import。
- 单击 Upload dashboard JSON 文件，再选择您要导入的仪表板的 JSON 文件。
- 选择您的 Prometheus 数据源。
- 点 Import。
7.4. 导出仪表板
将仪表板导出到 JSON 格式可能很有用。例如，您可能想要建议更改仪表板存储库。
- 打开您要导出的仪表板。
- 点仪表板名称左上角的 share。
- 点 Export 选项卡。
- 启用 Export 以在外部共享。
- 根据您要存储生成的 JSON 的位置，点 Save to file 或 View JSON 和 Copy to Clipboard。
7.5. 进一步阅读
继续阅读如何在 分析外方和带 exemplars 一章中连接 trace 到仪表板。
第 8 章 使用 exemplars 分析外部和错误
使用 exemplars 将指标连接到记录的 trace，以分析错误的根本原因或延迟。
指标通过多个事件进行聚合，并显示您的系统是否在定义的绑定内操作。它们非常适合监控错误率或尾部延迟，并设置警报或驱动性能优化。仍然，聚合会导致指标报告的延迟或错误很难找到 root。
通过启用追踪来查找错误和延迟的根原因。要将指标连接到记录的 trace，有 exemplars 概念。
设置 EXemplars 后，红帽构建的 Keycloak 报告带有最后记录的 trace 作为一个 exemplar。Grafana 等仪表板工具可以将指标仪表板中的 exemplar 链接到 trace 视图。
支持 exemplars 的指标有：
如需了解在将鼠标悬停在 pink 指示符之一时显示延迟的热图视觉化截图，请参见下方。
图 8.1. 使用 exemplar 的 heatmap 图表
8.1. 设置 exemplars
要从 exemplars 中受益，请执行以下步骤：
- 启用红帽构建的 Keycloak 指标，如 Gaining insights with metrics 所述。
- 为红帽构建的 Keycloak 启用追踪，如 Root 导致使用追踪进行分析 中所述。
在监控系统中启用 exemplar 存储。
对于 Prometheus ，这是您需要启用 的技术预览功能。
使用
OpenMetricsText1.0.0协议提取指标，该协议在 Prometheus 中不默认启用。如果您在 Kubernetes 环境中使用
PodMonitor或类似的 PodMonitor，可以通过将其添加到自定义资源的 spec 来实现：apiVersion: monitoring.coreos.com/v1 kind: PodMonitor metadata: ... spec: scrapeProtocols: - OpenMetricsText1.0.0配置指标数据源，在其中链接到 trace。
使用 Grafana 和 Prometheus 时，这会为 Prometheus 数据源设置
exemplarTraceIdDestinations，然后指向由 Jaeger 或 Tempo 等工具提供的追踪数据源。在仪表板中启用 exemplars。
在您要显示 exemplars 的每个仪表板上，在每个查询中启用 Exemplars 切换。正确设置后，您会注意到仪表板中可以点击以查看 trace 的点或星形。
- 如果没有指定提取协议，Prometheus 默认不会在内容协商中发送它，Keycloak 将回退到 PrometheusText 协议，该协议不包含 exemplars。
- 如果启用了追踪和指标，但请求抽样没有记录追踪，则公开的指标将不包含任何 exemplars。
- 如果您使用浏览器访问指标端点，内容协商将导致返回 PrometheusText 格式，您将无法看到任何 exemplars。
8.2. 验证 exemplars 是否按预期工作
执行以下步骤来验证红帽构建的 Keycloak 是否已正确设置来执行 exemplars：
- 按照说明为红帽构建的 Keycloak 设置指标和追踪。
-
出于测试目的，请通过将追踪语法设置为
1.0来记录所有 trace。对于生产环境中推荐的抽样设置，请参阅 Root cause analysis with tracing。 - 登录到 Keycloak 实例以创建一些 trace。
使用类似如下的命令提取指标，并搜索具有 exemplar 设置的指标：
$ curl -s http://localhost:9000/metrics \ -H 'Accept: application/openmetrics-text; version=1.0.0; charset=utf-8' \ | grep "#.*trace_id"这应该生成类似于如下的输出：请注意，添加了 span 和 trace ID 的额外
#：http_server_requests_seconds_count {...} ... # {span_id="...",trace_id="..."} ...
'%20d='M201.5%20305.5c-13.8%200-24.9-11.1-24.9-24.6%200-13.8%2011.1-24.9%2024.9-24.9%2013.6%200%2024.6%2011.1%2024.6%2024.9%200%2013.6-11.1%2024.6-24.6%2024.6zM504%20256c0%20137-111%20248-248%20248S8%20393%208%20256%20119%208%20256%208s248%20111%20248%20248zm-132.3-41.2c-9.4%200-17.7%203.9-23.8%2010-22.4-15.5-52.6-25.5-86.1-26.6l17.4-78.3%2055.4%2012.5c0%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.3%2024.9-24.9s-11.1-24.9-24.9-24.9c-9.7%200-18%205.8-22.1%2013.8l-61.2-13.6c-3-.8-6.1%201.4-6.9%204.4l-19.1%2086.4c-33.2%201.4-63.1%2011.3-85.5%2026.8-6.1-6.4-14.7-10.2-24.1-10.2-34.9%200-46.3%2046.9-14.4%2062.8-1.1%205-1.7%2010.2-1.7%2015.5%200%2052.6%2059.2%2095.2%20132%2095.2%2073.1%200%20132.3-42.6%20132.3-95.2%200-5.3-.6-10.8-1.9-15.8%2031.3-16%2019.8-62.5-14.9-62.5zM302.8%20331c-18.2%2018.2-76.1%2017.9-93.6%200-2.2-2.2-6.1-2.2-8.3%200-2.5%202.5-2.5%206.4%200%208.6%2022.8%2022.8%2087.3%2022.8%20110.2%200%202.5-2.2%202.5-6.1%200-8.6-2.2-2.2-6.1-2.2-8.3%200zm7.7-75c-13.6%200-24.6%2011.1-24.6%2024.9%200%2013.6%2011.1%2024.6%2024.6%2024.6%2013.8%200%2024.9-11.1%2024.9-24.6%200-13.8-11-24.9-24.9-24.9z'/%3e%3c/svg%3e){kind=small}