Console logging

Print logs to a console output

The console log handler is enabled by default, providing unstructured log messages for the console. As shown in the following section, the more specific console handler configuration takes effect only when the console logging is enabled. Console logging is enabled by default.

Configuring the console log format

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:

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

The format string supports the symbols in the following table:

Symbol Summary Description

%%

%

Renders a simple % character.

%c

Category

Renders the log category name.

%d{xxx}

Date

Renders a date with the given date format string.String syntax defined by java.text.SimpleDateFormat

%e

Exception

Renders a thrown exception.

%h

Hostname

Renders the simple host name.

%H

Qualified host name

Renders the fully qualified hostname, which may be the same as the simple host name, depending on the OS configuration.

%i

Process ID

Renders the current process PID.

%m

Full Message

Renders the log message and an exception, if thrown.

%n

Newline

Renders the platform-specific line separator string.

%N

Process name

Renders the name of the current process.

%p

Level

Renders the log level of the message.

%r

Relative time

Render the time in milliseconds since the start of the application log.

%s

Simple message

Renders only the log message without exception trace.

%t

Thread name

Renders the thread name.

%t{id}

Thread ID

Render the thread ID.

%z{<zone name>}

Timezone

Set the time zone of log output to <zone name>.

%L

Line number

Render the line number of the log message.

Setting the logging format

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

  1. Build your desired format template using the preceding table.

  2. Enter the following command:

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

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.

Example: Abbreviate the fully qualified category name
bin/kc.[sh|bat] start --log-console-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"

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

Configuring JSON or plain console logging

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

bin/kc.[sh|bat] start --log-console-output=json
Example Log Message
{"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}

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:

bin/kc.[sh|bat] start --log-console-output=default
Example Log Message
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

Colors

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:

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

Configuring the console log level

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

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

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

Relevant options

Type or Values Default

log-console-color

Enable or disable colors when logging to console.

If this is not present then an attempt will be made to guess if the terminal supports color.

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

Available only when Console log handler is activated

true, false

log-console-format

The format of unstructured console log entries.

If the format has spaces in it, escape the value using "<format>".

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

Available only when Console log handler is activated

String

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

log-console-include-mdc

Include mdc information in the console log.

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

CLI: --log-console-include-mdc
Env: KC_LOG_CONSOLE_INCLUDE_MDC

Available only when Console log handler and MDC logging are activated

true, false

true

log-console-include-trace

Include tracing information in the console log.

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

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

Available only when Console log handler and Tracing is activated

true, false

true

log-console-json-format

Set the format of the produced JSON.

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

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

default, ecs

default

log-console-level

Set the log level for the console 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-console-level
Env: KC_LOG_CONSOLE_LEVEL

Available only when Console log handler is activated

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

all

log-console-output

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

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

Available only when Console log handler is activated

default, json

default

Asynchronous

Type or Values Default

log-console-async

Indicates whether to log asynchronously to console.

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

CLI: --log-console-async
Env: KC_LOG_CONSOLE_ASYNC

Available only when Console log handler is activated

true, false

false

log-console-async-queue-length

The queue length to use before flushing writing when logging to console.

CLI: --log-console-async-queue-length
Env: KC_LOG_CONSOLE_ASYNC_QUEUE_LENGTH

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

Integer

512
On this page
Edit this guide