이 콘텐츠는 선택한 언어로 제공되지 않습니다.

Chapter 13. Configuring logging


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

  • root

    • console (default)
    • file

13.1. Logging configuration

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. This chapter describes how to configure logging.

13.1.1. Log levels

The following table defines the available log levels.

Expand

Level

Description

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).

13.1.2. Configuring the root log level

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.

13.1.3. Configuring category-specific log levels

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.

13.2. Enabling log handlers

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 and file. The more specific handler configuration mentioned below will only take effect when the handler is added to this comma-separated list.

13.3. Console log handler

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

13.3.1. Configuring the console log format

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

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.

13.3.2. 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>'"
    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].

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

Example Log Message

{"timestamp":"2022-02-25T10:31:32.452+01:00","sequence":8442,"loggerClassName":"org.jboss.logging.Logger","loggerName":"io.quarkus","level":"INFO","message":"Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.253s. Listening on: http://0.0.0.0:8080","threadName":"main","threadId":1,"mdc":{},"ndc":"","hostName":"host-name","processName":"QuarkusEntryPoint","processId":36946}
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:

2022-03-02 10:36:50,603 INFO  [io.quarkus] (main) Keycloak 18.0.0-SNAPSHOT on JVM (powered by Quarkus 2.7.2.Final) started in 3.615s. Listening on: http://0.0.0.0:8080
Copy to Clipboard Toggle word wrap

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

13.4. File logging

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

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

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

13.4.2. 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, 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

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

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

13.5. Relevant options

Expand
 Value

log-console-color

Enable or disable colors when logging to console.

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

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

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

log-console-output

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

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

default (default), json

log-file

Set the log file path and filename.

CLI: --log-file
Env: KC_LOG_FILE

data/log/keycloak.log (default)

log-file-format

Set a format specific to file log entries.

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

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

log-file-output

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

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

default (default), json

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)

맨 위로 이동
Red Hat logoGithubredditYoutubeTwitter

자세한 정보

평가판, 구매 및 판매

커뮤니티

Red Hat 문서 정보

Red Hat을 사용하는 고객은 신뢰할 수 있는 콘텐츠가 포함된 제품과 서비스를 통해 혁신하고 목표를 달성할 수 있습니다. 최신 업데이트를 확인하세요.

보다 포괄적 수용을 위한 오픈 소스 용어 교체

Red Hat은 코드, 문서, 웹 속성에서 문제가 있는 언어를 교체하기 위해 최선을 다하고 있습니다. 자세한 내용은 다음을 참조하세요.Red Hat 블로그.

Red Hat 소개

Red Hat은 기업이 핵심 데이터 센터에서 네트워크 에지에 이르기까지 플랫폼과 환경 전반에서 더 쉽게 작업할 수 있도록 강화된 솔루션을 제공합니다.

Theme

© 2025 Red Hat