Improve logging guide

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,93 @@ 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 2 ?
+
+link:https://logging.apache.org/log4j/2.x/[Log4j 2] 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 2 logs to JBoss Log Manager.
+
+[source,xml]
+----
+    <dependency>
+      <groupId>org.jboss.logmanager</groupId>
+      <artifactId>log4j2-jboss-logmanager</artifactId>
+    </dependency>
+----
+
+You can then use the Log4J 2 API inside your application.
+
+WARNING: do not include any Log4j 2 dependencies, the `log4j2-jboss-logmanager` library includes what's needed to use Log4j 2 as a logging facade.
+
+NOTE: if you still use the legacy Log4j version 1, you need to use `log4j-jboss-logmanager` instead.
+
+== Logging levels
+
+JBoss Logging supports Apache style logs levels:
+
+- **FATAL**: A critical service failure/complete inability to service requests of any kind. *It has a higher order than **SEVERE**.*
+- **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.
+
+JBoss logging also supports the link:https://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html[standard JDK log levels]:
+
+- **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.
+
+There is also two special JDK log levels **ALL**, for all messages including custom levels, and **OFF**, to turn off logging.
+
 == 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,25 +137,16 @@ 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
+The root logger configuration is used when no configuration exists for a given logger category.
 
-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 **String** logging format that format a log event in a simple text.
 
-[id="format-string"]
-== Format String
+You can configure this logging format for each log handler via a dedicated property,
+for the console handler it will be the `quarkus.log.console.format` property.
 
-The logging format string supports the following symbols:
+The **String** logging format supports the following symbols:
 
 [cols="<m,<3,<5",options="header"]
 |===
@@ -112,9 +186,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 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 +227,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 to emits log events to a recipient. +
+Quarkus comes with three different log handlers: **console**, **file** and **syslog**.
+
+=== Console log handler
+
+It is enabled by default, it outputs all log events inside the console of your application (stdout).
+
+For details of its configuration options, see link:#quarkus-log-logging-log-config_quarkus.log.console[Console logging configuration reference].
+
+=== File log handler
+
+It is disabled by default, it allows to output all log events inside 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[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 defined by the link:https://tools.ietf.org/html/rfc5424[RFC5424].
+
+The syslog handler allows to send all logs events to a syslog server (by default, on the local syslog server). +
+It is disabled by default.
+
+For details of its configuration options, see link:#quarkus-log-logging-log-config_quarkus.log.syslog[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 +283,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 contains `INFO` or higher order logs.
+
 [#category-named-handlers-example]
 .Named handlers attached to a category
 [source, properties]
@@ -200,28 +302,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]
-
-If you want to use log4j2, you need to use the `log4j2-jboss-logmanager` to route log4j2 logs to `jboss-logmanager`. +
-You will then be able to use the log4j2 API inside your code and configure your logger via your `application.properties`.
-
-[code,xml]
-----
-    <dependency>
-      <groupId>org.jboss.logmanager</groupId>
-      <artifactId>log4j2-jboss-logmanager</artifactId>
-    </dependency>
-----
-
-WARNING: do not include any log4j2 dependencies, the `log4j2-jboss-logmanager` library include what's needed to use log4j2.
-
 == 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].
@@ -278,7 +358,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 embarked 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:
@@ -331,6 +411,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