Documentation update.

mjfryc · mjfryc · commit 3ce466a2ac9b · 2025-03-18T20:32:01.000+01:00
* Documentation update.
* v1.0.0
diff --git a/README.md b/README.md
@@ -14,10 +14,8 @@
 ![Coverage](.github/badges/jacoco.svg)
 ![Branches](.github/badges/branches.svg)
 
-[![Milestone](https://img.shields.io/github/milestones/progress-percent/mjfryc/mjaron-tinyloki-java/1?label=Next%20release:%20milestone-v0.4.0)](https://github.com/mjfryc/mjaron-tinyloki-java/milestone/1)
-
-
-Tiny [Grafana Loki](https://grafana.com/oss/loki/) client (log sender) written in pure Java 1.8 without any external dependencies.
+Tiny [Grafana Loki](https://grafana.com/oss/loki/) client (log sender) written in pure Java 1.8 without any external
+dependencies.
 
 * Implements JSON variant of [Loki API](https://grafana.com/docs/loki/latest/api/#post-lokiapiv1push)
 * Works with **Android** and **Java SE**
@@ -28,26 +26,16 @@ Tiny [Grafana Loki](https://grafana.com/oss/loki/) client (log sender) written i
 HTTP sender requires http URL, optionally basic authentication credentials may be set.
 
 Short example:
+
 ```java
 import pl.mjaron.tinyloki.*;
 
 public class Sample {
     public static void main(String[] args) {
-
-        LogController tinyLoki = TinyLoki
-                .withUrl("http://localhost/loki/api/v1/push")
-                .withBasicAuth("user", "pass")
-                .start();
-
-        ILogStream stream = tinyLoki.stream() // Before v0.3.2 use createStream()
-                .info()
-                .l("host", "MyComputerName")
-                .l("customLabel", "custom_value")
-                .build();
-
-        stream.log("Hello world.");
-
-        tinyLoki.softStop().hardStop();
+        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withBasicAuth("user", "pass").start();
+        ILogStream helloStream = loki.stream().info().l("topic", "hello").build();
+        helloStream.log("Hello world!");
+        loki.closeSync();
     }
 }
 ```
@@ -60,34 +48,51 @@ import pl.mjaron.tinyloki.*;
 public class Sample {
     public static void main(String[] args) {
 
-        // Initialize log controller instance with URL.
-        // Usually creating more than one LogController instance doesn't make sense.
-        // LogController owns separate thread which sends logs periodically.
-        LogController tinyLoki = TinyLoki
-                .withUrl("http://localhost/loki/api/v1/push")
-                .withBasicAuth("user", "pass")
-                .start();
-
-        // Create streams. It is thread-safe.
-        ILogStream stream = tinyLoki.createStream(
-                // Define stream labels...
-                // Initializing log level to verbose and adding some custom labels.
-                TinyLoki.verbose()
-                        .l("host", "MyComputerName")        // Custom static label.
-                        .l("customLabel", "custom_value")   // Custom static label.
-                // Label names should start with letter
-                //     and contain letters, digits and '_' only.
-                // Bad characters will be replaced by '_'.
-                //     If first character is bad, it will be replaced by 'A'.
-        );
-
-        // ... new streams and other logs here (thread-safe, non-blocking).
-        stream.log("Hello world.");
-
-        // Optionally flush logs before application exit.
-        tinyLoki
-                .softStop()     // Try to send logs last time. Blocking method.
-                .hardStop();    // If it doesn't work (soft timeout) - force stop sending thread.
+        // Initialize the log controller instance with URL.
+        // The endpoint loki/api/v1/push will be added by default if missing.
+        // Usually creating more than one TinyLoki instance doesn't make sense.
+        // TinyLoki (its default IExecutor implementation) owns separate thread which sends logs periodically.
+        // It may be called inside try-with-resources block, but the default close() method doesn't synchronize the logs,
+        // but just interrupts the background worker thread.
+        try (TinyLoki loki = TinyLoki.withUrl("http://localhost:3100/loki/api/v1/push")
+                // Print all diagnostic information coming from the TinyLoki library. For diagnostic purposes only.
+                .withVerboseLogMonitor()
+
+                // Set the custom log processing interval time.
+                // So the executor will try to send the next logs 10 seconds after the previous logs sending operation.
+                .withThreadExecutor(10 * 1000)
+
+                // Set custom time of HTTP connection establishing timeout.
+                .withConnectTimeout(10 * 1000)
+
+                // Encode the logs to limit the size of data sent.
+                .withGzipLogEncoder()
+
+                // The BasicBuffering is set by default, but here the (not encoded) message size limit may be customized.
+                .withBasicBuffering(3 * 1024 * 1024, 10)
+
+                // Initialize the library with above settings.
+                // The ThreadExecutor will create a new thread and start waiting for the logs to be sent.
+                .start()) {
+
+            // Some logs here...
+            ILogStream whiteStream = loki.stream().l("color", "white").build();
+            whiteStream.log("Hello white world.");
+
+            // Blocking method, tries to send the logs ASAP and wait for sending completion.
+            // This method returns false when timeout occurs, but true when sending has completed with success or failure.
+            boolean allHttpSendingOperationsFinished = loki.sync();
+            System.out.println("Are all logs processed: " + allHttpSendingOperationsFinished);
+
+            ILogStream redStream = loki.stream().l("color", "red").build();
+            redStream.log("Hello white world.");
+
+            // Blocking method, tries to synchronize the logs than interrupt and join the execution thread.
+            // Set the custom timeout time for this operation.
+            boolean closedWithSuccess = loki.closeSync(5 * 1000);
+
+            System.out.println("Synced and closed with success: " + closedWithSuccess);
+        }
     }
 }
 ```
@@ -97,11 +102,11 @@ public class Sample {
 ### Maven Central
 
 ```gradle
-    implementation 'io.github.mjfryc:mjaron-tinyloki-java:0.3.11'
+    implementation 'io.github.mjfryc:mjaron-tinyloki-java:1.0.0'
 ```
 
- _[Maven Central page](https://search.maven.org/artifact/io.github.mjfryc/mjaron-tinyloki-java/),_
- _[Maven Central repository URL](https://repo1.maven.org/maven2/io/github/mjfryc/mjaron-tinyloki-java/)_
+_[Maven Central page](https://search.maven.org/artifact/io.github.mjfryc/mjaron-tinyloki-java/),_
+_[Maven Central repository URL](https://repo1.maven.org/maven2/io/github/mjfryc/mjaron-tinyloki-java/)_
 
 ### GitHub Packages
 
@@ -114,10 +119,10 @@ Click the [Packages section](https://github.com/mjfryc?tab=packages&repo_name=mj
 3. Add this jar to project dependencies in build.gradle, e.g:
 
 ```gradle
-    implementation files(project.rootDir.absolutePath + '/libs/mjaron-tinyloki-java-0.3.11.jar')
+    implementation files(project.rootDir.absolutePath + '/libs/mjaron-tinyloki-java-1.0.0.jar')
 ```
 
-## API design
+## API design (outdated)
 
 ```mermaid
 classDiagram
diff --git a/build.gradle b/build.gradle
@@ -6,7 +6,7 @@ plugins {
 }
 
 group 'io.github.mjfryc'
-version '0.3.11'
+version '1.0.0'
 
 repositories {
     mavenCentral()
diff --git a/src/main/java/pl/mjaron/tinyloki/Settings.java b/src/main/java/pl/mjaron/tinyloki/Settings.java
@@ -293,6 +293,35 @@ public Settings withExecutor(final IExecutor executor) {
         return this;
     }
 
+    /**
+     * Sets the new instance of {@link ThreadExecutor} with custom interval time between sending logs.
+     * <p>
+     * The default log processing interval time is defined by {@link ThreadExecutor#DEFAULT_PROCESSING_INTERVAL_TIME_MS}.
+     *
+     * @param processingIntervalTime Interval time between sending logs in milliseconds.
+     * @return This {@link Settings} object reference.
+     * @see ThreadExecutor#DEFAULT_PROCESSING_INTERVAL_TIME_MS
+     * @since 1.0.0
+     */
+    public Settings withThreadExecutor(final int processingIntervalTime) {
+        return withExecutor(new ThreadExecutor(processingIntervalTime));
+    }
+
+    /**
+     * Sets the new instance of {@link ThreadExecutor} with default interval time between sending logs.
+     * <p>
+     * The default log processing interval time is defined by {@link ThreadExecutor#DEFAULT_PROCESSING_INTERVAL_TIME_MS}.
+     * <p>
+     * The {@link ThreadExecutor} is the default executor if no other executor is set.
+     *
+     * @return This {@link Settings} object reference.
+     * @see ThreadExecutor#DEFAULT_PROCESSING_INTERVAL_TIME_MS
+     * @since 1.0.0
+     */
+    public Settings withThreadExecutor() {
+        return withExecutor(new ThreadExecutor());
+    }
+
     /**
      * Allows setting the {@link IBuffering} implementation.
      *
@@ -308,10 +337,15 @@ public Settings withBuffering(final IBuffering buffering) {
     /**
      * Allows to set and configure the {@link BasicBuffering}.
      *
-     * @param maxMessageSize  The max single message size.
+     * @param maxMessageSize  The max single (not encoded) message size.
      *                        This size should be lower than the Grafana Loki server max message size.
+     *                        <p>
      *                        The default value in this library: {@link IBuffering#DEFAULT_MAX_MESSAGE_SIZE}.
+     *                        <p>
+     *                        Note that if this size is exceeded, the server may respond with HTTP error <code>500</code>, e.g:
+     *                        <pre>{@code rpc error: code = ResourceExhausted desc = grpc: received message larger than max (6331143 vs. 4194304)}</pre>
      * @param maxBuffersCount The max buffers count. The value should be tuned to target system capabilities.
+     *                        <p>
      *                        The default value in this library: {@link IBuffering#DEFAULT_MAX_BUFFERS_COUNT}.
      * @return This {@link Settings} object reference.
      * @since 1.0.0
diff --git a/src/main/java/pl/mjaron/tinyloki/ThreadExecutor.java b/src/main/java/pl/mjaron/tinyloki/ThreadExecutor.java
@@ -2,24 +2,24 @@
 
 public class ThreadExecutor implements IExecutor, Runnable {
 
-    public static final int DEFAULT_LOG_COLLECTION_PERIOD_MS = 5000;
+    public static final int DEFAULT_PROCESSING_INTERVAL_TIME_MS = 5000;
 
     private final BlockingLogListener logListener = new BlockingLogListener();
     private ILogMonitor logMonitor = null;
     private ILogCollector logCollector = null;
     private ILogProcessor logProcessor = null;
     private Thread workerThread = null;
-    private int logCollectionPeriod = DEFAULT_LOG_COLLECTION_PERIOD_MS;
+    private int processingIntervalTime = DEFAULT_PROCESSING_INTERVAL_TIME_MS;
 
     public ThreadExecutor() {
     }
 
-    public ThreadExecutor(final int logCollectionPeriod) {
-        this.logCollectionPeriod = logCollectionPeriod;
+    public ThreadExecutor(final int processingIntervalTime) {
+        this.processingIntervalTime = processingIntervalTime;
     }
 
-    public int getLogCollectionPeriod() {
-        return logCollectionPeriod;
+    public int getProcessingIntervalTime() {
+        return processingIntervalTime;
     }
 
     @Override
@@ -110,7 +110,7 @@ public void run() {
 
         while (true) {
             try {
-                final int anyLogs = logListener.waitForLogs(logCollectionPeriod);
+                final int anyLogs = logListener.waitForLogs(processingIntervalTime);
                 if (anyLogs > 0) {
                     logProcessor.processLogs();
                 }
diff --git a/src/main/java/pl/mjaron/tinyloki/TinyLoki.java b/src/main/java/pl/mjaron/tinyloki/TinyLoki.java
@@ -365,13 +365,14 @@ public boolean sync(final int timeout) throws InterruptedException {
     }
 
     /**
-     * Blocking function. BLocks the calling thread until all requested logs are processed (attempted to send) or default timeout occurs, defined as {@link #DEFAULT_SYNC_TIMEOUT}.
+     * Blocking function. Blocks the calling thread until all requested logs are processed (attempted to send)
+     * or default timeout occurs, defined as {@link #DEFAULT_SYNC_TIMEOUT}.
      * <p>
      * <b>Thread safety</b>
      * <p>
      * It may be called from any thread.
      *
-     * @return <code>true</code> If sync operation finished with success.
+     * @return <code>true</code> If sync operation finished, even if the HTTP operation has failed due to IO errors.
      * <p>
      * <code>false</code> If sync operation failed due to timeout.
      * @throws InterruptedException When calling thread is interrupted.
diff --git a/src/test/java/pl/mjaron/tinyloki/IntegrationTest.java b/src/test/java/pl/mjaron/tinyloki/IntegrationTest.java
@@ -24,31 +24,60 @@ public static boolean isIntegrationEnabled() {
 
     @Test
     void shortExample() throws InterruptedException {
-        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100")
-                .withBasicAuth("user", "pass")
-                .start();
+        TinyLoki loki = TinyLoki.withUrl("http://localhost:3100").withBasicAuth("user", "pass").start();
+        ILogStream helloStream = loki.stream().info().l("topic", "hello").build();
+        helloStream.log("Hello world!");
+        loki.closeSync();
+    }
 
-        ILogStream windowStream = loki.stream().info().l("device", "window").build();
-        ILogStream doorStream = loki.stream().info().l("device", "door").build();
+    @Test
+    void verboseTest() throws InterruptedException {
 
-        windowStream.log("The window is open.");
-        doorStream.log("The door is open.");
+        // Initialize the log controller instance with URL.
+        // The endpoint loki/api/v1/push will be added by default if missing.
+        // Usually creating more than one TinyLoki instance doesn't make sense.
+        // TinyLoki (its default IExecutor implementation) owns separate thread which sends logs periodically.
+        // It may be called inside try-with-resources block, but the default close() method doesn't synchronize the logs,
+        // but just interrupts the background worker thread.
+        try (TinyLoki loki = TinyLoki.withUrl("http://localhost:3100/loki/api/v1/push")
 
-        // Time for syncing and closing the logs.
-        boolean closedWithSuccess = loki.closeSync(1000);
+                // Print all diagnostic information coming from the TinyLoki library. For diagnostic purposes only.
+                .withVerboseLogMonitor()
 
-        System.out.println("Closed with success: " + closedWithSuccess);
+                // Set the custom log processing interval time.
+                // So the executor will try to send the next logs 10 seconds after the previous logs sending operation.
+                .withThreadExecutor(10 * 1000)
 
-        assertTrue(closedWithSuccess);
-    }
+                // Set custom time of HTTP connection establishing timeout.
+                .withConnectTimeout(10 * 1000)
 
-    @Test
-    void sampleTest() throws InterruptedException {
-        try (TinyLoki loki = TinyLoki.withUrl("http://localhost:3100/loki/api/v1/push").withVerboseLogMonitor().start()) {
-            ILogStream stream = loki.stream().l("color", "white").build();
-            stream.log("Hello world.");
-            loki.sync();
-            loki.stop();
+                // Encode the logs to limit the size of data sent.
+                .withGzipLogEncoder()
+
+                // The BasicBuffering is set by default, but here the (not encoded) message size limit may be customized.
+                .withBasicBuffering(3 * 1024 * 1024, 10)
+
+                // Initialize the library with above settings.
+                // The ThreadExecutor will create a new thread and start waiting for the logs to be sent.
+                .start()) {
+
+            // Some logs here...
+            ILogStream whiteStream = loki.stream().l("color", "white").build();
+            whiteStream.log("Hello white world.");
+
+            // Blocking method, tries to send the logs ASAP and wait for sending completion.
+            // This method returns false when timeout occurs, but true when sending has completed with success or failure.
+            boolean allHttpSendingOperationsFinished = loki.sync();
+            System.out.println("Are all logs processed: " + allHttpSendingOperationsFinished);
+
+            ILogStream redStream = loki.stream().l("color", "red").build();
+            redStream.log("Hello white world.");
+
+            // Blocking method, tries to synchronize the logs than interrupt and join the execution thread.
+            // Set the custom timeout time for this operation.
+            boolean closedWithSuccess = loki.closeSync(5 * 1000);
+
+            System.out.println("Synced and closed with success: " + closedWithSuccess);
         }
     }
 
diff --git a/src/test/java/pl/mjaron/tinyloki/ThreadExecutorTest.java b/src/test/java/pl/mjaron/tinyloki/ThreadExecutorTest.java
@@ -17,7 +17,7 @@ class ThreadExecutorTest {
     @Test
     void basic() throws InterruptedException {
         ThreadExecutor executor = new ThreadExecutor(1000);
-        assertEquals(1000, executor.getLogCollectionPeriod());
+        assertEquals(1000, executor.getProcessingIntervalTime());
         assertThrows(RuntimeException.class, () -> {
             executor.configure(null, new DummyLogProcessor(), new VerboseLogMonitor());
         });

Original file line number	Diff line number	Diff line change
`@@ -6,7 +6,7 @@ plugins {`
`6`	`6`	`}`
`7`	`7`
`8`	`8`	`group 'io.github.mjfryc'`
`9`		`-version '0.3.11'`
	`9`	`+version '1.0.0'`
`10`	`10`
`11`	`11`	`repositories {`
`12`	`12`	`mavenCentral()`