Configuring logging

The following table defines the available log levels.

When no log level configuration exists for a more specific category logger, the enclosing category is used instead. When there is no enclosing category, the root logger level is used.

To set the root log level, enter the following command:

Use these guidelines for this command:

You can set different log levels for specific areas in Keycloak. Use this command to provide a comma-separated list of categories for which you want a different log level:

A configuration that applies to a category also applies to its sub-categories unless you include a more specific matching sub-category.

This example sets the following log levels:

It is necessary to understand that setting the log levels for each particular handler does not override the root level specified in the log-level property. Log handlers respect the root log level, which represents the maximal verbosity for the whole logging system. It means individual log handlers can be configured to be less verbose than the root logger, but not more.

Specifically, when an arbitrary log level is defined for the handler, it does not mean the log records with the log level will be present in the output. In that case, the root log-level must also be assessed. Log handler levels provide the restriction for the root log level, and the default log level for log handlers is all - without any restriction.

The root log level is set to debug, so every log handler inherits the value - so does the file log handler. To hide debug records in the console, we need to set the minimal (least severe) level to info for the console handler.

The root level must be set to the most verbose required level (debug in this case), and other log handlers must be amended accordingly.

In order to see the org.keycloak.events:trace, the trace level must be set for the Syslog handler.

Keycloak uses a pattern-based logging formatter that generates human-readable text logs by default.

The logging format template for these lines can be applied at the root level. The default format template is:

The format string supports the symbols in the following table:

To set the logging format for a logged line, perform these steps:

Note that you need to escape characters when invoking commands containing special shell characters such as ; using the CLI. Therefore, consider setting it in the configuration file instead.

This example abbreviates the category name to three characters by setting [%c{3.}] in the template instead of the default [%c].

By default, the console log handler logs plain unstructured data to the console. To use structured JSON log output instead, enter the following command:

When using JSON output, colors are disabled and the format settings set by --log-console-format will not apply.

To use unstructured logging, enter the following command:

Colored console log output for unstructured logs is disabled by default. Colors may improve readability, but they can cause problems when shipping logs to external log aggregation systems. To enable or disable color-coded console log output, enter following command:

Log level for console log handler can be specified by --log-console-level property as follows:

For more information, see the section Specify log level for each handler above.

Logging to a file is disabled by default. To enable it, enter the following command:

A log file named keycloak.log is created inside the data/log directory of your Keycloak installation.

To change where the log file is created and the file name, perform these steps:

To configure a different logging format for the file log handler, enter the following command:

See Configuring the console log format for more information and a table of the available pattern configuration.

Log level for file log handler can be specified by --log-file-level property as follows:

For more information, see the section Specify log level for each handler above.

To enable logging using Syslog, add it to the list of activated log handlers as follows:

To set a different application name, add the --log-syslog-app-name option as follows:

If not set, the application name defaults to keycloak.

To configure the endpoint(host:port) of your centralized logging system, enter the following command and substitute the values with your specific values:

When the Syslog handler is enabled, the host is using localhost as host value. The Default port is 514.

Log level for Syslog log handler can be specified by --log-syslog-level property as follows:

For more information, see the section Specify log level for each handler above.

Syslog uses TCP as the default protocol for communication. To use UDP instead of TCP, add the --log-syslog-protocol option as follows:

The available protocols are: tpc, udp, and ssl-tcp.

To set the logging format for a logged line, perform these steps:

Note that you need to escape characters when invoking commands containing special shell characters such as ; using the CLI. Therefore, consider setting it in the configuration file instead.

This example abbreviates the category name to three characters by setting [%c{3.}] in the template instead of the default [%c].

Syslog uses different message formats based on particular RFC specifications. To change the Syslog type with a different message format, use the --log-syslog-type option as follows:

Possible values for the --log-syslog-type option are:

The preferred Syslog type is RFC 5424, which obsoletes RFC 3164, known as BSD Syslog protocol.

To set the maximum length of the message allowed to be sent (in bytes), use the --log-syslog-max-length option as follows:

The length can be specified in memory size format with the appropriate suffix, like 1k or 1K. The length includes the header and the message.

If the length is not explicitly set, the default values are set based on the --log-syslog-type option as follows:

By default, the Syslog log handler sends plain unstructured data to the Syslog server. To use structured JSON log output instead, enter the following command:

When using JSON output, colors are disabled and the format settings set by --log-syslog-format will not apply.

To use unstructured logging, enter the following command:

As you can see, the timestamp is present twice, so you can amend it correspondingly via the --log-syslog-format property.