From af742eaa6a3c7587e5720e0129c09129cbdb04c7 Mon Sep 17 00:00:00 2001
From: Cindy Peng <148148319+cindy-peng@users.noreply.github.com>
Date: Tue, 11 Feb 2025 14:23:54 +0800
Subject: [PATCH 1/2] Doc: Add more explanation and examples for
 logbackBatchingSettings

---
 README.md | 30 ++++++++++++++++++++++++++++++
 1 file changed, 30 insertions(+)

diff --git a/README.md b/README.md
index c77f62c4d..68331d3a5 100644
--- a/README.md
+++ b/README.md
@@ -159,6 +159,36 @@ public class TestLogger {
 }
 ```
 
+### Controlling the batching settings
+When using asynchronous logging, the Logging API is called asynchronously.  This allows the appender 
+to combine multiple write() calls into a single, more efficient request to the Logging API. The 
+`logbackBatchingSettings` in the `logback.xml`  configures the batching behavior:
+
+```
+   <logbackBatchingSettings>
+     <elementCountThreshold>100</elementCountThreshold> <!-- Send a writeLogEntries request once the number of log entries in a batch is over 100 -->
+     <requestByteThreshold>1000</requestByteThreshold> <!-- Send a writeLogEntries request once the size of log entries in a batch are over 1000 bytes -->
+     <delayThreshold>500</delayThreshold> <!-- Send a writeLogEntries request once the 500 ms has passed since the first log entry created the batch -->
+     <maxOutstandingElementCount>10000</maxOutstandingElementCount>
+     <maxOutstandingRequestBytes>100000</maxOutstandingRequestBytes>
+     <limitExceededBehavior>Ignore</limitExceededBehavior>
+   </logbackBatchingSettings> 
+```
+Here are some explanations for [BatchingSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.batching.BatchingSettings):
+* `elementCountThreshold`: Triggers a `writeLogEntries` request when the number of batched log entries exceeds this threshold.
+* `requestByteThreshold`: Triggers a `writeLogEntries` request when the total size of batched log entries (in bytes) exceeds this threshold.
+* `delayThreshold`: Triggers a `writeLogEntries` request when the threshold in milliseconds has passed since the first log entry created the batch.
+
+Batching also supports [FlowControl](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.batching.FlowControlSettings), which can be used to 
+prevent the batching implementation from accumulating messages without limit, resulting eventually in an OutOfMemory exception. These settings in the configuration controls 
+flow control behavior:
+
+* `maxOutstandingElementCount`: When the total number of outstanding log events exceeds this threshold, flow control will be initiated.
+* `maxOutstandingRequestBytes`: When the total size of outstanding `writeLogEntries` requests exceeds this threshold, flow control will be initiated.
+* `limitExceededBehavior`: This value defines what action the appender should take when the configured limits (like `maxOutstandingRequestBytes` or `maxOutstandingElementCount`) are exceeded.
+
+For more about batching configurations, see [BatchingSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.batching.BatchingSettings).
+
 ### Populate log entries with metadata
 
 The library provides multiple ways to enrich log entries with additional information.

From 68f479a247537742a3c37778a0b36e45cb0a12d4 Mon Sep 17 00:00:00 2001
From: Cindy Peng <148148319+cindy-peng@users.noreply.github.com>
Date: Mon, 17 Feb 2025 18:52:18 +0800
Subject: [PATCH 2/2] fix comments

---
 README.md | 10 +++++-----
 1 file changed, 5 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index 68331d3a5..2409b625f 100644
--- a/README.md
+++ b/README.md
@@ -161,14 +161,14 @@ public class TestLogger {
 
 ### Controlling the batching settings
 When using asynchronous logging, the Logging API is called asynchronously.  This allows the appender 
-to combine multiple write() calls into a single, more efficient request to the Logging API. The 
-`logbackBatchingSettings` in the `logback.xml`  configures the batching behavior:
+to combine multiple `write()` calls into a single, more efficient request to the Logging API. The 
+`logbackBatchingSettings` in the `logback.xml` file configures the batching behavior:
 
 ```
    <logbackBatchingSettings>
      <elementCountThreshold>100</elementCountThreshold> <!-- Send a writeLogEntries request once the number of log entries in a batch is over 100 -->
-     <requestByteThreshold>1000</requestByteThreshold> <!-- Send a writeLogEntries request once the size of log entries in a batch are over 1000 bytes -->
-     <delayThreshold>500</delayThreshold> <!-- Send a writeLogEntries request once the 500 ms has passed since the first log entry created the batch -->
+     <requestByteThreshold>1000</requestByteThreshold> <!-- Send a writeLogEntries request once the total size of log entries in a batch is over 1000 bytes -->
+     <delayThreshold>500</delayThreshold> <!-- Send a writeLogEntries request once the 500 ms duration has passed since the first log entry created the batch -->
      <maxOutstandingElementCount>10000</maxOutstandingElementCount>
      <maxOutstandingRequestBytes>100000</maxOutstandingRequestBytes>
      <limitExceededBehavior>Ignore</limitExceededBehavior>
@@ -187,7 +187,7 @@ flow control behavior:
 * `maxOutstandingRequestBytes`: When the total size of outstanding `writeLogEntries` requests exceeds this threshold, flow control will be initiated.
 * `limitExceededBehavior`: This value defines what action the appender should take when the configured limits (like `maxOutstandingRequestBytes` or `maxOutstandingElementCount`) are exceeded.
 
-For more about batching configurations, see [BatchingSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.batching.BatchingSettings).
+For more information about batching configurations, see [BatchingSettings](https://cloud.google.com/java/docs/reference/gax/latest/com.google.api.gax.batching.BatchingSettings).
 
 ### Populate log entries with metadata