Merge pull request #34952 from Ladicek/logging-configuration-review

Logging configuration stylistic review

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

@@ -8,12 +8,12 @@ public class CategoryBuildTimeConfig {
     /**
      * The minimum log level for this category.
      * By default, all categories are configured with <code>DEBUG</code> minimum level.
-     *
-     * To get runtime logging below <code>DEBUG</code>, e.g. <code>TRACE</code>,
-     * the minimum level has to be adjusted at build time, the right log level needs to be provided at runtime.
-     *
+     * <p>
+     * To get runtime logging below <code>DEBUG</code>, e.g., <code>TRACE</code>,
+     * adjust the minimum level at build time. The right log level needs to be provided at runtime.
+     * <p>
      * As an example, to get <code>TRACE</code> logging,
-     * minimum level needs to be at <code>TRACE</code> and the runtime log level needs to match that.
+     * minimum level needs to be at <code>TRACE</code>, and the runtime log level needs to match that.
      */
     @ConfigItem(defaultValue = "inherit")
     public InheritableLevel minLevel;

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

@@ -11,9 +11,9 @@ public class CategoryConfig {
 
     /**
      * The log level for this category.
-     *
+     * <p>
      * Note that to get log levels below <code>INFO</code>,
-     * the minimum level build time configuration option needs to be adjusted as well.
+     * the minimum level build-time configuration option also needs to be adjusted.
      */
     @ConfigItem(defaultValue = "inherit")
     InheritableLevel level;

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

@@ -9,13 +9,13 @@
 @ConfigGroup
 public class CleanupFilterConfig {
     /**
-     * The message starts to match
+     * The message prefix to match
      */
     @ConfigItem(defaultValue = "inherit")
     public List<String> ifStartsWith;
 
     /**
-     * The new log level for the filtered message, defaults to DEBUG
+     * The new log level for the filtered message. Defaults to DEBUG.
      */
     @ConfigItem(defaultValue = "DEBUG")
     public Level targetLevel;

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

@@ -22,8 +22,8 @@ public class ConsoleConfig {
     boolean stderr;
 
     /**
-     * The log format. Note that this value will be ignored if an extension is present that takes
-     * control of console formatting (e.g. an XML or JSON-format extension).
+     * The log format. Note that this value is ignored if an extension is present that takes
+     * control of console formatting (e.g., an XML or JSON-format extension).
      */
     @ConfigItem(defaultValue = "%d{yyyy-MM-dd HH:mm:ss,SSS} %-5p [%c{3.}] (%t) %s%e%n")
     String format;
@@ -35,22 +35,22 @@ public class ConsoleConfig {
     Level level;
 
     /**
-     * If the console logging should be in color. If undefined quarkus takes
-     * best guess based on operating system and environment.
-     * Note that this value will be ignored if an extension is present that takes
-     * control of console formatting (e.g. an XML or JSON-format extension).
-     *
-     * This has been deprecated, and replaced with quarkus.console.color instead,
-     * as quarkus now provides more console based functionality than just logging.
+     * If the console logging should be in color. If undefined, Quarkus takes
+     * best guess based on the operating system and environment.
+     * Note that this value is ignored if an extension is present that takes
+     * control of console formatting (e.g., an XML or JSON-format extension).
+     * <p>
+     * This has been deprecated and replaced with <code>quarkus.console.color</code>,
+     * as Quarkus now provides more console-based functionality than just logging.
      */
     @ConfigItem
     @Deprecated
     public Optional<Boolean> color;
 
     /**
      * Specify how much the colors should be darkened.
-     * Note that this value will be ignored if an extension is present that takes
-     * control of console formatting (e.g. an XML or JSON-format extension).
+     * Note that this value is ignored if an extension is present that takes
+     * control of console formatting (e.g., an XML or JSON-format extension).
      */
     @ConfigItem(defaultValue = "0")
     int darken;

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

@@ -62,14 +62,14 @@ public class FileConfig {
      * File rotation config.
      * The time interval is determined by the content of the <code>fileSuffix</code> property.
      * The size interval is determined by the content of the <code>maxFileSize</code> property.
-     * If both are used, the rotating will be based on time then size.
+     * If both are used, the rotating will be based on time, then on size.
      */
     RotationConfig rotation;
 
     @ConfigGroup
     public static class RotationConfig {
         /**
-         * The maximum file size of the log file after which a rotation is executed.
+         * The maximum log file size, after which a rotation is executed.
          */
         @ConfigItem(defaultValue = "10M")
         MemorySize maxFileSize;
@@ -81,7 +81,7 @@ public static class RotationConfig {
         int maxBackupIndex;
 
         /**
-         * File handler rotation file suffix.
+         * The file handler rotation file suffix.
          * When used, the file will be rotated based on its suffix.
          *
          * Example fileSuffix: .yyyy-MM-dd

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

@@ -12,7 +12,7 @@
 public class LogBuildTimeConfig {
 
     /**
-     * Whether logging metrics are published in case a metrics extension is present.
+     * If enabled and a metrics extension is present, logging metrics are published.
      */
     @ConfigItem(name = "metrics.enabled", defaultValue = "false")
     public boolean metricsEnabled;
@@ -26,8 +26,8 @@ public class LogBuildTimeConfig {
     /**
      * Minimum logging categories.
      * <p>
-     * 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,
+     * Logging is done on a per-category basis. Each category can be configured independently.
+     * A configuration that applies to a category will also apply to all sub-categories of that category,
      * unless there is a more specific matching sub-category configuration.
      */
     @ConfigItem(name = "category")

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

@@ -19,7 +19,7 @@ public final class LogConfig {
     /**
      * The log level of the root category, which is used as the default log level for all categories.
      *
-     * JBoss Logging supports Apache style log levels:
+     * JBoss Logging supports Apache-style log levels:
      *
      * * {@link org.jboss.logmanager.Level#FATAL}
      * * {@link org.jboss.logmanager.Level#ERROR}
@@ -63,7 +63,7 @@ public final class LogConfig {
      * Logging categories.
      * <p>
      * 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,
+     * A configuration that applies to a category will also apply to all sub-categories of that category,
      * unless there is a more specific matching sub-category configuration.
      */
     @ConfigItem(name = "category")
@@ -82,7 +82,7 @@ public final class LogConfig {
     /**
      * File handlers.
      * <p>
-     * The named file handlers configured here can be linked on one or more categories.
+     * The named file handlers configured here can be linked to one or more categories.
      */
     @ConfigItem(name = "handler.file")
     @ConfigDocSection
@@ -91,7 +91,7 @@ public final class LogConfig {
     /**
      * Syslog handlers.
      * <p>
-     * The named syslog handlers configured here can be linked on one or more categories.
+     * The named syslog handlers configured here can be linked to one or more categories.
      */
     @ConfigItem(name = "handler.syslog")
     @ConfigDocSection
@@ -106,7 +106,7 @@ public final class LogConfig {
 
     /**
      * The names of additional handlers to link to the root category.
-     * These handlers are defined in consoleHandlers, fileHandlers or syslogHandlers.
+     * These handlers are defined in consoleHandlers, fileHandlers, or syslogHandlers.
      */
     @ConfigItem
     Optional<List<String>> handlers;

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

@@ -22,7 +22,7 @@ public class SyslogConfig {
 
     /**
      *
-     * The IP address and port of the syslog server
+     * The IP address and port of the Syslog server
      */
     @ConfigItem(defaultValue = "localhost:514")
     InetSocketAddress endpoint;
@@ -52,19 +52,19 @@ public class SyslogConfig {
     SyslogType syslogType;
 
     /**
-     * Sets the protocol used to connect to the syslog server
+     * Sets the protocol used to connect to the Syslog server
      */
     @ConfigItem(defaultValue = "tcp")
     Protocol protocol;
 
     /**
-     * Set to {@code true} if the message being sent should be prefixed with the size of the message
+     * If enabled, the message being sent is prefixed with the size of the message
      */
     @ConfigItem
     boolean useCountingFraming;
 
     /**
-     * Set to {@code true} if the message should be truncated
+     * Set to {@code true} to truncate the message if it exceeds maximum length
      */
     @ConfigItem(defaultValue = "true")
     boolean truncate;
@@ -84,7 +84,7 @@ public class SyslogConfig {
     String format;
 
     /**
-     * The log level specifying, which message levels will be logged by syslog logger
+     * The log level specifying what message levels will be logged by the Syslog logger
      */
     @ConfigItem(defaultValue = "ALL")
     Level level;

extensions/logging-json/runtime/src/main/java/io/quarkus/logging/json/runtime/JsonLogConfig.java

@@ -48,7 +48,7 @@ public static class JsonConfig {
         @ConfigItem(name = ConfigItem.PARENT, defaultValue = "true")
         boolean enable;
         /**
-         * Enable "pretty printing" of the JSON record. Note that some JSON parsers will fail to read pretty printed output.
+         * Enable "pretty printing" of the JSON record. Note that some JSON parsers will fail to read the pretty printed output.
          */
         @ConfigItem
         boolean prettyPrint;
@@ -58,7 +58,7 @@ public static class JsonConfig {
         @ConfigItem(defaultValue = "default")
         String dateFormat;
         /**
-         * The special end-of-record delimiter to be used. By default, newline is used as delimiter.
+         * The special end-of-record delimiter to be used. By default, newline is used.
          */
         @ConfigItem
         Optional<String> recordDelimiter;
@@ -76,7 +76,7 @@ public static class JsonConfig {
          * Enable printing of more details in the log.
          * <p>
          * 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.
+         * source class name, source file name, source method name, and source line number.
          */
         @ConfigItem
         boolean printDetails;
@@ -87,13 +87,13 @@ public static class JsonConfig {
         Optional<String> keyOverrides;
 
         /**
-         * Keys to be excluded from the Json output.
+         * Keys to be excluded from the JSON output.
          */
         @ConfigItem
         Optional<Set<String>> excludedKeys;
 
         /**
-         * Additional fields to be appended in the json logs.
+         * Additional fields to be appended in the JSON logs.
          */
         @ConfigItem
         @ConfigDocMapKey("field-name")