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 Console logging 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 Configuring logging.

Log file rotation

By default, log file rotation is enabled. The log file is rotated when its size exceeds 10 MB, and up to 5 backup files are kept. The log file is also rotated on server start by default.

To disable log file rotation entirely, use the following configuration:

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

Configure rotation settings

To change the maximum log file size before rotation:

bin/kc.[sh|bat] start --log="console,file" --log-file-rotation-max-file-size=50M

To change the number of backup files to keep:

bin/kc.[sh|bat] start --log="console,file" --log-file-rotation-max-backup-index=3

To disable rotation on server start, while keeping size-based rotation:

bin/kc.[sh|bat] start --log="console,file" --log-file-rotation-rotate-on-boot=false

To enable time-based rotation (e.g. daily), set a date-time format suffix:

bin/kc.[sh|bat] start --log="console,file" --log-file-rotation-file-suffix=.yyyy-MM-dd

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

log-file-rotation-enabled

Enables log file rotation.

CLI: --log-file-rotation-enabled
Env: KC_LOG_FILE_ROTATION_ENABLED

Available only when File log handler is activated

true, false

true

log-file-rotation-file-suffix

Set the log file handler rotation file suffix.

When used, the file will be rotated based on its suffix. Example: .yyyy-MM-dd to rotate daily. Note: If the suffix ends with .zip or .gz, the rotation file will also be compressed.

CLI: --log-file-rotation-file-suffix
Env: KC_LOG_FILE_ROTATION_FILE_SUFFIX

Available only when File log handler is activated and log file rotation is enabled

String

log-file-rotation-max-backup-index

The maximum number of backup log files to keep.

CLI: --log-file-rotation-max-backup-index
Env: KC_LOG_FILE_ROTATION_MAX_BACKUP_INDEX

Available only when File log handler is activated and log file rotation is enabled

Integer

5

log-file-rotation-max-file-size

The maximum log file size, after which a rotation is executed.

Supports size suffixes (e.g. 10M, 1G).

CLI: --log-file-rotation-max-file-size
Env: KC_LOG_FILE_ROTATION_MAX_FILE_SIZE

Available only when File log handler is activated and log file rotation is enabled

String

10M

log-file-rotation-rotate-on-boot

Indicates whether to rotate log files on server start.

CLI: --log-file-rotation-rotate-on-boot
Env: KC_LOG_FILE_ROTATION_ROTATE_ON_BOOT

Available only when File log handler is activated and log file rotation is enabled

true, false

true

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