Show (#242)

* standardize CI workflow names to lowercase

* removing threshold output level from LogWriter

* Rename LogWriter classes and interfaces to LogEventWriter for clarity and consistency

* documentation in log event writer classes and update version to 20.0.2

Author: q3769

pom.xml

@@ -31,7 +31,7 @@
 
     <groupId>io.github.elf4j</groupId>
     <artifactId>elf4j-engine</artifactId>
-    <version>20.0.1</version>
+    <version>20.0.2</version>
     <packaging>jar</packaging>
     <name>elf4j-engine</name>
     <description>A stand-alone Java log engine implementing the ELF4J (Easy Logging Facade for Java) API</description>

src/main/java/elf4j/engine/logging/LogHandler.java

@@ -32,7 +32,7 @@
 public interface LogHandler {
   /**
    * @return true if the logger instance's severity level is at or above the configured minimum
-   *     threshold for the specified logger and writer, false otherwise
+   *     threshold for the specified logger, false otherwise
    */
   boolean isEnabled(NativeLogger.LoggerId loggerId);
 

src/main/java/elf4j/engine/logging/writer/CompositeLogEventWriter.java

@@ -44,11 +44,12 @@
 import org.slf4j.MDC;
 
 /**
- * In general, log events are asynchronously written/rendered in parallel by multiple concurrent
- * threads. However, events issued by the same caller application thread are rendered sequentially
- * with the {@link ConseqExecutor} API. Thus, logs by different caller threads may arrive at the
- * final destination (e.g. system Console or a log file) in any order; meanwhile, logs from the same
- * caller thread will arrive sequentially in the same order as they are called by such thread.
+ * @implNote Log events are usually asynchronously written/rendered in parallel by multiple
+ *     concurrent threads. However, events issued by the same caller application thread are rendered
+ *     sequentially with the {@link ConseqExecutor} API. Thus, logs by different caller threads may
+ *     arrive at the final destination (e.g. system Console or a log file) in any order; meanwhile,
+ *     logs from the same caller thread will arrive sequentially in the same order as they are
+ *     called by such thread.
  */
 @EqualsAndHashCode(onlyExplicitlyIncluded = true)
 @ToString

src/main/java/elf4j/engine/logging/writer/LogEventWriter.java

@@ -34,12 +34,18 @@
  * messages to an output destination e.g. the STDOUT stream, a log file, or a remote vendor log
  * collector (Datadog, Newrelic, ...). Implementations of this interface should be thread-safe.
  *
+ * @apiNote A writer instance determines if the logging requires performance sensitive operations
+ *     (caller class/method/...). However, it does not concern itself with the logging threshold
+ *     levels.
+ * @implSpec A {@link LogEventWriter} instance normally includes various log patterns. Collectively,
+ *     the patterns determine if the writer instance requires performance sensitive operations such
+ *     as the inclusion of caller detail.
  * @see PerformanceSensitive
  */
 @ThreadSafe
 public interface LogEventWriter extends PerformanceSensitive {
   /**
-   * Writes the given log event to the output destination(s) configured for this log writer.
+   * Writes the given log event to the output destination(s) configured for this writer.
    *
    * @param logEvent the log data entry to write out
    */

src/main/java/elf4j/engine/logging/writer/LogEventWriterFactory.java

@@ -4,11 +4,8 @@
 
 public interface LogEventWriterFactory {
   /**
-   * Returns a list of log writers of the enclosing writer type based on the provided logging
-   * configuration.
-   *
    * @param configurationProperties the entire log service configuration
-   * @return all log writers of the enclosing writer type from the given configuration
+   * @return a log event writer instance based on the provided configuration
    */
   LogEventWriter getWriter(Properties configurationProperties);
 }

src/main/java/elf4j/engine/logging/writer/StandardStreamLogEventWriter.java

@@ -27,7 +27,6 @@
 
 import static elf4j.engine.logging.writer.StandardStreamLogEventWriter.OutStreamType.STDOUT;
 
-import elf4j.Level;
 import elf4j.Logger;
 import elf4j.engine.logging.LogEvent;
 import elf4j.engine.logging.pattern.RenderingPattern;
@@ -39,20 +38,16 @@
 import lombok.Value;
 
 /**
- * A log writer implementation that writes log events to the standard output or standard error
- * stream. The log pattern, threshold output level, and target stream (stdout or stderr) can be
- * configured.
+ * A log event writer targeting the standard stream output destination. The log pattern and target
+ * stream type (stdout or stderr) can be configured.
+ *
+ * @apiNote Due to the implementation approach on output synchrony and atomicity, this writer - and
+ *     the elf4j-engine in general - is not intended to be used simultaneously with other logging
+ *     providers. Otherwise, logs from different providers may intertwine.
  */
 @Value
 @ToString
 public class StandardStreamLogEventWriter implements LogEventWriter {
-  /**
-   * For simplicity, the standard stream writer threshold level is always set to TRACE and not
-   * configurable, regardless of whether the output stream is stdout or stderr. i.e. it is entirely
-   * up to the logger name threshold level whether a specific log is printed or not.
-   */
-  static final Level DEFAULT_WRITER_THRESHOLD_LEVEL = Level.TRACE;
-
   static final String DEFAULT_PATTERN = "{timestamp} {level} {logger} - {message}";
   static final OutStreamType DEFAULT_OUT_STREAM_TYPE = STDOUT;
   static final String LINE_FEED = System.lineSeparator();
@@ -115,10 +110,10 @@ private static final class StandardOutputStream {
 
     /**
      * Locking is in the default "unfair" mode for performance. This means under contention, logs
-     * from different threads may appear in the final destination in any order. However, 1) the
-     * (unchanged) timestamps on the logs still reflect the chronicle order, and can/should be used
-     * to sort the logs when viewing them; and 2) the logs from the same thread are still ensured to
-     * appear in the same order as the thread requested.
+     * from different caller threads may appear in the final destination in any order. However, 1)
+     * the (unchanged) timestamps on the logs still reflect the chronicle order, and can/should be
+     * used to sort the logs when viewing them; and 2) the logs from the same caller thread are
+     * still ensured to appear in the same order as the thread requested.
      */
     private static final Lock OUTPUT_LOCK = new java.util.concurrent.locks.ReentrantLock(false);
 
@@ -136,9 +131,8 @@ public StandardOutputStream(OutStreamType outStreamType) {
     }
 
     /**
-     * This method is supposed to be called once and only once per each entirely complete log
-     * message.
-     *
+     * @apiNote This method is supposed to be called once and only once per each entirely complete
+     *     log message.
      * @param bytes of the completely rendered log message to write to the target output stream
      */
     public void write(byte[] bytes) {

src/test/java/elf4j/engine/SampleUsageTest.java

@@ -27,7 +27,6 @@
 
 import static org.junit.jupiter.api.Assertions.assertTrue;
 
-import elf4j.Level;
 import elf4j.Logger;
 import java.util.function.Supplier;
 import org.junit.jupiter.api.Nested;
@@ -74,10 +73,7 @@ void convenienceShorthands() {
           debugLogger.isDebugEnabled(),
           "Assuming minimum threshold level configured is TRACE, thus DEBUG severity log level should be enabled");
       if (debugLogger.isDebugEnabled()) {
-        debugLogger.debug(
-            "The DEBUG severity level log message '{}' will print here as the default minimum writer threshold level is {}",
-            message,
-            Level.TRACE);
+        debugLogger.debug("The DEBUG severity level log message '{}' will print here", message);
       }
     }
   }