Quarkus - Configuring Logging

This guide explains logging and how to configure it.

Runtime configuration

Run time logging is configured in the application.properties file, for example to set everything to INFO logging except Hibernate:

quarkus.log.level=INFO
quarkus.log.category."org.hibernate".level=DEBUG

All possible properties are listed in the logging configuration reference.

If you are adding these properties via command line make sure " is escaped. For example -Dquarkus.log.category.\"org.hibernate\".level=DEBUG.

Logging categories

Logging is done on a per-category basis. Each category can be independently configured. A configuration which applies to a category will also apply to all sub-categories of that category, unless there is a more specific matching sub-category configuration. For every category the same settings that are configured on ( console / file / syslog ) apply. These can also be overridden by attaching a one or more named handlers to a category. See example in Named handlers attached to a category

Property Name Default Description

quarkus.log.category."<category-name>".level

INFO [1]

The level to use to configure the category named <category-name>. The quotes are necessary.

quarkus.log.category."<category-name>".use-parent-handlers

true

Specify whether or not this logger should send its output to its parent logger.

quarkus.log.category."<category-name>".handlers=[<handler>]

empty [2]

The names of the handlers that you want to attach to a specific category.

The quotes shown in the property name are required as categories normally contain '.' which must be escaped. An example is shown in File TRACE Logging Configuration.

Root logger configuration

The root logger category is handled separately, and is configured via the following properties:

Property Name Default Description

quarkus.log.level

INFO

The default minimum log level for every log category.

Log levels

There are several log levels you can use:

Level Description

FATAL

A critical service failure/complete inability to service requests of any kind

ERROR

A significant disruption in a request or the inability to service a request

WARN

A non-critical service error or problem that may not require immediate correction

INFO

Service lifecycle events or important related very-low-frequency information

DEBUG

Messages that convey extra information regarding lifecycle or non-request-bound events which may be helpful for debugging

TRACE

Messages that convey extra per-request debugging information that may be very high frequency

Format String

The logging format string supports the following symbols:

Symbol Summary Description

%%

%

Renders a simple % character.

%c

Category

Renders the category name.

%C

Source class

Renders the source class name.[3]

%d{xxx}

Date

Renders a date with the given date format string, which uses the syntax defined by java.text.SimpleDateFormat.

%e

Exception

Renders the thrown exception, if any.

%F

Source file

Renders the source file name.[3]

%h

Host name

Renders the system simple host name.

%H

Qualified host name

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

%i

Process ID

Render the current process PID.

%l

Source location

Renders the source location information, which includes source file name, line number, class name, and method name.[3]

%L

Source line

Renders the source line number.[3]

%m

Full Message

Renders the log message plus exception (if any).

%M

Source method

Renders the source method name.[3]

%n

Newline

Renders the platform-specific line separator string.

%N

Process name

Render the name of the current process.

%p

Level

Render 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 just the log message, with no exception trace.

%t

Thread name

Render the thread name.

%t{id}

Thread ID

Render the thread ID.

%z{<zone name>}

Time zone

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

%X{<MDC property name>}

Mapped Diagnostics Context Value

Renders the value from Mapped Diagnostics Context

%X

Mapped Diagnostics Context Values

Renders all the values from Mapped Diagnostics Context in format {property.key=property.value}

%x

Nested Diagnostics context values

Renders all the values from Nested Diagnostics Context in format {value1.value2}

Alternative Console Logging Formats

It is possible to change the output format of the console log. This can be useful in environments where the output of the Quarkus application is captured by a service which can, for example, process and store the log information for later analysis.

JSON Logging

In order to configure JSON logging, the quarkus-logging-json extension may be employed. Add this extension to your application POM as the following snippet illustrates.

Modifications to POM file to add the JSON logging extension
  <dependencies>
    <!-- ... your other dependencies are here ... -->
    <dependency>
      <groupId>io.quarkus</groupId>
      <artifactId>quarkus-logging-json</artifactId>
    </dependency>
  </dependencies>

The presence of this extension will, by default, replace the output format configuration from the console configuration. This means that the format string and the color settings (if any) will be ignored. The other console configuration items (including those controlling asynchronous logging and the log level) will continue to be applied.

For some, it will make sense to use logging that is humanly readable (unstructured) in dev mode and JSON logging (structured) in production mode. This can be achieved using different profiles, as shown in the following configuration.

Disable JSON logging in application.properties for dev and test mode
%dev.quarkus.log.console.json=false
%test.quarkus.log.console.json=false
Configuration

The JSON logging extension can be configured in various ways. The following properties are supported:

Enabling pretty printing might cause certain processors and JSON parsers to fail.
Printing the details can be expensive as the values are retrieved from the caller. The details include the source class name, source file name, source method name and source line number.

Examples

Console DEBUG Logging, No color, Shortened Time, Shortened Category Prefixes
quarkus.log.console.enable=true
quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
quarkus.log.console.level=DEBUG
quarkus.log.console.color=false

quarkus.log.category."io.quarkus".level=DEBUG
If you are adding these properties via command line make sure " is escaped. For example -Dquarkus.log.category.\"io.quarkus\".level=DEBUG.
File TRACE Logging Configuration
quarkus.log.file.enable=true
# Send output to a trace.log file under the /tmp directory
quarkus.log.file.path=/tmp/trace.log
quarkus.log.file.level=TRACE
quarkus.log.file.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Set 2 categories (io.quarkus.smallrye.jwt, io.undertow.request.security) to TRACE level
quarkus.log.category."io.quarkus.smallrye.jwt".level=TRACE
quarkus.log.category."io.undertow.request.security".level=TRACE
Named handlers attached to a category
# Send output to the console
quarkus.log.file.path=/tmp/trace.log
quarkus.log.console.format=%d{HH:mm:ss} %-5p [%c{2.}] (%t) %s%e%n
# Configure a named handler that logs to console
quarkus.log.handler.console."STRUCTURED_LOGGING".format=%e%n
# Configure a named handler that logs to file
quarkus.log.handler.file."STRUCTURED_LOGGING_FILE".enable=true
quarkus.log.handler.file."STRUCTURED_LOGGING_FILE".format=%e%n
# Configure the category and link the two named handlers to it
quarkus.log.category."io.quarkus.category".level=INFO
quarkus.log.category."io.quarkus.category".handlers=STRUCTURED_LOGGING,STRUCTURED_LOGGING_FILE

Supported Logging APIs

Applications and components may use any of the following APIs for logging, and the logs will be merged:

Centralized Log Management

If you want to send your logs to a centralized tool like Graylog, Logstash or Fluentd, you can follow the Centralized log management guide.

How to Configure Logging for @QuarkusTest

If you want to configure logging for your @QuarkusTest, don’t forget to set up the maven-surefire-plugin accordingly. In particular, you need to set the appropriate LogManager using the java.util.logging.manager system property.

Example Configuration
<build>
  <plugins>
    <plugin>
      <artifactId>maven-surefire-plugin</artifactId>
      <version>${surefire-plugin.version}</version>
      <configuration>
        <systemPropertyVariables>
          <java.util.logging.manager>org.jboss.logmanager.LogManager</java.util.logging.manager> (1)
          <quarkus.log.level>DEBUG</quarkus.log.level>  (2)
          <maven.home>${maven.home}</maven.home>
        </systemPropertyVariables>
      </configuration>
    </plugin>
  </plugins>
</build>
1 Make sure the org.jboss.logmanager.LogManager is used.
2 Enable debug logging for all logging categories.

If you are using Gradle, add this to your build.gradle:

test {
	systemProperty "java.util.logging.manager", "org.jboss.logmanager.LogManager"
}

Logging configuration reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

The log level of the root category, which is used as the default log level for all categories. In addition to the standard JDK log level JBoss Logging also adds the following: org.jboss.logmanager.Level#FATAL org.jboss.logmanager.Level#ERROR org.jboss.logmanager.Level#WARN org.jboss.logmanager.Level#INFO org.jboss.logmanager.Level#DEBUG org.jboss.logmanager.Level#TRACE

Level

INFO

The default minimum log level

Level

INFO

Console logging

Type

Default

If console logging should be enabled

boolean

true

The log format. Note that this value will be ignored if an extension is present that takes control of console formatting (e.g. an XML or JSON-format extension).

string

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

The console log level.

Level

ALL

If the console logging should be in color. If undefined quarkus takes best guess based on operating system and environment. Note that this value will be ignored if an extension is present that takes control of console formatting (e.g. an XML or JSON-format extension).

boolean

Specify how much the colors should be darkened. Note that this value will be ignored if an extension is present that takes control of console formatting (e.g. an XML or JSON-format extension).

int

0

Indicates whether to log asynchronously

boolean

false

The queue length to use before flushing writing

int

512

Determine whether to block the publisher (rather than drop the message) when the queue is full

block, discard

block

File logging

Type

Default

If file logging should be enabled

boolean

false

The log format

string

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

The level of logs to be written into the file.

Level

ALL

The name of the file in which logs will be written.

File

quarkus.log

Indicates whether to log asynchronously

boolean

false

The queue length to use before flushing writing

int

512

Determine whether to block the publisher (rather than drop the message) when the queue is full

block, discard

block

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

MemorySize

The maximum number of backups to keep.

int

1

File handler rotation file suffix. Example fileSuffix: .yyyy-MM-dd

string

Indicates whether to rotate log files on server initialization. You need to either set a max-file-size or configure a file-suffix for it to work.

boolean

true

Syslog logging

Type

Default

If syslog logging should be enabled

boolean

false

The IP address and port of the syslog server

host:port

localhost:514

The app name used when formatting the message in RFC5424 format

string

The name of the host the messages are being sent from

string

Sets the facility used when calculating the priority of the message as defined by RFC-5424 and RFC-3164

kernel, user-level, mail-system, system-daemons, security, syslogd, line-printer, network-news, uucp, clock-daemon, security2, ftp-daemon, ntp, log-audit, log-alert, clock-daemon2, local-use-0, local-use-1, local-use-2, local-use-3, local-use-4, local-use-5, local-use-6, local-use-7

user-level

Set the SyslogType syslog type this handler should use to format the message sent

rfc5424, rfc3164

rfc5424

Sets the protocol used to connect to the syslog server

tcp, udp, ssl-tcp

tcp

Set to true if the message being sent should be prefixed with the size of the message

boolean

false

Set to true if the message should be truncated

boolean

true

Enables or disables blocking when attempting to reconnect a org.jboss.logmanager.handlers.SyslogHandler.Protocol#TCP TCP or org.jboss.logmanager.handlers.SyslogHandler.Protocol#SSL_TCP SSL TCP protocol

boolean

false

The log message format

string

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

The log level specifying, which message levels will be logged by syslog logger

Level

ALL

Indicates whether to log asynchronously

boolean

false

The queue length to use before flushing writing

int

512

Determine whether to block the publisher (rather than drop the message) when the queue is full

block, discard

block

Logging categories

Type

Default

The log level level for this category

InheritableLevel

inherit

The names of the handlers to link to this category.

list of string

Specify whether or not this logger should send its output to its parent Logger

boolean

true

Console handlers

Type

Default

If console logging should be enabled

boolean

true

The log format. Note that this value will be ignored if an extension is present that takes control of console formatting (e.g. an XML or JSON-format extension).

string

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

Level

ALL

If the console logging should be in color. If undefined quarkus takes best guess based on operating system and environment. Note that this value will be ignored if an extension is present that takes control of console formatting (e.g. an XML or JSON-format extension).

boolean

Specify how much the colors should be darkened. Note that this value will be ignored if an extension is present that takes control of console formatting (e.g. an XML or JSON-format extension).

int

0

Indicates whether to log asynchronously

boolean

false

The queue length to use before flushing writing

int

512

Determine whether to block the publisher (rather than drop the message) when the queue is full

block, discard

block

File handlers

Type

Default

If file logging should be enabled

boolean

false

string

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

The level of logs to be written into the file.

Level

ALL

The name of the file in which logs will be written.

File

quarkus.log

Indicates whether to log asynchronously

boolean

false

The queue length to use before flushing writing

int

512

Determine whether to block the publisher (rather than drop the message) when the queue is full

block, discard

block

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

MemorySize

int

1

File handler rotation file suffix. Example fileSuffix: .yyyy-MM-dd

string

Indicates whether to rotate log files on server initialization. You need to either set a max-file-size or configure a file-suffix for it to work.

boolean

true

Syslog handlers

Type

Default

If syslog logging should be enabled

boolean

false

The IP address and port of the syslog server

host:port

localhost:514

The app name used when formatting the message in RFC5424 format

string

The name of the host the messages are being sent from

string

Sets the facility used when calculating the priority of the message as defined by RFC-5424 and RFC-3164

kernel, user-level, mail-system, system-daemons, security, syslogd, line-printer, network-news, uucp, clock-daemon, security2, ftp-daemon, ntp, log-audit, log-alert, clock-daemon2, local-use-0, local-use-1, local-use-2, local-use-3, local-use-4, local-use-5, local-use-6, local-use-7

user-level

Set the SyslogType syslog type this handler should use to format the message sent

rfc5424, rfc3164

rfc5424

Sets the protocol used to connect to the syslog server

tcp, udp, ssl-tcp

tcp

Set to true if the message being sent should be prefixed with the size of the message

boolean

false

Set to true if the message should be truncated

boolean

true

Enables or disables blocking when attempting to reconnect a org.jboss.logmanager.handlers.SyslogHandler.Protocol#TCP TCP or org.jboss.logmanager.handlers.SyslogHandler.Protocol#SSL_TCP SSL TCP protocol

boolean

false

string

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

The log level specifying, which message levels will be logged by syslog logger

Level

ALL

Indicates whether to log asynchronously

boolean

false

The queue length to use before flushing writing

int

512

Determine whether to block the publisher (rather than drop the message) when the queue is full

block, discard

block

Log cleanup filters - internal use

Type

Default

The message starts to match

list of string

inherit

About the MemorySize format

A size configuration option recognises string in this format (shown as a regular expression): [0-9]+[KkMmGgTtPpEeZzYy]?. If no suffix is given, assume bytes.


1. Some extensions may define customized default log levels for certain categories, in order to reduce log noise by default. Setting the log level in configuration will override any extension-defined log levels.
2. By default the configured category gets the same handlers attached as the one on the root logger.
3. Format sequences which examine caller information may affect performance