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

include::{generated-dir}/config/quarkus-log-logging-log-config.adoc[opts=optional, leveloffset=+1]

=== 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 <<category-named-handlers-example>>

[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.
|quarkus.log.category."<category-name>".useParentHandlers|true|Specify whether or not this logger should send its output to its parent logger.
|quarkus.log.category."<category-name>".handlers=[<handler>]|empty footnote:[By default the configured category gets the same handlers attached as the one on the root logger.]|The names of the handlers that you want to attach to a specific category.
|===

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

[id="alt-console-format"]
=== 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.

[id="json-logging"]
==== 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
[source,xml]
----
  <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
[source, properties]
----
%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:

include::{generated-dir}/config/quarkus-logging-json.adoc[opts=optional, leveloffset=+1]

WARNING: Enabling pretty printing might cause certain processors and JSON parsers to fail.

NOTE: 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
[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
----

[#category-named-handlers-example]
.Named handlers attached to a category
[source, properties]
----
# 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:

* 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]

== Centralized log management

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