Merge pull request #10672 from loicmathieu/logging-doc

Logging doc

bom/application/pom.xml

@@ -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>
 
@@ -1991,6 +1992,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>

core/runtime/src/main/java/io/quarkus/runtime/logging/LogConfig.java

@@ -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}
+     * * {@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;
 
     /**

docs/src/main/asciidoc/logging.adoc

@@ -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]
 ----
@@ -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:
 
@@ -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
@@ -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.
@@ -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]
@@ -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].
@@ -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:
@@ -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