配置日志

了解如何配置日志

Keycloak 使用 JBoss Logging 框架。以下是可用日志处理程序的高级概述，以及通用的父日志处理程序 root

  • 控制台

  • 文件

  • 系统日志

日志配置

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 级别出现。

将级别配置为单独的选项

在配置特定于类别的日志级别时，您也可以将日志级别设置为单独的 log-level-<category> 选项，而不是为此使用 log-level 选项。当您想要为选定的类别设置日志级别而不覆盖先前设置的 log-level 选项时，这非常有用。

示例

如果您像这样启动服务器

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug"

那么您可以设置环境变量 KC_LOG_LEVEL_ORG_KEYCLOAK=trace 来更改 org.keycloak 类别的日志级别。

log-level-<category> 选项优先于 log-level。这允许您覆盖在 log-level 选项中设置的内容。例如，如果您为上面的 CLI 示例设置 KC_LOG_LEVEL_ORG_HIBERNATE=trace，则 org.hibernate 类别将使用 trace 级别而不是 debug。

请记住，当使用环境变量时，类别名称必须为大写，并且点必须替换为下划线。当使用其他配置源时，类别名称必须“按原样”指定，例如

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug" --log-level-org.keycloak=trace

启用日志处理程序

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

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

可用的处理程序有

  • 控制台

  • 文件

  • 系统日志

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

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

log-level 属性指定全局根日志级别和选定类别的级别。但是，更精细的日志级别方法对于满足现代应用程序的要求是必要的。

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

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

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

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

  • log-syslog-level - 系统日志处理程序

只有在启用了特定的日志处理程序时，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，但系统日志处理程序为 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，必须为系统日志处理程序设置 trace 级别。

为日志处理程序使用不同的 JSON 格式

每个日志处理程序都能够以 JSON 格式输出结构化日志。可以通过格式为 log-<handler>-output=json （其中 <handler> 是日志处理程序）的属性启用它。

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

  • default (默认)

  • ecs

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

ECS 是一个开源的、社区驱动的规范，它定义了一组通用的字段，用于 Elastic 解决方案。ECS 规范正在与 OpenTelemetry Semantic Conventions 融合，目标是创建一个由 OpenTelemetry 维护的单一标准。

为了更改 JSON 输出格式，引入了格式为 log-<handler>-json-format （其中 <handler> 是日志处理程序）的属性

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

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

  • log-syslog-json-format - 系统日志处理程序

示例

如果您想要控制台日志处理程序的 ECS (Elastic Common Schema) 格式的 JSON 日志，您可以输入以下命令

bin/kc.[sh|bat] start --log-console-output=json --log-console-json-format=ecs
示例日志消息
{"@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"}

控制台日志处理程序

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

配置控制台日志格式

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>'"

请注意，当调用包含特殊 shell 字符（如 ;）的命令时，您需要转义字符，使用 CLI。因此，请考虑在配置文件中设置它。

示例：缩写完全限定的类别名称
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 或纯文本控制台日志记录

默认情况下，控制台日志处理程序将纯文本非结构化数据记录到控制台。要改为使用结构化 JSON 日志输出，请输入以下命令

bin/kc.[sh|bat] start --log-console-output=json
示例日志消息
{"timestamp":"2025-02-03T14:52:20.290353085+01:00","sequence":9605,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Keycloak 999.0.0-SNAPSHOT on JVM (powered by Quarkus 3.17.8) started in 4.440s. Listening on: http://0.0.0.0:8080","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host-name","processName":"/usr/lib/jvm/jdk-21.0.3+9/bin/java","processId":76944}

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

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

bin/kc.[sh|bat] start --log-console-output=default
示例日志消息
2025-02-03 14:53:56,653 INFO  [io.quarkus] (main) Keycloak 999.0.0-SNAPSHOT on JVM (powered by Quarkus 3.17.8) started in 4.795s. Listening on: http://0.0.0.0:8080

颜色

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

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

配置控制台日志级别

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

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

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

文件日志记录

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

启用文件日志记录

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

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

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

配置日志文件的位置和名称

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

  1. 创建一个可写目录以存储日志文件。

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

  2. 输入此命令

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

配置文件处理程序格式

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

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

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

配置文件日志级别

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

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

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

使用系统日志进行集中式日志记录

Keycloak 提供了将日志发送到远程系统日志服务器的功能。它利用 RFC 5424 中定义的协议。

启用系统日志处理程序

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

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

配置系统日志应用程序名称

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

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

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

配置系统日志端点

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

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

当启用系统日志处理程序时，主机使用 localhost 作为主机值。默认端口为 514。

配置系统日志级别

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

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

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

配置系统日志协议

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

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

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

配置系统日志格式

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

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

  2. 输入以下命令

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

请注意，当调用包含特殊 shell 字符（如 ;）的命令时，您需要转义字符，使用 CLI。因此，请考虑在配置文件中设置它。

示例：缩写完全限定的类别名称
bin/kc.[sh|bat] start --log-syslog-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"

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

配置系统日志类型

系统日志根据特定的 RFC 规范使用不同的消息格式。要使用不同的消息格式更改系统日志类型，请使用 --log-syslog-type 选项，如下所示

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

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

  • rfc5424 (默认)

  • rfc3164

首选的系统日志类型是 RFC 5424，它取代了 RFC 3164，后者被称为 BSD 系统日志协议。

配置系统日志最大消息长度

要设置允许发送的最大消息长度（以字节为单位），请使用 --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

配置系统日志结构化输出

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

bin/kc.[sh|bat] start --log-syslog-output=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 设置的格式设置将不适用。

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

bin/kc.[sh|bat] start --log-syslog-output=default
示例日志消息
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-level

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

对于根类别，您无需指定类别。

CLI: --log-level
Env: KC_LOG_LEVEL

[info] (默认)

控制台

值

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-json-format

设置生成的 JSON 的格式。

CLI: --log-console-json-format
Env: KC_LOG_CONSOLE_JSON_FORMAT

仅在激活控制台日志处理程序且输出设置为 'json' 时可用

default (默认), ecs

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-json-format

设置生成的 JSON 的格式。

CLI: --log-file-json-format
Env: KC_LOG_FILE_JSON_FORMAT

仅在激活文件日志处理程序且输出设置为 'json' 时可用

default (默认), ecs

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-syslog-app-name

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

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

仅在激活系统日志时可用

keycloak (默认)

log-syslog-endpoint

设置系统日志服务器的 IP 地址和端口。

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

仅在激活系统日志时可用

localhost:514 (默认)

log-syslog-format

设置特定于系统日志条目的格式。

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

仅在激活系统日志时可用

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

log-syslog-include-trace

在系统日志中包含跟踪信息。

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

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

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

true (默认), false

log-syslog-json-format

设置生成的 JSON 的格式。

CLI: --log-syslog-json-format
Env: KC_LOG_SYSLOG_JSON_FORMAT

仅在激活系统日志且输出设置为 'json' 时可用

default (默认), ecs

log-syslog-level

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

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

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

仅在激活系统日志时可用

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

仅在激活系统日志时可用

log-syslog-output

将系统日志输出设置为 JSON 或默认（纯文本）非结构化日志记录。

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

仅在激活系统日志时可用

default (默认), json

log-syslog-protocol

设置用于连接到系统日志服务器的协议。

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

仅在激活系统日志时可用

tcp (默认), udp, ssl-tcp

log-syslog-type

设置用于格式化发送消息的系统日志类型。

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

仅在激活系统日志时可用

rfc5424 (默认), rfc3164
在此页上
编辑本指南