Red Hat Summit Red Hat SummitSuporteConsoleDesenvolvedoresComeçar um testeContato

Este conteúdo não está disponível no idioma selecionado.

Chapter 16. Configuring logging

Configure logging for Red Hat build of Keycloak.

Red Hat build of Keycloak uses the JBoss Logging framework. The following is a high-level overview for the available log handlers with the common parent log handler root:

  • console
  • file
  • syslog

16.1. Logging configuration
Copiar o link

Logging is done on a per-category basis in Red Hat build of Keycloak. You can configure logging for the root log level or for more specific categories such as org.hibernate or org.keycloak. It is also possible to tailor log levels for each particular log handler.

This chapter describes how to configure logging.

16.1.1. Log levels
Copiar o link

The following table defines the available log levels.

Expand
LevelDescription

FATAL

Critical failures with complete inability to serve any kind of request.

ERROR

A significant error or problem leading to the inability to process requests.

WARN

A non-critical error or problem that might not require immediate correction.

INFO

Red Hat build of Keycloak lifecycle events or important information. Low frequency.

DEBUG

More detailed information for debugging purposes, such as database logs. Higher frequency.

TRACE

Most detailed debugging information. Very high frequency.

ALL

Special level for all log messages.

OFF

Special level to turn logging off entirely (not recommended).

16.1.2. Configuring the root log level
Copiar o link

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: 

bin/kc.[sh|bat] start --log-level=<root-level>
Copy to Clipboard Toggle word wrap

Use these guidelines for this command:

  • For <root-level>, supply a level defined in the preceding table.
  • The log level is case-insensitive. For example, you could either use DEBUG or debug.
  • If you were to accidentally set the log level twice, the last occurrence in the list becomes the log level. For example, if you included the syntax --log-level="info,…​,DEBUG,…​", the root logger would be DEBUG.

16.1.3. Configuring category-specific log levels
Copiar o link

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

bin/kc.[sh|bat] start --log-level="<root-level>,<org.category1>:<org.category1-level>"
Copy to Clipboard Toggle word wrap

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

Example

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug,org.hibernate.hql.internal.ast:info"
Copy to Clipboard Toggle word wrap

This example sets the following log levels:

  • Root log level for all loggers is set to INFO.
  • The hibernate log level in general is set to debug.
  • To keep SQL abstract syntax trees from creating verbose log output, the specific subcategory org.hibernate.hql.internal.ast is set to info. As a result, the SQL abstract syntax trees are omitted instead of appearing at the debug level.

16.1.4. Adding context for log messages
Copiar o link

Note

Log messages with Mapped Diagnostic Context (MDC) is Preview and is not fully supported. This feature is disabled by default.

You can enable additional context information for each log line like the current realm and client that is executing the request.

Use the option log-mdc-enabled to enable it.

Example configuration

bin/kc.[sh|bat] start --features=log-mdc --log-mdc-enabled=true
Copy to Clipboard Toggle word wrap

Example output

2025-06-20 14:13:01,772 {kc.clientId=security-admin-console, kc.realmName=master} INFO ...
Copy to Clipboard Toggle word wrap

Specify which keys to be added by setting the configuration option log-mdc-keys.

16.1.5. Configuring levels as individual options
Copiar o link

When configuring category-specific log levels, you can also set the log levels as individual log-level-<category> options instead of using the log-level option for that. This is useful when you want to set the log levels for selected categories without overwriting the previously set log-level option.

Example

If you start the server as: 

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug"
Copy to Clipboard Toggle word wrap

you can then set an environmental variable KC_LOG_LEVEL_ORG_KEYCLOAK=trace to change the log level for the org.keycloak category.

The log-level-<category> options take precedence over log-level. This allows you to override what was set in the log-level option. For instance if you set KC_LOG_LEVEL_ORG_HIBERNATE=trace for the CLI example above, the org.hibernate category will use the trace level instead of debug.

Bear in mind that when using the environmental variables, the category name must be in uppercase and the dots must be replaced with underscores. When using other config sources, the category name must be specified "as is", for example: 

bin/kc.[sh|bat] start --log-level="INFO,org.hibernate:debug" --log-level-org.keycloak=trace
Copy to Clipboard Toggle word wrap

16.2. Enabling log handlers
Copiar o link

To enable log handlers, enter the following command: 

bin/kc.[sh|bat] start --log="<handler1>,<handler2>"
Copy to Clipboard Toggle word wrap

The available handlers are:

  • console
  • file
  • syslog

The more specific handler configuration mentioned below will only take effect when the handler is added to this comma-separated list.

16.2.1. Specify log level for each handler
Copiar o link

The log-level property specifies the global root log level and levels for selected categories. However, a more fine-grained approach for log levels is necessary to comply with the modern application requirements.

To set log levels for particular handlers, properties in format log-<handler>-level (where <handler> is available log handler) were introduced.

It means properties for log level settings look like this:

  • log-console-level - Console log handler
  • log-file-level - File log handler
  • log-syslog-level - Syslog log handler
Note

The log-<handler>-level properties are available only when the particular log handlers are enabled. More information in log handlers settings below.

Only log levels specified in Section 16.1.1, “Log levels” section are accepted, and must be in lowercase. There is no support for specifying particular categories for log handlers yet.

16.2.1.1. General principle
Copiar o link

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.

16.2.1.2. Examples
Copiar o link

Example: debug for file handler, but info for console handler:

bin/kc.[sh|bat] start --log=console,file --log-level=debug --log-console-level=info
Copy to Clipboard Toggle word wrap

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.

Example: warn for all handlers, but debug for file handler:

bin/kc.[sh|bat] start --log=console,file,syslog --log-level=debug --log-console-level=warn --log-syslog-level=warn
Copy to Clipboard Toggle word wrap

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

Example: info for all handlers, but debug+org.keycloak.events:trace for Syslog handler:

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
Copy to Clipboard Toggle word wrap

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

16.2.2. Use different JSON format for log handlers
Copiar o link

Every log handler provides the ability to have structured log output in JSON format. It can be enabled by properties in the format log-<handler>-output=json (where <handler> is a log handler).

If you need a different format of the produced JSON, you can leverage the following JSON output formats:

  • default (default)
  • ecs

The ecs value refers to the ECS (Elastic Common Schema).

ECS is an open-source, community-driven specification that defines a common set of fields to be used with Elastic solutions. The ECS specification is being converged with OpenTelemetry Semantic Conventions with the goal of creating a single standard maintained by OpenTelemetry.

In order to change the JSON output format, properties in the format log-<handler>-json-format (where <handler> is a log handler) were introduced:

  • log-console-json-format - Console log handler
  • log-file-json-format - File log handler
  • log-syslog-json-format - Syslog log handler

16.2.2.1. Example
Copiar o link

If you want to have JSON logs in ECS (Elastic Common Schema) format for the console log handler, you can enter the following command: 

bin/kc.[sh|bat] start --log-console-output=json --log-console-json-format=ecs
Copy to Clipboard Toggle word wrap

Example Log Message

{"@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"}
Copy to Clipboard Toggle word wrap

16.2.3. Asynchronous logging
Copiar o link

Red Hat build of Keycloak supports asynchronous logging, which might be useful for deployments requiring high throughput and low latency. Asynchronous logging uses a separate thread to take care of processing all log records. The logging handlers are invoked in exactly the same way as with synchronous logging, only done in separate threads. You can enable asynchronous logging for all Red Hat build of Keycloak log handlers. A dedicated thread will be created for every log handler with enabled asynchronous logging.

The underlying mechanism for asynchronous logging uses a queue for processing log records. Every new log record is added to the queue and then published to the particular log handler with enabled asynchronous logging. Every log handler has a different queue.

If the queue is already full, it blocks the main thread and waits for free space in the queue.

16.2.3.1. When to use asynchronous logging
Copiar o link

  • You need lower latencies for incoming requests
  • You need higher throughput
  • You have small worker thread pool and want to offload logging to separate threads
  • You want to reduce the impact of I/O-heavy log handlers
  • You are logging to remote destinations (e.g., network syslog servers) and want to avoid blocking worker threads
Warning

Be aware that enabling asynchronous logging might bring some additional memory overhead due to the additional separate thread and the inner queue. In that case, it is not recommended to use it for resource-constrained environments. Additionally, unexpected server shutdowns create a risk of losing log records.

16.2.3.2. Enable asynchronous logging
Copiar o link

You can enable asynchronous logging globally for all log handlers by using log-async property as follows: 

bin/kc.[sh|bat] start --log-async=true
Copy to Clipboard Toggle word wrap

Or you can enable the asynchronous logging for every specific handler by using properties in the format log-<handler>-async (where <handler> is a log handler). If the property for a specific handler is not set, the value from the parent log-async property is used.

You can use these properties as follows: 

bin/kc.[sh|bat] start --log-console-async=true --log-file-async=true --log-syslog-async=true
Copy to Clipboard Toggle word wrap
  • log-console-async - Console log handler
  • log-file-async - File log handler
  • log-syslog-async - Syslog log handler

16.2.3.3. Change queue length
Copiar o link

You can change the size of the queue used for the asynchronous logging. The default size is 512 log records in the queue.

You can change the queue length as follows: 

bin/kc.[sh|bat] start --log-console-async-queue-length=512 --log-file-async-queue-length=512 --log-syslog-async-queue-length=512
Copy to Clipboard Toggle word wrap

These properties are available only when asynchronous logging is enabled for these specific log handlers.

16.2.4. HTTP Access Logging
Copiar o link

Red Hat build of Keycloak supports HTTP access logging to record details of incoming HTTP requests. While access logs are often used for debugging and traffic analysis, they are also important for security auditing and compliance monitoring, helping administrators track access patterns, identify suspicious activity, and maintain audit trails.

These logs are written at the INFO level, so make sure your logging configuration includes this level — either globally (e.g. log-level=info) or specifically for the access log category (e.g. log-level=org.keycloak.http.access-log:info). When HTTP access logs are enabled, they are shown by default, as INFO level is the default log level for Red Hat build of Keycloak.

16.2.4.1. How to enable
Copiar o link

You can enable HTTP access logging by using http-access-log-enabled property as follows: 

bin/kc.[sh|bat] start --http-access-log-enabled=true
Copy to Clipboard Toggle word wrap

16.2.4.2. Change log format/pattern
Copiar o link

You can change format/pattern of the access log records by using http-access-log-pattern property as follows: 

bin/kc.[sh|bat] start --http-access-log-pattern=combined
Copy to Clipboard Toggle word wrap

Predefined named patterns:

  • common (default) - prints basic information about the request
  • combined - prints basic information about the request + information about referer and user agent
  • long - prints comprehensive information about the request with all its headers

You can even specify your own pattern with your required data to be logged, such as: 

bin/kc.[sh|bat] start --http-access-log-pattern='%A %{METHOD} %{REQUEST_URL} %{i,User-Agent}'
Copy to Clipboard Toggle word wrap

Consult the Quarkus documentation for the full list of variables that can be used.

16.2.4.3. Exclude specific URL paths
Copiar o link

It is possible to exclude specific URL paths from the HTTP access logging, so they will not be recorded.

You can use regular expressions to exclude them, such as: 

bin/kc.[sh|bat] start --http-access-log-exclude='/realms/my-internal-realm/.*'
Copy to Clipboard Toggle word wrap

In this case, all calls to the /realms/my-internal-realm/ and subsequent paths will be excluded from the HTTP Access log.

16.3. Console log handler
Copiar o link

The console log handler is enabled by default, providing unstructured log messages for the console.

16.3.1. Configuring the console log format
Copiar o link

Red Hat build of 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:

Expand
SymbolSummaryDescription

%%

%

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.

16.3.2. Setting the logging format
Copiar o link

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>'"
    Copy to Clipboard Toggle word wrap

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'"
Copy to Clipboard Toggle word wrap

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

16.3.3. Configuring JSON or plain console logging
Copiar o link

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
Copy to Clipboard Toggle word wrap

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}
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

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
Copy to Clipboard Toggle word wrap

16.3.4. Colors
Copiar o link

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>
Copy to Clipboard Toggle word wrap

16.3.5. Configuring the console log level
Copiar o link

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
Copy to Clipboard Toggle word wrap

For more information, see the section Section 16.2.1, “Specify log level for each handler” above.

16.4. File logging
Copiar o link

As an alternative to logging to the console, you can use unstructured logging to a file.

16.4.1. Enable file logging
Copiar o link

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

bin/kc.[sh|bat] start --log="console,file"
Copy to Clipboard Toggle word wrap

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

16.4.2. Configuring the location and name of the log file
Copiar o link

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, Red Hat build of Keycloak will start correctly, but it will issue an error and no log file will be created.

  2. Enter this command: 

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

16.4.3. Configuring the file handler format
Copiar o link

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

bin/kc.[sh|bat] start --log-file-format="<pattern>"
Copy to Clipboard Toggle word wrap

See Section 16.3.1, “Configuring the console log format” for more information and a table of the available pattern configuration.

16.4.4. Configuring the file log level
Copiar o link

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
Copy to Clipboard Toggle word wrap

For more information, see the section Section 16.2.1, “Specify log level for each handler” above.

16.5. Centralized logging using Syslog
Copiar o link

Red Hat build of Keycloak provides the ability to send logs to a remote Syslog server. It utilizes the protocol defined in RFC 5424.

16.5.1. Enable the Syslog handler
Copiar o link

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

bin/kc.[sh|bat] start --log="console,syslog"
Copy to Clipboard Toggle word wrap

16.5.2. Configuring the Syslog Application Name
Copiar o link

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

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-app-name=kc-p-itadmins
Copy to Clipboard Toggle word wrap

If not set, the application name defaults to keycloak.

16.5.3. Configuring the Syslog endpoint
Copiar o link

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

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-endpoint=myhost:12345
Copy to Clipboard Toggle word wrap

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

16.5.4. Configuring the Syslog log level
Copiar o link

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

bin/kc.[sh|bat] start --log-syslog-level=warn
Copy to Clipboard Toggle word wrap

For more information, see the section Section 16.2.1, “Specify log level for each handler” above.

16.5.5. Configuring the Syslog protocol
Copiar o link

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

bin/kc.[sh|bat] start --log="console,syslog" --log-syslog-protocol=udp
Copy to Clipboard Toggle word wrap

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

16.5.6. Configuring the Syslog counting framing
Copiar o link

By default, Syslog messages sent over TCP or SSL-TCP are prefixed with the message size, as required by certain Syslog receivers. This behavior is controlled by the --log-syslog-counting-framing option.

To explicitly enable or disable this feature, use the following command: 

bin/kc.[sh|bat] start --log-syslog-counting-framing=true
Copy to Clipboard Toggle word wrap

You can set the value to one of the following:

  • protocol-dependent (default) – Enable counting framing only when the log-syslog-protocol is tcp or ssl-tcp.
  • true – Always enable counting framing by prefixing messages with their size.
  • false – Never use counting framing.

Note that using protocol-dependent ensures compatibility with most Syslog servers by enabling the prefix only when required by the protocol.

16.5.7. Configuring the Syslog log format
Copiar o link

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-syslog-format="'<format>'"
    Copy to Clipboard Toggle word wrap

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-syslog-format="'%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n'"
Copy to Clipboard Toggle word wrap

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

16.5.8. Configuring the Syslog type
Copiar o link

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: 

bin/kc.[sh|bat] start --log-syslog-type=rfc3164
Copy to Clipboard Toggle word wrap

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

  • rfc5424 (default)
  • rfc3164

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

16.5.9. Configuring the Syslog maximum message length
Copiar o link

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

bin/kc.[sh|bat] start --log-syslog-max-length=1536
Copy to Clipboard Toggle word wrap

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:

  • 2048B - for RFC 5424
  • 1024B - for RFC 3164

16.5.10. Configuring the Syslog structured output
Copiar o link

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: 

bin/kc.[sh|bat] start --log-syslog-output=json
Copy to Clipboard Toggle word wrap

Example Log Message

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}
Copy to Clipboard Toggle word wrap

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: 

bin/kc.[sh|bat] start --log-syslog-output=default
Copy to Clipboard Toggle word wrap

Example Log Message

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.
Copy to Clipboard Toggle word wrap

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

16.6. Relevant options
Copiar o link

Expand
 Value

log

Enable one or more log handlers in a comma-separated list.

CLI: --log
Env: KC_LOG

console, file, syslog

log-async

Indicates whether to log asynchronously to all handlers.

CLI: --log-async
Env: KC_LOG_ASYNC

true, false (default)

log-level

The log level of the root category or a comma-separated list of individual categories and their levels.

For the root category, you don’t need to specify a category.

CLI: --log-level
Env: KC_LOG_LEVEL

[info] (default)

log-level-<category>

The log level of a category.

Takes precedence over the log-level option.

CLI: --log-level-<category>
Env: KC_LOG_LEVEL_<CATEGORY>

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

log-mdc-enabled 🛠

Indicates whether to add information about the realm and other information to the mapped diagnostic context.

All elements will be prefixed with kc.

CLI: --log-mdc-enabled
Env: KC_LOG_MDC_ENABLED

Available only when log-mdc preview feature is enabled

true, false (default)

log-mdc-keys

Defines which information should be added to the mapped diagnostic context as a comma-separated list.

CLI: --log-mdc-keys
Env: KC_LOG_MDC_KEYS

Available only when MDC logging is enabled

realmName, clientId, userId, ipAddress, org, sessionId, authenticationSessionId, authenticationTabId

16.6.1. Console
Copiar o link

Expand
 Value

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 (default)

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

512 (default)

log-console-color

Enable or disable colors when logging to console.

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

Available only when Console log handler is activated

true, false (default)

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

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

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 (default), false

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 (default), false

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 (default), ecs

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 (default)

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 (default), json

16.6.2. File
Copiar o link

Expand
 Value

log-file

Set the log file path and filename.

CLI: --log-file
Env: KC_LOG_FILE

Available only when File log handler is activated

data/log/keycloak.log (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 (default)

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

512 (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

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

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 (default), false

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 (default), false

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 (default), ecs

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 (default)

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 (default), json

16.6.3. Syslog
Copiar o link

Expand
 Value

log-syslog-app-name

Set the app name used when formatting the message in RFC5424 format.

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

Available only when Syslog is activated

keycloak (default)

log-syslog-async

Indicates whether to log asynchronously to Syslog.

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

CLI: --log-syslog-async
Env: KC_LOG_SYSLOG_ASYNC

Available only when Syslog is activated

true, false (default)

log-syslog-async-queue-length

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

CLI: --log-syslog-async-queue-length
Env: KC_LOG_SYSLOG_ASYNC_QUEUE_LENGTH

Available only when Syslog is activated and asynchronous logging is enabled

512 (default)

log-syslog-counting-framing

If true, the message being sent is prefixed with the size of the message.

If protocol-dependent, the default value is true when log-syslog-protocol is tcp or ssl-tcp, otherwise false.

CLI: --log-syslog-counting-framing
Env: KC_LOG_SYSLOG_COUNTING_FRAMING

Available only when Syslog is activated

true, false, protocol-dependent (default)

log-syslog-endpoint

Set the IP address and port of the Syslog server.

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

Available only when Syslog is activated

localhost:514 (default)

log-syslog-format

Set a format specific to Syslog entries.

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

Available only when Syslog is activated

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

log-syslog-include-mdc

Include MDC information in the Syslog.

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

CLI: --log-syslog-include-mdc
Env: KC_LOG_SYSLOG_INCLUDE_MDC

Available only when Syslog handler and MDC logging are activated

true (default), false

log-syslog-include-trace

Include tracing information in the Syslog.

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

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

Available only when Syslog handler and Tracing is activated

true (default), false

log-syslog-json-format

Set the format of the produced JSON.

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

Available only when Syslog is activated and output is set to 'json'

default (default), ecs

log-syslog-level

Set the log level for the Syslog 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-syslog-level
Env: KC_LOG_SYSLOG_LEVEL

Available only when Syslog is activated

off, fatal, error, warn, info, debug, trace, all (default)

log-syslog-max-length

Set the maximum length, in bytes, of the message allowed to be sent.

The length includes the header and the message. If not set, the default value is 2048 when log-syslog-type is rfc5424 (default) and 1024 when log-syslog-type is rfc3164.

CLI: --log-syslog-max-length
Env: KC_LOG_SYSLOG_MAX_LENGTH

Available only when Syslog is activated

 

log-syslog-output

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

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

Available only when Syslog is activated

default (default), json

log-syslog-protocol

Set the protocol used to connect to the Syslog server.

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

Available only when Syslog is activated

tcp (default), udp, ssl-tcp

log-syslog-type

Set the Syslog type used to format the sent message.

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

Available only when Syslog is activated

rfc5424 (default), rfc3164

16.6.4. HTTP Access log
Copiar o link

Expand
 Value

http-access-log-enabled

If HTTP access logging is enabled.

By default this will log records in console.

CLI: --http-access-log-enabled
Env: KC_HTTP_ACCESS_LOG_ENABLED

true, false (default)

http-access-log-exclude

A regular expression that can be used to exclude some paths from logging.

For instance, /realms/my-realm/.* will exclude all subsequent endpoints for realm my-realm from the log.

CLI: --http-access-log-exclude
Env: KC_HTTP_ACCESS_LOG_EXCLUDE

Available only when HTTP Access log is enabled

 

http-access-log-pattern

The HTTP access log pattern.

You can use the available named formats, or use custom format described in Quarkus documentation.

CLI: --http-access-log-pattern
Env: KC_HTTP_ACCESS_LOG_PATTERN

Available only when HTTP Access log is enabled

common (default), combined, long, or any

Voltar ao topo
Red Hat logoGithubredditYoutubeTwitter

Aprender

Experimente, compre e venda

Comunidades

Sobre a documentação da Red Hat

Ajudamos os usuários da Red Hat a inovar e atingir seus objetivos com nossos produtos e serviços com conteúdo em que podem confiar. Explore nossas atualizações recentes.

Tornando o open source mais inclusivo

A Red Hat está comprometida em substituir a linguagem problemática em nosso código, documentação e propriedades da web. Para mais detalhes veja o Blog da Red Hat.

Sobre a Red Hat

Fornecemos soluções robustas que facilitam o trabalho das empresas em plataformas e ambientes, desde o data center principal até a borda da rede.

Theme

© 2025 Red Hat