File logging

Store logs into a file

As an alternative to logging to the console, you can use structured/unstructured logging to a file stored in the filesystem. The more specific file handler configuration mentioned below will only take effect when the file logging is enabled.

Enable file logging

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

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

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

Configuring the location and name of the log file

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

  1. Create a writable directory to store the log file.

    If the directory is not writable, Keycloak starts correctly, but it issues an error and no log file is created.

  2. Enter this command:

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

Configuring the file handler format

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

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

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

Configuring the file log level

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

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

For more information, see [Specify log level for each handler].

Relevant options

Type or Values Default

log-file-format

Set a format specific to file log entries.

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

Available only when File log handler is activated

String

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

log-file-include-mdc

Include MDC information in the file log.

If the log-file-format option is specified, this option has no effect.

CLI: --log-file-include-mdc
Env: KC_LOG_FILE_INCLUDE_MDC

Available only when File log handler and MDC logging are activated

true, false

true

log-file-include-trace

Include tracing information in the file log.

If the log-file-format option is specified, this option has no effect.

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

Available only when File log handler and Tracing is activated

true, false

true

log-file-json-format

Set the format of the produced JSON.

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

Available only when File log handler is activated and output is set to 'json'

default, ecs

default

log-file-level

Set the log level for the file handler.

It specifies the most verbose log level for logs shown in the output. It respects levels specified in the log-level option, which represents the maximal verbosity for the whole logging system. For more information, check the Logging guide.

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

Available only when File log handler is activated

off, fatal, error, warn, info, debug, trace, all

all

log-file-output

Set the log output to JSON or default (plain) unstructured logging.

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

Available only when File log handler is activated

default, json

default

Asynchronous

Type or Values Default

log-file-async

Indicates whether to log asynchronously to file log.

If not set, value from the parent property log-async is used.

CLI: --log-file-async
Env: KC_LOG_FILE_ASYNC

Available only when File log handler is activated

true, false

false

log-file-async-queue-length

The queue length to use before flushing writing when logging to file log.

CLI: --log-file-async-queue-length
Env: KC_LOG_FILE_ASYNC_QUEUE_LENGTH

Available only when File log handler is activated and asynchronous logging is enabled

Integer

512
On this page
Edit this guide