配置日志记录

了解如何配置日志记录

Keycloak 使用 JBoss 日志记录框架。以下是具有公共父日志记录处理程序 root 的可用日志记录处理程序的高级概述

  • 控制台

  • 文件

  • syslog

日志记录配置

日志记录在 Keycloak 中按类别进行。您可以为根日志级别或更具体的类别（例如 org.hibernate 或 org.keycloak）配置日志记录。也可以为每个特定日志处理程序定制日志级别。

本指南介绍如何配置日志记录。

日志级别

下表定义了可用的日志级别。

级别 描述

FATAL

严重错误，完全无法提供任何类型的请求。

ERROR

重大错误或问题，导致无法处理请求。

WARN

非致命错误或问题，可能不需要立即纠正。

INFO

Keycloak 生命周期事件或重要信息。频率低。

DEBUG

用于调试目的的更详细的信息，例如数据库日志。频率较高。

TRACE

最详细的调试信息。频率非常高。

ALL

所有日志消息的特殊级别。

OFF

完全关闭日志记录的特殊级别（不推荐）。

配置根日志级别

当不存在针对更具体的类别记录器的日志级别配置时，将使用封闭类别。当不存在封闭类别时，将使用根记录器级别。

要设置根日志级别，请输入以下命令

bin/kc.[sh|bat] start --log-level=<root-level>

请遵循此命令的以下准则

  • 对于 <root-level>，请提供前表中定义的级别。

  • 日志级别不区分大小写。例如，您可以使用 DEBUG 或 debug。

  • 如果您意外设置了日志级别两次，则列表中的最后一次出现将成为日志级别。例如，如果您包含语法 --log-level="info,…​,DEBUG,…​"，则根记录器将是 DEBUG。

配置类别特定的日志级别

您可以为 Keycloak 中的特定区域设置不同的日志级别。使用此命令提供要使用不同日志级别的类别的逗号分隔列表

bin/kc.[sh|bat] start --log-level="<root-level>,<org.category1>:<org.category1-level>"

应用于类别的配置也适用于其子类别，除非您包含更具体的匹配子类别。

示例
bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug,org.hibernate.hql.internal.ast:info"

此示例设置以下日志级别

  • 所有记录器的根日志级别设置为 INFO。

  • 一般的 hibernate 日志级别设置为 debug。

  • 为了防止 SQL 抽象语法树创建冗长的日志输出，将特定子类别 org.hibernate.hql.internal.ast 设置为 info。因此，SQL 抽象语法树将被省略，而不是以 debug 级别出现。

启用日志处理程序

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

bin/kc.[sh|bat] start --log="<handler1>,<handler2>"

可用的处理程序是

  • 控制台

  • 文件

  • syslog

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

为每个处理程序指定日志级别

log-level 属性指定全局根日志级别和所选类别的级别。但是，需要更细粒度的日志级别方法才能符合现代应用程序要求。

为了设置特定处理程序的日志级别，引入了格式为 log-<handler>-level（其中 <handler> 是可用的日志处理程序）的属性。

这意味着日志级别设置的属性看起来像这样

  • log-console-level - 控制台日志处理程序

  • log-file-level - 文件日志处理程序

  • log-syslog-level - Syslog 日志处理程序

log-<handler>-level 属性仅在启用特定日志处理程序时才可用。有关更多信息，请参见下面日志处理程序设置。

仅接受 日志级别 部分中指定的日志级别，并且 **必须为小写**。目前尚不支持为日志处理程序指定特定类别。

一般原则

必须了解，为每个特定处理程序设置日志级别 **不会覆盖** log-level 属性中指定的根级别。日志处理程序尊重根日志级别，该级别代表整个日志记录系统的最大详细程度。这意味着可以将单个日志处理程序配置为比根记录器更不详细，但不能更详细。

具体来说，当为处理程序定义任意日志级别时，并不意味着日志记录中将存在具有该日志级别的日志记录。在这种情况下，还必须评估根 log-level。日志处理程序级别为根日志级别提供 **限制**，日志处理程序的默认日志级别为 all - 没有限制。

示例

示例：文件处理程序为 debug，但控制台处理程序为 info
bin/kc.[sh|bat] start --log=console,file --log-level=debug --log-console-level=info

根日志级别设置为 debug，因此每个日志处理程序都继承该值 - 文件日志处理程序也是如此。要隐藏控制台中的 debug 记录，我们需要将控制台处理程序的最小（最不严重）级别设置为 info。

示例：所有处理程序为 warn，但文件处理程序为 debug
bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug --log-console-level=warn --log-syslog-level=warn

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

示例：所有处理程序为 info，但 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

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

控制台日志处理程序

控制台日志处理程序默认启用，为控制台提供非结构化日志消息。

配置控制台日志格式

Keycloak 默认使用基于模式的日志记录格式化程序，该格式化程序生成人类可读的文本日志。

这些行的日志记录格式模板可以在根级别应用。默认格式模板是

  • %d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n

格式字符串支持下表中的符号

符号 概要 描述

%%

%

%

渲染一个简单的 % 字符。

%c

类别

渲染日志类别名称。

%d{xxx}

日期

使用给定的日期格式字符串渲染日期。字符串语法由 java.text.SimpleDateFormat 定义

%e

异常

渲染抛出的异常。

%h

主机名

渲染简单主机名。

%H

限定主机名

渲染完全限定的主机名，这可能是简单主机名，具体取决于操作系统配置。

%i

进程 ID

渲染当前进程 PID。

%m

完整消息

渲染日志消息和异常（如果有）。

%n

换行符

渲染特定于平台的换行符字符串。

%N

进程名称

渲染当前进程的名称。

级别

%p

渲染消息的日志级别。

%r

相对时间

渲染自应用程序日志开始以来的毫秒时间。

%s

简单消息

仅渲染日志消息，不包含异常跟踪。

%t

线程名称

渲染线程名称。

%t{id}

线程 ID

渲染线程 ID。

%z{<zone name>}

时区

将日志输出的时区设置为 <zone name>。

%L

行号

渲染日志消息的行号。

设置日志记录格式

  1. 要设置已记录行的日志记录格式，请执行以下步骤

  2. 使用上表构建所需的格式模板。

    bin/kc.[sh|bat] start --log-console-format="'<format>'"

输入以下命令

请注意，在使用 CLI 调用包含特殊 shell 字符（如 ;）的命令时，您需要转义字符。因此，请考虑在配置文件中设置它。
bin/kc.[sh|bat] start --log-console-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"

示例：缩写完全限定的类别名称

此示例通过在模板中设置 [%c{3.}] 而不是默认的 [%c] 来将类别名称缩写为三个字符。

配置 JSON 或纯控制台日志记录

bin/kc.[sh|bat] start --log-console-output=json
默认情况下，控制台日志处理程序将纯非结构化数据记录到控制台。要改为使用结构化的 JSON 日志输出，请输入以下命令
{"timestamp":"2022-02-25T10:31:32.452+01:00","sequence":8442,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.253s. Listening on: http://0.0.0.0:8080","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host-name","processName":"QuarkusEntryPoint","processId":36946}

示例日志消息

使用 JSON 输出时，将禁用颜色，并且 --log-console-format 设置的格式设置将不适用。

bin/kc.[sh|bat] start --log-console-output=default
默认情况下，控制台日志处理程序将纯非结构化数据记录到控制台。要改为使用结构化的 JSON 日志输出，请输入以下命令
2022-03-02 10:36:50,603 INFO  [io.quarkus] (main) Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.615s. Listening on: http://0.0.0.0:8080

要使用非结构化日志记录，请输入以下命令

颜色

bin/kc.[sh|bat] start --log-console-color=<false|true>

默认情况下，非结构化日志的彩色控制台日志输出已禁用。颜色可能会提高可读性，但它们在将日志发送到外部日志聚合系统时会导致问题。要启用或禁用彩色控制台日志输出，请输入以下命令

配置控制台日志级别

bin/kc.[sh|bat] start --log-console-level=warn

控制台日志处理程序的日志级别可以通过 --log-console-level 属性指定，如下所示

有关更多信息，请参见上面 为每个处理程序指定日志级别 部分。

文件日志记录

作为将日志记录到控制台的替代方案，您可以使用非结构化日志记录到文件。

启用文件日志记录

bin/kc.[sh|bat] start --log="console,file"

默认情况下，将日志记录到文件已禁用。要启用它，请输入以下命令

在 Keycloak 安装的 data/log 目录中创建了一个名为 keycloak.log 的日志文件。

配置日志文件的路径和名称

  1. 要更改日志文件创建的位置和文件名，请执行以下步骤

    创建一个可写目录来存储日志文件。

  2. 如果目录不可写，Keycloak 将正常启动，但会发出错误，并且不会创建日志文件。

    bin/kc.[sh|bat] start --log="console,file" --log-file=<path-to>/<your-file.log>

输入此命令

配置文件处理程序格式

bin/kc.[sh|bat] start --log-file-format="<pattern>"

要为文件日志处理程序配置不同的日志记录格式，请输入以下命令

有关更多信息和可用模式配置的表格，请参见 配置控制台日志格式。

配置文件日志级别

bin/kc.[sh|bat] start --log-file-level=warn

控制台日志处理程序的日志级别可以通过 --log-console-level 属性指定，如下所示

文件日志处理程序的日志级别可以通过 --log-file-level 属性指定，如下所示

使用 Syslog 进行集中式日志记录

Keycloak 提供将日志发送到远程 Syslog 服务器的功能。它使用在 RFC 5424 中定义的协议。

启用 Syslog 处理程序

bin/kc.[sh|bat] start --log="console,syslog"

要启用使用 Syslog 进行日志记录，请将其添加到已激活的日志处理程序列表中，如下所示

配置 Syslog 应用程序名称

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-app-name=kc-p-itadmins

要设置不同的应用程序名称，请添加 --log-syslog-app-name 选项，如下所示

如果未设置，应用程序名称默认为 keycloak。

配置 Syslog 端点

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-endpoint=myhost:12345

要配置集中式日志记录系统的端点（host:port），请输入以下命令，并将值替换为您的特定值

启用 Syslog 处理程序后，主机使用 localhost 作为主机值。默认端口为 514。

配置 Syslog 日志级别

bin/kc.[sh|bat] start --log-syslog-level=warn

控制台日志处理程序的日志级别可以通过 --log-console-level 属性指定，如下所示

Syslog 日志处理程序的日志级别可以通过 --log-syslog-level 属性指定，如下所示

配置 Syslog 协议

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-protocol=udp

Syslog 使用 TCP 作为默认的通信协议。要改为使用 UDP 而不是 TCP，请添加 --log-syslog-protocol 选项，如下所示

可用的协议是：tpc、udp 和 ssl-tcp。

设置日志记录格式

  1. 要设置已记录行的日志记录格式，请执行以下步骤

  2. 使用上表构建所需的格式模板。

    bin/kc.[sh|bat] start --log-syslog-format="'<format>'"

输入以下命令

请注意，在使用 CLI 调用包含特殊 shell 字符（如 ;）的命令时，您需要转义字符。因此，请考虑在配置文件中设置它。
bin/kc.[sh|bat] start --log-syslog-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"

示例：缩写完全限定的类别名称

配置 Syslog 类型

Syslog 使用不同的消息格式，基于特定的 RFC 规范。要使用不同的消息格式更改 Syslog 类型，请使用 --log-syslog-type 选项，如下所示

bin/kc.[sh|bat] start --log-syslog-type=rfc3164

--log-syslog-type 选项的可能值是

  • rfc5424（默认）

  • rfc3164

首选的 Syslog 类型是 RFC 5424，它取代了 RFC 3164，也称为 BSD Syslog 协议。

配置 Syslog 最大消息长度

要设置允许发送的消息的最大长度（以字节为单位），请使用 --log-syslog-max-length 选项，如下所示

bin/kc.[sh|bat] start --log-syslog-max-length=1536

长度可以用适当的后缀（如 1k 或 1K）以内存大小格式指定。长度包括头和消息。

如果长度未显式设置，则默认值将根据 --log-syslog-type 选项设置，如下所示

  • 2048B - 对于 RFC 5424

  • 1024B - 对于 RFC 3164

配置 Syslog 结构化输出

默认情况下，Syslog 日志处理程序将纯未结构化数据发送到 Syslog 服务器。要改为使用结构化的 JSON 日志输出，请输入以下命令

bin/kc.[sh|bat] start --log-syslog-output=json
默认情况下，控制台日志处理程序将纯非结构化数据记录到控制台。要改为使用结构化的 JSON 日志输出，请输入以下命令
2024-04-05T12:32:20.616+02:00 host keycloak 2788276 io.quarkus - {"timestamp":"2024-04-05T12:32:20.616208533+02:00","sequence":9948,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Profile prod activated. ","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host","processName":"QuarkusEntryPoint","processId":2788276}

使用 JSON 输出时，颜色将被禁用，并且 --log-syslog-format 设置的格式设置将不适用。

使用 JSON 输出时，将禁用颜色，并且 --log-console-format 设置的格式设置将不适用。

bin/kc.[sh|bat] start --log-syslog-output=default
默认情况下，控制台日志处理程序将纯非结构化数据记录到控制台。要改为使用结构化的 JSON 日志输出，请输入以下命令
2024-04-05T12:31:38.473+02:00 host keycloak 2787568 io.quarkus - 2024-04-05 12:31:38,473 INFO  [io.quarkus] (main) Profile prod activated.

如您所见，时间戳出现了两次，因此您可以通过 --log-syslog-format 属性相应地修改它。

相关选项

值

log

以逗号分隔的列表启用一个或多个日志处理程序。

CLI： --log
Env: KC_LOG

console, file, syslog

log-console-color

启用或禁用向控制台记录时的颜色。

CLI： --log-console-color
Env: KC_LOG_CONSOLE_COLOR

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

true, false（默认）

log-console-format

未结构化控制台日志条目的格式。

如果格式中包含空格，请使用“<format>”转义该值。

CLI： --log-console-format
Env: KC_LOG_CONSOLE_FORMAT

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

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n（默认）

log-console-include-trace

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

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

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

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

true（默认），false

log-console-level

设置控制台处理程序的日志级别。

它指定输出中显示的日志的最详细日志级别。它遵守 log-level 选项中指定的级别，该选项代表整个日志系统的最大详细程度。有关更多信息，请查看日志记录指南。

CLI： --log-console-level
Env: KC_LOG_CONSOLE_LEVEL

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

off, fatal, error, warn, info, debug, trace, all（默认）

log-console-output

将日志输出设置为 JSON 或默认（纯）未结构化日志记录。

CLI： --log-console-output
Env: KC_LOG_CONSOLE_OUTPUT

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

default（默认），json

log-file

设置日志文件路径和文件名。

CLI： --log-file
Env: KC_LOG_FILE

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

data/log/keycloak.log（默认）

log-file-format

设置特定于文件日志条目的格式。

CLI： --log-file-format
Env: KC_LOG_FILE_FORMAT

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

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n（默认）

log-file-include-trace

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

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

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

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

true（默认），false

log-file-level

设置文件处理程序的日志级别。

它指定输出中显示的日志的最详细日志级别。它遵守 log-level 选项中指定的级别，该选项代表整个日志系统的最大详细程度。有关更多信息，请查看日志记录指南。

CLI： --log-file-level
Env: KC_LOG_FILE_LEVEL

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

off, fatal, error, warn, info, debug, trace, all（默认）

log-file-output

将日志输出设置为 JSON 或默认（纯）未结构化日志记录。

CLI： --log-file-output
Env: KC_LOG_FILE_OUTPUT

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

default（默认），json

log-level

根类别的日志级别或以逗号分隔的单个类别及其级别的列表。

对于根类别，您不需要指定类别。

CLI： --log-level
Env: KC_LOG_LEVEL

[info]（默认）

log-syslog-app-name

设置在 RFC5424 格式中格式化消息时使用的应用程序名称。

CLI： --log-syslog-app-name
Env: KC_LOG_SYSLOG_APP_NAME

仅在激活 Syslog 时可用

keycloak（默认）

log-syslog-endpoint

设置 Syslog 服务器的 IP 地址和端口。

CLI： --log-syslog-endpoint
Env: KC_LOG_SYSLOG_ENDPOINT

仅在激活 Syslog 时可用

localhost:514（默认）

log-syslog-format

设置特定于 Syslog 条目的格式。

CLI： --log-syslog-format
Env: KC_LOG_SYSLOG_FORMAT

仅在激活 Syslog 时可用

%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c] (%t) %s%e%n（默认）

log-syslog-include-trace

在 Syslog 中包含跟踪信息。

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

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

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

true（默认），false

log-syslog-level

设置 Syslog 处理程序的日志级别。

它指定输出中显示的日志的最详细日志级别。它遵守 log-level 选项中指定的级别，该选项代表整个日志系统的最大详细程度。有关更多信息，请查看日志记录指南。

CLI： --log-syslog-level
Env: KC_LOG_SYSLOG_LEVEL

仅在激活 Syslog 时可用

off, fatal, error, warn, info, debug, trace, all（默认）

log-syslog-max-length

设置允许发送的消息的最大长度（以字节为单位）。

长度包括头和消息。如果未设置，则当 log-syslog-type 为 rfc5424（默认）时，默认值为 2048；当 log-syslog-type 为 rfc3164 时，默认值为 1024。

CLI： --log-syslog-max-length
Env: KC_LOG_SYSLOG_MAX_LENGTH

仅在激活 Syslog 时可用

log-syslog-output

将 Syslog 输出设置为 JSON 或默认（纯）未结构化日志记录。

CLI： --log-syslog-output
Env: KC_LOG_SYSLOG_OUTPUT

仅在激活 Syslog 时可用

default（默认），json

log-syslog-protocol

设置用于连接到 Syslog 服务器的协议。

CLI： --log-syslog-protocol
Env: KC_LOG_SYSLOG_PROTOCOL

仅在激活 Syslog 时可用

tcp（默认），udp，ssl-tcp

log-syslog-type

设置用于格式化发送消息的 Syslog 类型。

CLI： --log-syslog-type
Env: KC_LOG_SYSLOG_TYPE

仅在激活 Syslog 时可用

rfc5424（默认），rfc3164
在本页上
编辑本指南