Batch Processor
The APISIX batch processor groups entries, such as logs and metrics, before a plugin sends them to its destination. Batching reduces the number of network operations under normal load, while a bounded pending-entry queue prevents an unavailable destination from consuming worker memory without limit.
Plugins that use the common batch processor expose batching parameters in their configuration. Plugins integrated through the batch processor manager also expose max_pending_entries in their metadata. The error-log-logger plugin uses a direct batch processor and does not expose this backlog limit.
Configure Batch Delivery
The following parameters control when APISIX sends a batch and how it handles delivery failures. The table shows the defaults used by most plugins that use this processor; check the plugin configuration reference for exceptions.
| Parameter | Default | Description |
|---|---|---|
batch_max_size | 1000 (100 for lago) | Maximum number of entries in one batch. A value of 1 sends each entry immediately. |
inactive_timeout | 5 (3 for error-log-logger) | Maximum time in seconds to wait for another entry before sending the current batch. Keep this value lower than buffer_duration. |
buffer_duration | 60 | Maximum age in seconds of the oldest entry before APISIX sends the batch. |
max_retry_count | 0 | Maximum number of retries after a delivery failure. APISIX drops the affected entries when the retry limit is exceeded. |
retry_delay | 1 | Delay in seconds before retrying a failed delivery. |
The destination and plugin determine the practical batch size. For example, a destination may impose a request-body or message-size limit. Choose a batch_max_size that keeps the serialized batch within that limit.
Configure the Pending-Entry Limit
For plugins integrated through the batch processor manager, each worker stores pending entries in memory until the destination accepts them or the retry policy drops them. APISIX limits this backlog to 8192 entries by default. This limit is not available for error-log-logger. Configure max_pending_entries in the plugin's metadata to use a different limit:
curl "http://127.0.0.1:9180/apisix/admin/plugin_metadata/http-logger" -X PUT \
-H "X-API-KEY: ${ADMIN_API_KEY}" \
-d '{
"max_pending_entries": 4096
}'
When the backlog reaches the configured limit, APISIX discards new entries until pending work falls below the limit. It writes a summary to the error log at most once per second:
max pending entries limit exceeded. discarding entry. total_pushed_entries: 12289 total_processed_entries: 4096 max_pending_entries: 8192 discarded_entries: 3172
The limit applies independently in each worker. For one plugin, estimate the total gateway backlog as max_pending_entries multiplied by the number of workers. Then account for the size of each entry and any serialized batches awaiting delivery.
Estimate Memory Use
Memory use depends primarily on entry size. Enabling request or response body logging can make each entry substantially larger, especially when the corresponding body-size limits are high.
The following measurements are from one http-logger stress test in which the destination accepted connections but did not respond. The test used 3000 requests per second, the default max_pending_entries and batch settings, and logged both request and response bodies where shown. Treat these figures as sizing examples, not capacity guarantees for other workloads or environments.
| Body data logged per request | Approximate peak worker-memory growth |
|---|---|
| No bodies | 40 MB |
| 1 KB request and 1 KB response | 100 MB |
| 4 KB request and 4 KB response | 250 MB |
| 16 KB request and 16 KB response | 840 MB |
Lower max_pending_entries when entries contain large bodies or when the gateway has a tight per-worker memory budget. Under healthy delivery, the backlog normally stays close to batch_max_size; if you increase batch_max_size, make sure max_pending_entries remains large enough to hold normal pending batches.
Verify Backlog Protection
After changing the limit, test with a delayed or unavailable logging destination. Monitor worker memory and the APISIX error log, then confirm that log delivery resumes after the destination recovers. A lower limit protects gateway memory sooner but discards logs earlier during an outage.