跳到主要内容
版本：3.18.0

批处理器

APISIX 批处理器会先将日志和指标等条目组成批次，再由插件将其发送到目标。在正常负载下，批处理可以减少网络操作次数；有界的待处理条目队列则可避免目标不可用时无限占用工作进程内存。

使用通用批处理器的插件会在配置中公开批处理参数。通过批处理器管理器集成的插件还会在其元数据中公开 max_pending_entries。error-log-logger 插件直接使用批处理器，不会公开此积压限制。

配置批次投递​

以下参数用于控制 APISIX 发送批次的时机以及处理投递失败的方式。表中列出大多数使用此处理器的插件所采用的默认值；如有例外，请查阅相应插件的配置参考。

参数默认值描述
batch_max_size1000（lago 为 100）单个批次中的最大条目数。值为 1 时，每个条目都会立即发送。
inactive_timeout5（error-log-logger 为 3）在发送当前批次前，等待下一个条目的最长时间（秒）。此值应小于 buffer_duration。
buffer_duration60在 APISIX 发送批次前，最早条目允许存在的最长时间（秒）。
max_retry_count0投递失败后的最大重试次数。超过重试上限时，APISIX 会丢弃受影响的条目。
retry_delay1投递失败后再次重试前的延迟时间（秒）。

实际批次大小取决于目标和插件。例如，目标可能对请求正文或消息大小设有限制。请选择合适的 batch_max_size，确保序列化后的批次不超过该限制。

配置待处理条目上限​

对于通过批处理器管理器集成的插件，每个工作进程都会将待处理条目存储在内存中，直到目标接受这些条目或重试策略将其丢弃。APISIX 默认将积压限制为 8192 个条目。error-log-logger 不支持此限制。若要使用不同的限制，请在插件元数据中配置 max_pending_entries：

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
  }'

当积压达到配置的上限时，APISIX 会丢弃新条目，直到待处理任务数量降至该上限以下。APISIX 每秒最多向错误日志写入一次汇总信息：

max pending entries limit exceeded. discarding entry. total_pushed_entries: 12289 total_processed_entries: 4096 max_pending_entries: 8192 discarded_entries: 3172

该限制分别应用于每个工作进程。对于一个插件，可用 max_pending_entries 乘以工作进程数来估算网关的积压条目总数。然后还需考虑每个条目的大小，以及等待投递的所有序列化批次。

估算内存使用量​

内存使用量主要取决于条目大小。启用请求或响应正文日志记录后，每个条目可能显著增大，尤其是在相应的正文大小限制较高时。

下列数据来自一次 http-logger 压力测试。在该测试中，目标接受连接但不返回响应；测试采用每秒 3000 个请求、默认的 max_pending_entries 和批处理设置，并在表中注明的位置同时记录请求与响应正文。请将这些数据视为容量规划示例，不要将其当作其他工作负载或环境的容量保证。

每个请求记录的正文数据工作进程内存增长峰值（约）
不记录正文40 MB
1 KB 请求正文和 1 KB 响应正文100 MB
4 KB 请求正文和 4 KB 响应正文250 MB
16 KB 请求正文和 16 KB 响应正文840 MB

当条目包含较大正文或网关的单工作进程内存预算较紧时，请降低 max_pending_entries。投递正常时，积压通常会保持在接近 batch_max_size 的水平；如果增大 batch_max_size，请确保 max_pending_entries 仍足以容纳正常的待处理批次。

验证积压保护​

更改上限后，请使用延迟响应或不可用的日志目标进行测试。监控工作进程内存和 APISIX 错误日志，然后确认目标恢复后日志投递也随之恢复。较低的上限可以更早保护网关内存，但也会在故障期间更早丢弃日志。