启用跟踪

了解如何在 Keycloak 中启用分布式跟踪
本指南介绍的是当前处于预览状态的功能。在我们继续开发此功能期间，请提供您的反馈。

本指南解释了如何通过利用 OpenTelemetry (OTel) 在 Keycloak 中启用和配置分布式跟踪。跟踪允许详细监控每个请求的生命周期，这有助于快速识别和诊断问题，从而实现更有效的调试和维护。

它还提供有关性能瓶颈的宝贵见解，并有助于优化系统的整体效率。Keycloak 使用受支持的 Quarkus OTel 扩展，该扩展提供了应用程序跟踪的无缝集成和公开。

启用跟踪

可以使用构建时选项 tracing-enabled 启用公开跟踪，并按如下方式启用 opentelemetry 功能。

bin/kc.[sh|bat] start --tracing-enabled=true --features=opentelemetry

默认情况下，跟踪导出器使用 gRPC 协议和端点 http://127.0.0.1:4317 以批处理方式发送数据。

默认服务名称为 keycloak，通过 tracing-service-name 属性指定，该属性优先于 tracing-resource-attributes 属性中定义的 service.name。

有关可通过 tracing-resource-attributes 属性提供的资源属性的更多信息，请参见 Quarkus OpenTelemetry 资源 指南。

有关更多跟踪设置，请参见以下所有可能的配置。

开发设置

为了查看捕获的 Keycloak 跟踪，可以使用利用 Jaeger 跟踪平台的基本设置。出于开发目的，可以使用 Jaeger-all-in-one 来尽可能轻松地查看跟踪。

Jaeger-all-in-one 包括 Jaeger 代理、OTel 收集器以及查询服务/UI。您不需要安装单独的收集器，因为您可以直接将跟踪数据发送到 Jaeger。 
podman|docker run --name jaeger \
-p 16686:16686 \
-p 4317:4317 \
-p 4318:4318 \
jaegertracing/all-in-one

公开端口

  • :16686 - Jaeger UI

  • :4317 - OpenTelemetry 协议 gRPC 接收器（默认）

  • :4318 - OpenTelemetry 协议 HTTP 接收器

您可以访问 http://127.0.0.1:16686/ 上的 Jaeger UI 以查看跟踪信息。Jaeger UI 可能如下所示，其中包含任意 Keycloak 跟踪。

Jaeger UI

日志中的跟踪

启用跟踪后，跟踪信息将包含在所有已启用日志处理程序的日志消息中（有关详细信息，请参见 配置日志记录）。这对于将日志事件与请求执行相关联可能很有用，这可以提供更好的可跟踪性和调试功能。来自同一请求的所有日志行在日志中将具有相同的 traceId。

日志消息还包含 sampled 标志，该标志与下面描述的采样相关，并指示跨度是否已采样（已发送到收集器）。

日志记录的格式可能如下所示。

2024-08-05 15:27:07,144 traceId=b636ac4c665ceb901f7fdc3fc7e80154, parentId=d59cea113d0c2549, spanId=d59cea113d0c2549, sampled=true WARN  [org.keycloak.events] ...

隐藏日志中的跟踪信息

您可以通过指定其关联的 Keycloak 选项 log-<handler-name>-include-trace 在特定日志处理程序中隐藏跟踪信息，其中 <handler-name> 是日志处理程序的名称。例如，要禁用 console 日志中的跟踪信息，您可以按如下方式将其关闭。

bin/kc.[sh|bat] start --tracing-enabled=true --features=opentelemetry --log=console --log-console-include-trace=false
当您明确覆盖特定日志处理程序的日志格式时，*-include-trace 选项将不起作用，并且不包含跟踪信息。

采样

采样器决定是否应丢弃或转发跟踪，通过限制发送到收集器的已收集跟踪的数量来有效地降低开销。它有助于管理资源消耗，这将有助于避免对每个请求进行跟踪的巨大存储成本以及潜在的性能损失。

对于生产就绪环境，应适当地设置采样以最大程度地减少基础设施成本。

Keycloak 支持几种内置的 OpenTelemetry 采样器，例如

  • always_on

  • always_off

  • traceidratio（默认）

  • parentbased_always_on

  • parentbased_always_off

  • parentbased_traceidratio

可以使用 tracing-sampler-type 属性更改使用的采样器。

默认采样器

Keycloak 的默认采样器是 traceidratio，它根据通过 tracing-sampler-ratio 属性配置的指定比率控制跟踪采样的速率。

跟踪比率

默认跟踪比率为 1.0，这意味着所有跟踪都已采样（已发送到收集器）。该比率是 (0,1] 范围内的浮点数。例如，当比率为 0.1 时，仅采样 10% 的跟踪。

对于生产就绪环境，跟踪比率应为较小的数字，以防止跟踪存储基础设施的巨大成本并避免性能开销。

原理

采样器根据当前已采样跨度比率做出自己的采样决策，而不管对父跨度的决策如何，就像使用 parentbased_traceidratio 采样器一样。

parentbased_traceidratio 采样器可能是首选的默认类型，因为它可以确保父跨度和子跨度之间的采样一致性。具体而言，如果采样了父跨度，则其所有子跨度也将被采样——所有跨度都使用相同的采样决策。这有助于将所有跨度保持在一起并防止存储不完整的跟踪。

但是，这可能会引入某些导致 DoS 攻击的安全风险。外部调用者可以操纵跟踪标头，可以注入父跨度，并且跟踪存储可能会不堪重负。需要评估适当的 HTTP 标头（尤其是 tracestate）过滤和调用者信任的适当措施。

有关更多信息，请参见 W3C 跟踪上下文 文档。

Kubernetes 环境中的跟踪

在使用 Keycloak 运算符时启用跟踪时，有关部署的某些信息将传播到底层容器。

Keycloak CR 目前不支持跟踪配置，因此可以使用 additionalOptions 将其用于 tracing-enabled 属性和其他跟踪选项。

您可以根据跟踪的标签在跟踪后端中过滤出所需的跟踪。

  • service.name - Keycloak 部署名称

  • k8s.namespace.name - 命名空间

  • host.name - Pod 名称

Keycloak 运算符会自动为其管理的 Pod 中包含的每个 Keycloak 容器设置 KC_TRACING_SERVICE_NAME 和 KC_TRACING_RESOURCE_ATTRIBUTES 环境变量。

相关选项

值

log-console-include-trace

在控制台日志中包含跟踪信息。

如果指定了 log-console-format 选项，则此选项无效。

CLI： --log-console-include-trace
Env： KC_LOG_CONSOLE_INCLUDE_TRACE

仅在激活控制台日志处理程序和跟踪时可用

true（默认）、false

log-file-include-trace

在文件日志中包含跟踪信息。

如果指定了 log-file-format 选项，则此选项无效。

CLI： --log-file-include-trace
Env： KC_LOG_FILE_INCLUDE_TRACE

仅在激活文件日志处理程序和跟踪时可用

true（默认）、false

log-syslog-include-trace

在 Syslog 中包含跟踪信息。

如果指定了 log-syslog-format 选项，则此选项无效。

CLI： --log-syslog-include-trace
Env： KC_LOG_SYSLOG_INCLUDE_TRACE

仅在激活 Syslog 处理程序和跟踪时可用

true（默认）、false

tracing-compression

预览：用于压缩有效负载的 OpenTelemetry 压缩方法。

如果未设置，则禁用压缩。

CLI： --tracing-compression
Env： KC_TRACING_COMPRESSION

仅在启用“opentelemetry”功能和跟踪时可用

gzip、none（默认）

tracing-enabled

预览：启用 OpenTelemetry 跟踪。

CLI： --tracing-enabled
Env： KC_TRACING_ENABLED

仅在启用“opentelemetry”功能时可用

true、false（默认）

tracing-endpoint

预览：要连接到的 OpenTelemetry 端点。

CLI： --tracing-endpoint
Env： KC_TRACING_ENDPOINT

仅在启用“opentelemetry”功能和跟踪时可用

http://127.0.0.1:4317（默认）

tracing-jdbc-enabled

预览：启用 OpenTelemetry JDBC 跟踪。

CLI： --tracing-jdbc-enabled
Env： KC_TRACING_JDBC_ENABLED

仅在启用“opentelemetry”功能和跟踪时可用

true（默认）、false

tracing-protocol

预览：用于遥测数据的 OpenTelemetry 协议。

CLI： --tracing-protocol
Env： KC_TRACING_PROTOCOL

仅在启用“opentelemetry”功能和跟踪时可用

grpc（默认）、http/protobuf

tracing-resource-attributes

预览：导出跟踪中存在的 OpenTelemetry 资源属性，以表征遥测生产者。

格式为 key1=val1,key2=val2 的值。有关更多信息，请查看跟踪指南。

CLI： --tracing-resource-attributes
Env： KC_TRACING_RESOURCE_ATTRIBUTES

仅在启用“opentelemetry”功能和跟踪时可用

tracing-sampler-ratio

预览：OpenTelemetry 采样器比率。

跨度被采样的概率。预期区间<0,1)内的双精度值。

CLI： --tracing-sampler-ratio
Env： KC_TRACING_SAMPLER_RATIO

仅在启用“opentelemetry”功能和跟踪时可用

1.0（默认）

tracing-sampler-type

预览：用于跟踪的 OpenTelemetry 采样器。

CLI： --tracing-sampler-type
Env： KC_TRACING_SAMPLER_TYPE

仅在启用“opentelemetry”功能和跟踪时可用

always_on、always_off、traceidratio（默认）、parentbased_always_on、parentbased_always_off、parentbased_traceidratio

tracing-service-name

预览：OpenTelemetry 服务名称。

优先于 tracing-resource-attributes 属性中定义的 service.name。

CLI： --tracing-service-name
Env： KC_TRACING_SERVICE_NAME

仅在启用“opentelemetry”功能和跟踪时可用

keycloak（默认）
在本页上
编辑本指南