////
This guide is maintained in the main Quarkus repository
and pull requests should be submitted there:
https://github.com/quarkusio/quarkus/tree/master/docs/src/main/asciidoc
////
= Quarkus - Configuring Logging

include::./attributes.adoc[]

This guide explains logging and how to configure it.

== Run Time Configuration

Run time configuration of logging is done through the normal `application.properties` file.

=== Console configuration

Console logging is enabled by default.  To configure or disable it, the following configuration properties are used:

[cols="<m,<m,<2",options="header"]
|===
|Property Name|Default|Description
|quarkus.log.console.enable|true|Determine whether console logging is enabled.
|quarkus.log.console.format|%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n|The format pattern to use for logging to the console; see <<format_string>>.
|quarkus.log.console.level|ALL|The minimum log level to display to the console.
|quarkus.log.console.color|true|Allow color rendering to be used on the console, if it is supported by the terminal.
|quarkus.log.console.async|false|Indicates whether to log asynchronously.
|quarkus.log.console.async.queue-length|512|The queue length to use before flushing writing.
|quarkus.log.console.async.overflow|block|Determine whether to block the publisher (rather than drop the message) when the queue is full.
|===

=== File configuration

Logging to a file is also supported but not enabled by default.  To configure or enable this behavior, use the following configuration properties:

[cols="<m,<m,<2",options="header"]
|===
|Property Name|Default|Description
|quarkus.log.file.enable|false|Determine whether file logging is enabled.
|quarkus.log.file.format|%d{yyyy-MM-dd HH:mm:ss,SSS} %h %N[%i] %-5p [%c{3.}] (%t) %s%e%n|The format pattern to use for logging to a file; see <<format_string>>.
|quarkus.log.file.level|ALL|The minimum log level to write to the log file.
|quarkus.log.file.path|quarkus.log|The path of the log file.
|quarkus.log.file.rotation.max-file-size||The maximum file size of the log file after which a rotation is executed. This configuration option would recognize strings in this format (shown as a regular expression): `[0-9]+[KkMmGgTtPpEeZzYy]?`. If no suffix is given, assume bytes.
|quarkus.log.file.rotation.max-backup-index|1|The maximum number of backups to keep.
|quarkus.log.file.rotation.file-suffix||Rotating log file suffix. The format of suffix value has to be understood by `java.text.SimpleDateFormat`.
|quarkus.log.file.rotation.rotate-on-boot|true|Indicates whether to rotate log files on server initialization.
|quarkus.log.file.async|false|Indicates whether to log asynchronously.
|quarkus.log.file.async.queue-length|512|The queue length to use before flushing writing.
|quarkus.log.file.async.overflow|block|Determine whether to block the publisher (rather than drop the message) when the queue is full.
|===

=== Syslog configuration

Logging to a syslog is also supported but not enabled by default.  To configure or enable this behavior, use the following configuration properties:

[cols="<m,<m,<2",options="header"]
|===
|Property Name|Default|Description
|quarkus.log.syslog.enable|false|Determine whether syslog logging is enabled.
|quarkus.log.syslog.format|%d{yyyy-MM-dd HH:mm:ss,SSS} %h %N[%i] %-5p [%c{3.}] (%t) %s%e%n|The format pattern to use for logging to syslog; see <<format_string>>.
|quarkus.log.syslog.level|ALL|The minimum log level to write to syslog.
|quarkus.log.syslog.endpoint|localhost:514|The IP address and port of the syslog server.
|quarkus.log.syslog.app-name|The current process name|The app name used when formatting the message in RFC5424 format.
|quarkus.log.syslog.hostname|The current hostname|The name of the host the messages are being sent from.
|quarkus.log.syslog.facility|USER_LEVEL|The facility used when calculating the priority of the message as defined by RFC-5424 and RFC-3164.
|quarkus.log.syslog.syslog-type|RFC5424|The syslog type which handler should use to format the message sent.
|quarkus.log.syslog.protocol|TCP|The protocol used to connect to the syslog server.
|quarkus.log.syslog.use-counting-framing|false|Determine whether the message being sent should be prefixed with the size of the message.
|quarkus.log.syslog.truncate|true|Indicates whether the message should be truncated.
|quarkus.log.syslog.block-on-reconnect|true|Determine whether to block when attempting to reconnect on TCP or SSL TCP protocols
|quarkus.log.syslog.async|false|Indicates whether to log asynchronously.
|quarkus.log.syslog.async.queue-length|512|The queue length to use before flushing writing.
|quarkus.log.syslog.async.overflow|block|Determine whether to block the publisher (rather than drop the message) when the queue is full.
|===

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

[cols="<m,<m,<2",options="header"]
|===
|Property Name|Default|Description
|quarkus.log.category."<category-name>".level|INFO footnote:[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.]|The level to use to configure the category named `<category-name>`.  The quotes are necessary.
|===

NOTE: The quotes shown in the property name are required as categories normally contain '.' which must
be escaped. An example is shown in <<category-example>>.

=== Root logger configuration

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

[cols="<m,<m,<2",options="header"]
|===
|Property Name|Default|Description
|quarkus.log.level|INFO|The default minimum log level for every log category.
|===

[id="format_string"]
== Format String

The logging format string supports the following symbols:

[cols="<m,<3,<5",options="header"]
|===
|Symbol|Summary|Description

|%%|`%`|Renders a simple `%` character.
|%c|Category|Renders the category name.
|%C|Source class|Renders the source class name.footnote:calc[Format sequences which examine caller information may affect performance]
|%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.footnote:calc[]
|%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.footnote:calc[]
|%L|Source line|Renders the source line number.footnote:calc[]
|%m|Full Message|Renders the log message plus exception (if any).
|%M|Source method|Renders the source method name.footnote:calc[]
|%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}
|===


== Examples

.Console DEBUG Logging, No color, Shortened Time, Shortened Category Prefixes
[source, properties]
----
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
----

NOTE: If you are adding these properties via command line make sure `"` is escaped.
For example `-Dquarkus.log.category.\"io.quarkus\".level=DEBUG`.

[#category-example]
.File TRACE Logging Configuration
[source, properties]
----
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
----

== Supported Logging APIs

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

* JDK `java.util.logging`
* https://github.com/jboss-logging/jboss-logging[JBoss Logging]
* https://www.slf4j.org/[SLF4J]
* https://commons.apache.org/proper/commons-logging/[Apache Commons Logging]

