# Kafka Logger 配置选项

kafka-logger 插件将请求和响应日志以 JSON 对象的形式批量推送到 Apache Kafka 集群，并支持自定义日志格式，以便更好地管理数据。<!-- --> <!-- -->配置涵盖插件参数和插件元数据。

## 参数[​](#参数 "参数的直接链接")

请参阅插件[通用配置](https://docs.apiseven.com/apisix/reference/plugin-common-configurations.md)，了解所有插件通用的配置选项。

* broker\_list

  object

  ***

  已废弃，请改用 `brokers`。Kafka broker 主机及其端口的映射。`broker_list` 和 `brokers` 二选一配置。

* brokers

  array

  有效值：

  大于 0

  ***

  Kafka broker 节点列表。`brokers` 和已废弃的 `broker_list` 二选一配置。

  * host

    string

    必填

    ***

    Kafka broker 的主机。

  * port

    integer

    必填

    ***

    Kafka broker 的端口。

  * sasl\_config

    object

    ***

    Kafka broker 的 SASL 配置。

    * mechanism

      string

      默认值：`PLAIN`

      有效值：

      `PLAIN`、`SCRAM-SHA-256` 或 `SCRAM-SHA-512`

      ***

      SASL 配置的机制。

      `SCRAM-SHA-256` 和 `SCRAM-SHA-512` 选项在 API7 企业版 3.8.16 及更高版本和 APISIX 3.15.0 及更高版本中可用。

    * user

      string

      必填

      ***

      SASL 配置的用户名。

    * password

      string

      必填

      ***

      SASL 配置的密码。该值在存储到 etcd 前会使用 AES 加密。

* tls

  object

  ***

  连接 Kafka broker 时使用的 TLS 配置。配置该对象即表示以 TLS 连接；不配置则以明文连接。自 API7 企业版 3.9.x 系列的 3.9.17 版本起可用，3.10.x 系列自 3.10.4 版本起可用；在 APISIX 中自 3.18.0 版本起可用。

  * verify

    boolean

    默认值：`false`

    ***

    如果为 true，则根据已配置的受信任 CA 校验 Kafka broker 的 TLS 证书。

    默认值为 `false`，此时配置 `tls` 只会加密连接，但不会校验 broker 身份，存在中间人攻击风险。生产环境请设置为 `true`。

* kafka\_topic

  string

  必填

  ***

  用于组织推送日志的目标主题。

* producer\_type

  string

  默认值：`async`

  有效值：

  `async` 或 `sync`

  ***

  Kafka 生产者模式。在 `async` 模式下，消息会先在本地缓冲，再发送到 Kafka；在 `sync` 模式下，消息不会使用异步生产者缓冲区，而是直接发送。

* required\_acks

  integer

  默认值：`1`

  有效值：

  -1 或 1

  ***

  leader 需要接收到的确认数量，以便生产者认为请求已完成。这控制了发送记录的持久性。有关更多信息，请参阅 [Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。尚不支持 `acks=0`。

* api\_version

  integer

  默认值：`1`

  有效值：

  `0`、`1` 或 `2`

  ***

  向 broker 发送消息时使用的 Kafka Produce API 版本。只有版本 `2` 会携带消息时间戳，使 broker 能够存储它；使用默认值 `1` 时，消息可能在没有可用时间戳的情况下被记录。版本 `2` 要求 Kafka 0.10 或更高版本。

  Kafka 4 已移除 Produce API 版本 0–2，因此与此插件不兼容。在插件支持 Produce API 版本 3 或更高版本之前，请使用 Kafka 3.x。

  自 API7 企业版 3.9.14、3.10.1 和 APISIX 3.18.0 起引入。

* key

  string

  ***

  用于为消息分配分区的键。

* timeout

  integer

  默认值：`3`

  有效值：

  大于 0

  ***

  上游发送数据的超时时间。

* meta\_format

  string

  默认值：`default`

  有效值：

  `default` 或 `origin`

  ***

  收集请求信息的格式。设置为 `default` 时以 JSON 格式收集信息，设置为 `origin` 时保留原始 HTTP 请求格式。有关更多信息，请参阅[示例](https://docs.apiseven.com/hub/kafka-logger.md#以不同的元日志格式记录日志)。

* log\_format

  object

  ***

  使用 JSON 格式的键值对的自定义日志格式。值可以引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

  当 `meta_format` 为 `default` 时，如果 `include_req_body` 或 `include_resp_body` 为 true，请引用 `$request_body` 或 `$resp_body`，将已收集的请求体或响应体添加到自定义日志条目中。这些选项不会自动向自定义格式添加 Body 字段。

  在 APISIX 3.15.0 及更高版本中，日志格式嵌套结构支持最多五层深度。在 API7 企业版中，仅支持扁平键值结构；尚不支持嵌套结构。

  当 `meta_format` 为 `origin` 时，此参数会被忽略。

  你还可以使用[插件元数据](https://docs.apiseven.com/apisix/key-concepts/plugin-metadata.md)在全局范围内配置日志格式，这将为所有 `kafka-logger` 插件实例配置日志格式。如果单个插件实例上配置的日志格式与插件元数据上配置的日志格式不同，则以单个插件实例上配置的日志格式为准。

* log\_format\_extra

  object

  ***

  用于向默认日志条目添加额外字段，使用 JSON 格式的键值对。值可引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。已配置的字段不会覆盖现有默认字段。插件实例优先于插件元数据；在实例上设置空对象会禁用元数据值。配置 `log_format` 或将 `meta_format` 配置为 `origin` 时，`log_format_extra` 会被忽略。

  使用[插件元数据](https://docs.apiseven.com/apisix/key-concepts/plugin-metadata.md)为所有 `kafka-logger` 实例配置额外字段。请参阅[示例](https://docs.apiseven.com/hub/kafka-logger.md#add-request-and-response-headers-with-plugin-metadata)了解更多详情。

  自 API7 企业版 3.9.15、3.10.2 和 APISIX 3.18.0 起引入。

* include\_req\_body

  boolean

  默认值：`false`

  ***

  如果为 true，则收集请求体。当 `meta_format` 为 `default` 时，将其添加到默认日志字段；当 `meta_format` 为 `origin` 时，将其追加到原始 HTTP 请求。无论请求体缓存在内存还是临时文件中，都可以记录；`max_req_body_bytes` 限制所记录请求体的大小。

* include\_req\_body\_expr

  array\[array]

  ***

  一个或多个 [APISIX 表达式](https://docs.apiseven.com/apisix/reference/apisix-expressions.md) 条件组成的数组。当 `include_req_body` 为 true 时，表达式控制是否主动读取请求体，以及默认日志格式中的 `request.body` 字段。即使表达式计算结果为 false，引用 `$request_body` 的自定义 `log_format` 或 `log_format_extra` 字段仍可能包含 NGINX 已缓冲的请求体。`origin` 元日志格式也会直接追加任何可获取的请求体，而不会重新计算这些表达式。请勿将此选项用作数据脱敏边界。

* max\_req\_body\_bytes

  integer

  默认值：`524288`

  有效值：

  大于或等于 1

  ***

  允许的最大请求体（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置的值，则在推送到 Kafka 之前将截断该主体。

* include\_resp\_body

  boolean

  默认值：`false`

  ***

  如果为 true，则收集响应体。使用默认日志字段时，它会添加到 `response.body`；使用自定义 `log_format` 时，请引用 `$resp_body` 将其添加到日志条目中。当 `meta_format` 为 `origin` 时，不会添加响应体。`max_resp_body_bytes` 参数限制所记录响应体的大小。

* include\_resp\_body\_expr

  array\[array]

  ***

  一个或多个 [APISIX 表达式](https://docs.apiseven.com/apisix/reference/apisix-expressions.md) 形式的条件数组。当 `include_resp_body` 为 true 时使用。仅当此处配置的表达式评估为 true 时，才会记录响应体。

* max\_resp\_body\_bytes

  integer

  默认值：`524288`

  有效值：

  大于或等于 1

  ***

  允许的最大响应体（以字节为单位）。在此限制内的响应体将被推送到 Kafka。如果大小超过配置的值，则在推送到 Kafka 之前将截断该主体。

* cluster\_name

  integer

  默认值：`1`

  有效值：

  大于或等于 1

  ***

  集群名称。当有两个或多个 Kafka 集群时使用。仅当 `producer_type` 设置为 `async` 时有效。

* producer\_batch\_num

  integer

  默认值：`200`

  有效值：

  大于或等于 1

  ***

  一批发送的消息数量。与 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_num` 参数相同。

* producer\_batch\_size

  integer

  默认值：`1048576`

  有效值：

  大于或等于 0

  ***

  发送数据时使用的 TCP 发送缓冲区大小。与 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数相同，但以字节为单位。

* producer\_max\_buffering

  integer

  默认值：`50000`

  有效值：

  大于或等于 1

  ***

  异步生产者可在本地缓冲的 Kafka 生产者消息数上限。与 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数相同。此缓冲区不受 `max_pending_entries` 限制；内存用量还取决于 worker 数量、`batch_max_size`、日志格式，以及是否记录请求体或响应体。

* producer\_time\_linger

  integer

  默认值：`1`

  有效值：

  大于或等于 1

  ***

  刷新时间。与 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `flush_time` 参数相同，但以秒为单位。

* meta\_refresh\_interval

  integer

  默认值：`30`

  有效值：

  大于或等于 1

  ***

  自动刷新元数据的时间间隔。与 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `refresh_interval` 参数相同，但以秒为单位。

* name

  string

  默认值：`kafka logger`

  ***

  批处理器的插件唯一标识符。如果你使用 [Prometheus](https://docs.apiseven.com/hub/prometheus.md) 监控 APISIX 指标，则名称将导出到 `apisix_batch_process_entries` 中。

* batch\_max\_size

  integer

  默认值：`1000`

  有效值：

  大于 0

  ***

  一批中允许的日志条目数。一旦达到，批次将被发送到日志服务。将此参数设置为 1 表示立即处理。

* inactive\_timeout

  integer

  默认值：`5`

  有效值：

  大于 0

  ***

  在将批次发送到日志服务之前等待新日志的最长时间（以秒为单位）。该值应小于 `buffer_duration`。

* buffer\_duration

  integer

  默认值：`60`

  有效值：

  大于 0

  ***

  在将批次发送到日志服务之前，从最早的条目开始允许的最长时间（以秒为单位）。

* retry\_delay

  integer

  默认值：`1`

  有效值：

  大于或等于 0

  ***

  如果批次未成功发送，则重试将批次发送到日志服务的时间间隔（以秒为单位）。

* max\_retry\_count

  integer

  默认值：`0`

  有效值：

  大于或等于 0

  ***

  丢弃日志条目之前允许的最大失败重试次数。

## 插件元数据[​](#插件元数据 "插件元数据的直接链接")

* log\_format

  object

  ***

  使用 JSON 格式的键值对的自定义日志格式。值可以引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。

  在 APISIX 3.15.0 及更高版本中，日志格式嵌套结构支持最多五层深度。在 API7 企业版中，仅支持扁平键值结构；尚不支持嵌套结构。

  对于 `meta_format` 为 `origin` 的插件实例，此配置会被忽略。

* log\_format\_extra

  object

  ***

  用于向默认日志条目添加额外字段，使用 JSON 格式的键值对。值可引用[内置变量](https://docs.apiseven.com/apisix/reference/built-in-variables.md)。已配置的字段不会覆盖现有默认字段。插件实例优先于插件元数据；在实例上设置空对象会禁用元数据值。配置 `log_format` 或插件实例使用 `meta_format: origin` 时，`log_format_extra` 会被忽略。

  自 API7 企业版 3.9.15、3.10.2 和 APISIX 3.18.0 起引入。

* max\_pending\_entries

  integer

  默认值：`8192`

  有效值：

  大于或等于 1

  ***

  批处理器中等待处理的最大条目数。当积压达到此限制时，新条目会被丢弃。此设置不限制 Kafka 异步生产者的本地缓冲区。

  在 APISIX 3.18.0、API7 企业版 3.9 分支的 3.9.19 以及 3.10 分支的 3.10.6 中，默认值变更为 `8192`。在 API7 企业版 3.9.18、3.10.5 及更早的 APISIX 版本中，省略该参数会使积压队列不设上限。

  有关容量规划和验证指南，请参见[批处理器](https://docs.apiseven.com/apisix/reference/batch-processor.md#配置待处理条目上限)。
