Red Hat Summit 红帽全球峰会支持控制台（Console）开发人员开始试用联系人

16.2. 启用日志处理程序

要启用日志处理程序，请输入以下命令： 

bin/kc.[sh|bat] start --log="<handler1>,<handler2>"
Copy to Clipboard Toggle word wrap

可用的处理程序有：

  • 控制台
  • file
  • syslog

以下提到的更具体的处理程序配置仅在将处理程序添加到此逗号分隔列表中时生效。

16.2.1. 为每个处理器指定日志级别
复制链接

log-level 属性指定所选类别的全局根日志级别和级别。但是，需要更精细的日志级别来满足现代应用的要求。

要为特定处理程序设置日志级别，格式为 log-<handler>-level （其中 & lt;handler > 是可用的日志处理程序）。

这意味着日志级别设置的属性如下：

  • log-console-level - Console log handler
  • log-file-level - File log handler
  • log-syslog-level - Syslog 日志处理程序
注意

log-<handler>-level 属性仅在启用了特定日志处理程序时才可用。以下日志处理程序设置中的更多信息。

只有 第 16.1.1 节 “日志级别” 部分指定的日志级别才会被接受，且必须为小写。尚不支持为日志处理程序指定特定的类别。

16.2.1.1. 常规原则
复制链接

需要了解，为每个特定处理程序设置日志级别 不会覆盖 log-level 属性中指定的根级别。日志处理程序遵循 root 日志级别，这代表了整个日志记录系统的最大详细程度。这意味着单个日志处理程序可以配置为小于根日志记录器，但不能配置更多。

具体来说，当为处理程序定义了任意日志级别时，并不表示输出中会显示带有日志级别的日志记录。在这种情况下，还必须评估 root 日志级别。日志级别为 root 日志级别 提供限制，日志处理程序的默认日志级别 都是 无限制的。

16.2.1.2. 例子
复制链接

示例：对文件处理程序进行 debug，但 console 处理程序的信息： 

bin/kc.[sh|bat] start --log=console,file --log-level=debug --log-console-level=info
Copy to Clipboard Toggle word wrap

root 日志级别设置为 debug，因此每个日志处理程序都会继承值 - 因此，文件日志处理程序会继承文件日志处理程序。要 在控制台中隐藏调试 记录，我们需要将 console 处理程序的最小（最低严重）级别设置为 info。

示例： 警告 所有处理程序，但对文件处理程序进行 debug ：

bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug --log-console-level=warn --log-syslog-level=warn
Copy to Clipboard Toggle word wrap

root 级别必须设置为最详细的必要级别（本例中为debug ），并且必须相应地修改其他日志处理程序。

示例：所有处理程序的信息，但对 Syslog 处理程序进行 debug+org.keycloak.events:trace ： 

bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug,org.keycloak.events:trace, --log-syslog-level=trace --log-console-level=info --log-file-level=info
Copy to Clipboard Toggle word wrap

要查看 org.keycloak.events:trace，必须为 Syslog 处理程序设置 trace 级别。

16.2.2. 为日志处理程序使用不同的 JSON 格式
复制链接

每个日志处理程序都提供了以 JSON 格式具有结构化日志输出的功能。它可以被属性启用，格式为 log-<handler>-output=json （其中 & lt;handler& gt; 是一个日志处理程序）。

如果您需要生成的 JSON 的不同格式，您可以使用以下 JSON 输出格式：

  • 默认 （默认）
  • ECS

ecs 值指的是 ECS (Elastic Common Schema)。

ECS 是一种开源、社区驱动的规范，用于定义用于 Elastic 解决方案的通用字段集合。ECS 规格与 OpenTelemetry Semantic Conventions 合并，目的是创建由 OpenTelemetry 维护的一个标准。

要更改 JSON 输出格式，引入了格式 log-<handler>-json-format （其中 &lt ;handler& gt; 是一个日志处理器）的属性：

  • log-console-json-format - Console log handler
  • log-file-json-format - File log handler
  • log-syslog-json-format - Syslog 日志处理程序

16.2.2.1. Example
复制链接

如果要以 ECS (Elastic Common Schema)格式具有 JSON 日志，您可以输入以下命令： 

bin/kc.[sh|bat] start --log-console-output=json --log-console-json-format=ecs
Copy to Clipboard Toggle word wrap

日志消息示例

{"@timestamp":"2025-02-03T14:53:22.539484211+01:00","event.sequence":9608,"log.logger":"io.quarkus","log.level":"INFO","message":"Keycloak 999.0.0-SNAPSHOT on JVM (powered by Quarkus 3.17.8) started in 4.615s. Listening on: http://0.0.0.0:8080","process.thread.name":"main","process.thread.id":1,"mdc":{},"ndc":"","host.hostname":"host-name","process.name":"/usr/lib/jvm/jdk-21.0.3+9/bin/java","process.pid":77561,"data_stream.type":"logs","ecs.version":"1.12.2","service.environment":"prod","service.name":"Keycloak","service.version":"999.0.0-SNAPSHOT"}
Copy to Clipboard Toggle word wrap

16.2.3. 异步日志记录
复制链接

红帽构建的 Keycloak 支持异步日志记录，这对需要 高吞吐量和低延迟 的部署很有用。异步日志记录使用单独的线程来处理所有日志记录。日志记录处理程序的调用方式与同步日志记录完全相同，仅在单独的线程中执行。您可以为所有红帽构建 Keycloak 日志处理程序启用异步日志记录。将为每个启用了异步日志记录的日志处理程序创建一个专用的线程。

异步日志记录的底层机制使用队列来处理日志记录。每个新日志记录都会添加到队列中，然后使用启用异步日志记录发布到特定的日志处理程序。每个日志处理程序都有不同的队列。

如果队列已满，它将阻止主线程并等待队列中的可用空间。

16.2.3.1. 使用异步日志记录的时间
复制链接

  • 传入的请求 需要较低延迟
  • 您需要 更高的吞吐量
  • 您有 小型 worker 线程池，并希望将日志记录卸载到单独的线程
  • 您要降低 I/O-heavy 日志处理程序的影响
  • 您可以登录到 远程目的地 （如网络 syslog 服务器），并希望避免阻塞 worker 线程
警告

请注意，启用异步日志记录可能会因为 额外的独立线程和内部队列造成一些额外的内存开销。在这种情况下，不建议将其用于受资源约束的环境。此外，意外的服务器关闭造成 丢失日志记录的风险。

16.2.3.2. 启用异步日志记录
复制链接

您可以使用 log-async 属性全局启用异步日志记录，如下所示： 

bin/kc.[sh|bat] start --log-async=true
Copy to Clipboard Toggle word wrap

或者，您可以使用格式 log-<handler>-async （其中 <handler> 是一个日志处理程序） 中的属性 为每个特定处理器启用异步日志记录。如果没有设置特定处理程序的属性，则使用父 log-async 属性的值。

您可以使用以下方法使用这些属性： 

bin/kc.[sh|bat] start --log-console-async=true --log-file-async=true --log-syslog-async=true
Copy to Clipboard Toggle word wrap
  • log-console-async - Console log handler
  • log-file-async - File log handler
  • log-syslog-async - Syslog 日志处理程序

16.2.3.3. 更改队列长度
复制链接

您可以更改用于异步日志记录的队列的大小。默认大小为队列中的 512 个日志记录。

您可以按照以下方式更改队列长度： 

bin/kc.[sh|bat] start --log-console-async-queue-length=512 --log-file-async-queue-length=512 --log-syslog-async-queue-length=512
Copy to Clipboard Toggle word wrap

这些属性仅在为这些特定日志处理程序启用异步日志记录时才可用。

16.2.4. HTTP 访问日志记录
复制链接

红帽构建的 Keycloak 支持 HTTP 访问日志记录来记录传入的 HTTP 请求详情。虽然访问日志通常用于调试和流量分析，但它们对于安全审核和合规监控也很重要，有助于管理员跟踪访问模式，识别可疑活动，以及维护审计跟踪活动。

这些日志在 INFO 级别上编写，因此请确保您的日志记录配置包含这个级别 - 全局（如 log-level=info）或具体用于访问日志类别（如 log-level=org.keycloak.http.access-log:info）。当启用 HTTP 访问日志时，它们会被默认显示，因为 INFO 级别是 Red Hat build of Keycloak 的默认日志级别。

16.2.4.1. 如何启用
复制链接

您可以使用 http-access-log-enabled 属性启用 HTTP 访问日志，如下所示： 

bin/kc.[sh|bat] start --http-access-log-enabled=true
Copy to Clipboard Toggle word wrap

16.2.4.2. 更改日志格式/模式
复制链接

您可以使用 http-access-log-pattern 属性更改访问日志记录的格式/模式，如下所示： 

bin/kc.[sh|bat] start --http-access-log-pattern=combined
Copy to Clipboard Toggle word wrap

预定义的命名模式：

  • common （默认）- 打印有关请求的基本信息
  • combined - 打印有关请求 + 信息及参考者和用户代理的基本信息
  • long - 使用所有标头打印有关请求的综合信息

您甚至可以使用需要记录的数据来指定自己的模式，例如： 

bin/kc.[sh|bat] start --http-access-log-pattern='%A %{METHOD} %{REQUEST_URL} %{i,User-Agent}'
Copy to Clipboard Toggle word wrap

如需可以使用的变量的完整列表，请参阅 Quarkus 文档。

16.2.4.3. 排除特定的 URL 路径
复制链接

可以从 HTTP 访问日志中排除特定的 URL 路径，因此不会记录它们。

您可以使用正则表达式来排除它们，例如： 

bin/kc.[sh|bat] start --http-access-log-exclude='/realms/my-internal-realm/.*'
Copy to Clipboard Toggle word wrap

在这种情况下，对 /realms/my-internal-realm/ 的所有调用都将从 HTTP 访问日志中排除。

返回顶部
Red Hat logoGithubredditYoutubeTwitter

学习

尝试、购买和销售

社区

关于红帽文档

通过我们的产品和服务，以及可以信赖的内容，帮助红帽用户创新并实现他们的目标。 了解我们当前的更新.

让开源更具包容性

红帽致力于替换我们的代码、文档和 Web 属性中存在问题的语言。欲了解更多详情，请参阅红帽博客.

關於紅帽

我们提供强化的解决方案，使企业能够更轻松地跨平台和环境（从核心数据中心到网络边缘）工作。

Theme

© 2025 Red Hat