diff --git a/README.md b/README.md index de2fab9b8..7b14f4198 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` file configures the batching behavior: + +``` + + 100 + 1000 + 500 + 10000 + 100000 + Ignore + +``` +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 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 The library provides multiple ways to enrich log entries with additional information.