Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Logging doc #10672

Merged
merged 3 commits into from
Jul 23, 2020
Merged

Logging doc #10672

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2772165
Using Log4j2
loicmathieu Jul 8, 2020
1671b8a
Improve logging guide
loicmathieu Jul 21, 2020
9d8117c
Add log4j-jboss-logmanager to the bom
loicmathieu Jul 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 6 additions & 0 deletions bom/application/pom.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,7 @@
<gson.version>2.8.6</gson.version>
<webjars-locator-core.version>0.46</webjars-locator-core.version>
<log4j2-jboss-logmanager.version>1.0.0.Beta1</log4j2-jboss-logmanager.version>
<log4j-jboss-logmanager.version>1.2.0.Final</log4j-jboss-logmanager.version>
<avro.version>1.10.0</avro.version>
</properties>

Expand Down Expand Up @@ -1971,6 +1972,11 @@
<artifactId>log4j2-jboss-logmanager</artifactId>
<version>${log4j2-jboss-logmanager.version}</version>
</dependency>
<dependency>
<groupId>org.jboss.logmanager</groupId>
<artifactId>log4j-jboss-logmanager</artifactId>
<version>${log4j-jboss-logmanager.version}</version>
</dependency>

<dependency>
<groupId>io.quarkus.gizmo</groupId>
Expand Down
20 changes: 13 additions & 7 deletions core/runtime/src/main/java/io/quarkus/runtime/logging/LogConfig.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,23 +17,29 @@ public final class LogConfig {
/**
* 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:
* JBoss Logging supports Apache style log levels:
*
* {@link org.jboss.logmanager.Level#FATAL}
* {@link org.jboss.logmanager.Level#ERROR}
* {@link org.jboss.logmanager.Level#WARN}
* {@link org.jboss.logmanager.Level#INFO}
* {@link org.jboss.logmanager.Level#DEBUG}
* {@link org.jboss.logmanager.Level#TRACE}
* * {@link org.jboss.logmanager.Level#FATAL}
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this meant to use AsciiDoc style or JavaDoc style? If the latter, this should be a <ul>; if the former, then they shouldn't use {@link}.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

<ul> list are not well rendered on configuration reference section on the website.
I'll remove the {@link}.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

On the other hand {@link} are ignored by the asciidoc processing so it didn't appears on the website. Removing them will restrict API discovery on IDE ...

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a long standing point of contention. :-) @gsmet do you know what we settled on? Is the doc renderer using AsciiDoc, or do we need a separate JavaDoc and AsciiDoc section, or what?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is both a JavaDoc and an asciidoc, and the doc build generates the HTML for the website based on asciidoc processing.
I think that the current aproach works even if it can seems disturbing because it mixes JavaDoc directive and asciidoc one.

* * {@link org.jboss.logmanager.Level#ERROR}
* * {@link org.jboss.logmanager.Level#WARN}
* * {@link org.jboss.logmanager.Level#INFO}
* * {@link org.jboss.logmanager.Level#DEBUG}
* * {@link org.jboss.logmanager.Level#TRACE}
*
* In addition, it also supports the standard JDK log levels.
*
* @asciidoclet
*/
@ConfigItem(defaultValue = "INFO")
public Level level;

/**
* The default minimum log level
*
* @deprecated this functionality was never implemented, it may be deleted or implemented in a future release.
*/
@ConfigItem(defaultValue = "INFO")
@Deprecated
public Level minLevel;
gastaldi marked this conversation as resolved.
Show resolved Hide resolved

/**
Expand Down
157 changes: 127 additions & 30 deletions docs/src/main/asciidoc/logging.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,10 +9,95 @@ include::./attributes.adoc[]

This guide explains logging and how to configure it.

Internally, Quarkus uses JBoss Log Manager and the JBoss Logging facade. +
You can use the JBoss Logging facade inside your code as it's already provided,
or any of the supported Logging API listed in the next chapter as Quarkus will send them to JBoss Log Manager.

All the logging configuration will then be done inside your `application.properties`.

== 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` (also called JUL)
* https://github.com/jboss-logging/jboss-logging[JBoss Logging]
* https://www.slf4j.org/[SLF4J]
* https://commons.apache.org/proper/commons-logging/[Apache Commons Logging]

Internally Quarkus uses JBoss Logging; you can also use it inside your application so that no other dependencies should be added for your logs.

[source,java]
----
import org.jboss.logging.Logger;

import javax.ws.rs.GET;
import javax.ws.rs.Path;
import javax.ws.rs.Produces;
import javax.ws.rs.core.MediaType;

@Path("/hello")
public class ExampleResource {

private static final Logger LOG = Logger.getLogger(ExampleResource.class);

@GET
@Produces(MediaType.TEXT_PLAIN)
public String hello() {
LOG.info("Hello");
return "hello";
}
}
----

NOTE: If you use JBoss Logging but one of your libraries uses a different logging API, you may need to configure a link:#logging-adapters[Logging Adapter].

=== What about Apache Log4j ?

link:https://logging.apache.org/log4j/2.x/[Log4j] is a logging implementation: it contains a logging backend and a logging facade.
Quarkus uses the JBoss Log Manager backend, so you will need to include the `log4j2-jboss-logmanager` library to route Log4j logs to JBoss Log Manager.

[source,xml]
----
<dependency>
<groupId>org.jboss.logmanager</groupId>
<artifactId>log4j2-jboss-logmanager</artifactId> <1>
</dependency>
----

<1> This is the library needed for Log2J version 2; if you use the legacy Log4J version 1 you need to use `log4j-jboss-logmanager` instead.

You can then use the Log4J API inside your application.

WARNING: Do not include any Log4j dependencies. The `log4j2-jboss-logmanager` library includes what's needed to use Log4j as a logging facade.

== Logging levels

These are the log levels used by Quarkus:

[horizontal]
OFF:: Special level to turn off logging.
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.
ALL:: Special level for all messages including custom levels.

In addition, the following levels may be configured for applications and libraries using link:https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html[`java.util.logging`]:

[horizontal]
SEVERE:: Same as **ERROR**.
WARNING:: Same as **WARN**.
CONFIG:: Service configuration information.
FINE:: Same as **DEBUG**.
FINER:: Same as **TRACE**.
FINEST:: Event more debugging information than `TRACE`, maybe with even higher frequency.

== Runtime configuration

Run time logging is configured in the `application.properties` file,
for example to set everything to `INFO` logging except Hibernate:
for example, to set the default log level to `INFO` logging and include Hibernate `DEBUG` logs:

[source, properties]
----
Expand Down Expand Up @@ -54,23 +139,14 @@ The root logger category is handled separately, and is configured via the follow
|quarkus.log.level|INFO|The default minimum log level for every log category.
|===

=== Log levels
If no level configuration exists for a given logger category, the enclosing (parent) category is examined. If no categories are configured which enclose the category in question, then the root logger configuration is used.

There are several log levels you can use:
== Logging Format

[cols="<m,<5",options="header"]
|===
|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
|===
By default, Quarkus uses a pattern-based logging formatter that generates human-readable text logs.

[id="format-string"]
== Format String
You can configure the format for each log handler via a dedicated property.
For the console handler, the property is `quarkus.log.console.format`.

The logging format string supports the following symbols:

Expand Down Expand Up @@ -112,9 +188,9 @@ of the Quarkus application is captured by a service which can, for example, proc
later analysis.

[id="json-logging"]
==== JSON Logging
==== JSON Logging Format

In order to configure JSON logging, the `quarkus-logging-json` extension may be employed. Add this extension to your
In order to configure the JSON logging format, 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
Expand Down Expand Up @@ -153,17 +229,43 @@ WARNING: Enabling pretty printing might cause certain processors and JSON parser
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.

== Log Handlers

A log handler is a logging component responsible for the emission of log events to a recipient.
Quarkus comes with three different log handlers: **console**, **file** and **syslog**.

=== Console log handler

The console log handler is enabled by default. It outputs all log events to the console of your application (typically to the system's `stdout`).

For details of its configuration options, see link:#quarkus-log-logging-log-config_quarkus.log.console[the Console Logging configuration reference].

=== File log handler

The file log handler is disabled by default. It outputs all log events to a file on the application's host.
It supports log file rotation.

For details of its configuration options, see link:#quarkus-log-logging-log-config_quarkus.log.file[the File Logging configuration reference].

=== Syslog log handler

link:https://en.wikipedia.org/wiki/Syslog[Syslog] is a protocol for sending log messages on Unix-like systems using a protocol defined by link:https://tools.ietf.org/html/rfc5424[RFC 5424].

The syslog handler sends all log events to a syslog server (by default, the syslog server that is local to the application).
It is disabled by default.

For details of its configuration options, see link:#quarkus-log-logging-log-config_quarkus.log.syslog[the Syslog Logging configuration reference].

== Examples

.Console DEBUG Logging, No color, Shortened Time, Shortened Category Prefixes
.Console DEBUG Logging except for Quarkus logs (INFO), 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
quarkus.log.category."io.quarkus".level=INFO
----

NOTE: If you are adding these properties via command line make sure `"` is escaped.
Expand All @@ -183,6 +285,8 @@ quarkus.log.category."io.quarkus.smallrye.jwt".level=TRACE
quarkus.log.category."io.undertow.request.security".level=TRACE
----

NOTE: As we don't change the root logger, console log will only contain `INFO` or higher order logs.

[#category-named-handlers-example]
.Named handlers attached to a category
[source, properties]
Expand All @@ -200,15 +304,6 @@ 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].
Expand Down Expand Up @@ -265,7 +360,7 @@ This is especially important when building native executables as you could encou
Caused by java.lang.ClassNotFoundException: org.apache.commons.logging.impl.LogFactoryImpl
----

This is due to the logging implementation not being embarked in the the native executable.
This is due to the logging implementation not being included in the native executable.
Using the JBoss Logging adapters will solve this problem.

These adapters are available for most of the common Open Source logging components, such as Apache Commons Logging:
Expand Down Expand Up @@ -318,6 +413,8 @@ And Slf4j:
</dependency>
----

NOTE: This is not needed for libraries that are dependencies of a Quarkus extension as the extension will take care of this for you.

[[loggingConfigurationReference]]
== Logging configuration reference

Expand Down