You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "Yilialinn (via GitHub)" <gi...@apache.org> on 2026/04/21 12:38:54 UTC
[PR] docs: update kafka-logger plugin documentation [apisix]
Yilialinn opened a new pull request, #13278:
URL: https://github.com/apache/apisix/pull/13278
## Summary
- Add canonical link to API7 docs
- Update frontmatter `description` to better reflect plugin capabilities
- Fix `Required` column: `optional` → `False` for `producer_batch_num`, `producer_batch_size`, `producer_max_buffering`, `producer_time_linger`, and `meta_refresh_interval`; fix `brokers.port` type `string` → `integer` in ZH doc
- Replace minimal "Enable Plugin" and "Example usage" sections with three comprehensive examples:
1. **Log in Different Meta Log Formats** — includes Docker Compose setup, full route configuration, and comparison of `default` vs `origin` log output
2. **Log Request and Response Headers With Plugin Metadata** — demonstrates using plugin metadata with built-in variables to capture custom request/response headers
3. **Log Request Bodies Conditionally** — shows `include_req_body` + `include_req_body_expr` for conditional body logging
- Remove "Delete Plugin" section
- Add `admin_key` note block before the first Admin API curl example
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update kafka-logger plugin documentation [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn commented on code in PR #13278:
URL: https://github.com/apache/apisix/pull/13278#discussion_r3123137526
##########
docs/zh/latest/plugins/kafka-logger.md:
##########
@@ -27,123 +27,174 @@ description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/kafka-logger" />
+</head>
+
## 描述
-`kafka-logger` 插件用于将日志作为 JSON 对象推送到 Apache Kafka 集群中。可用作 `ngx_lua` NGINX 模块的 Kafka 客户端驱动程序。
+`kafka-logger` 插件将请求和响应日志作为 JSON 对象批量推送到 Apache Kafka 集群，并支持自定义日志格式。
+
+接收日志数据可能需要一些时间。数据将在 [批处理器](../batch-processor.md) 中的计时器函数到期后自动发送。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------------- | ------- | ------ | -------------- | --------------------- | ------------------------------------------------ |
-| broker_list | object | 是 | | | 已废弃，现使用 `brokers` 属性代替。原指需要推送的 Kafka 的 broker 列表。 |
-| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
-| brokers.host | string | 是 | | | Kafka broker 的节点 host 配置，例如 `192.168.1.1` |
-| brokers.port | string | 是 | | | Kafka broker 的节点端口配置 |
-| brokers.sasl_config | object | 否 | | | Kafka broker 中的 sasl_config |
-| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | Kafka broker 中的 sasl 认证机制 |
-| brokers.sasl_config.user | string | 是 | | | Kafka broker 中 sasl 配置中的 user，如果 sasl_config 存在，则必须填写 |
-| brokers.sasl_config.password | string | 是 | | | Kafka broker 中 sasl 配置中的 password，如果 sasl_config 存在，则必须填写 |
-| kafka_topic | string | 是 | | | 需要推送的 topic。 |
-| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
-| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的反馈信息的数量。该参数是为了保证发送请求的可靠性。该属性的配置与 Kafka `acks` 属性相同，具体配置请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。required_acks 还不支持为 0。 |
-| key | string | 否 | | | 用于消息分区而分配的密钥。 |
-| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 |
-| name | string | 否 | "kafka logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 |
-| meta_format | enum | 否 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。更多信息，请参考 [meta_format](#meta_format-示例)。|
-| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
-| include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。|
-| include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
-| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大请求正文（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 |
-| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时才会记录响应体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。|
-| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大响应正文（以字节为单位）。低于此限制的响应主体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| cluster_name | integer | 否 | 1 | [0,...] | Kafka 集群的名称，当有两个及以上 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,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数，单位为字节。 |
-| producer_max_buffering | integer | 否 | 50000 | [1,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数，表示最大缓冲区，单位为条。 |
-| 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` 参数，用于指定自动刷新 metadata 的间隔时长，单位为秒。 |
-
-该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
-
-:::tip 提示
-
-数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，则会将数据发送到 Kafka 服务器并刷新缓冲区。
+| 名称 | 类型 | 是否必需 | 默认值 | 有效值 | 描述 |
+| -------------------------------- | ------- | -------- | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| broker_list | object | 否 | | | 已废弃，请改用 `brokers` 属性。原指需要推送的 Kafka 的 broker 列表。 |
+| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
+| brokers.host | string | 是 | | | Kafka broker 的节点地址，例如 `192.168.1.1`。 |
+| brokers.port | integer | 是 | | [0, 65535] | Kafka broker 的节点端口。 |
+| brokers.sasl_config | object | 否 | | | Kafka broker 的 SASL 配置。 |
+| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | SASL 认证机制。 |
+| brokers.sasl_config.user | string | 是 | | | SASL 配置中的用户名。如果配置了 `sasl_config`，则必须填写。 |
+| brokers.sasl_config.password | string | 是 | | | SASL 配置中的密码。如果配置了 `sasl_config`，则必须填写。 |
+| kafka_topic | string | 是 | | | 用于推送日志的目标 topic。 |
+| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
+| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的确认信息数量，用于保证发送请求的可靠性。该属性与 Kafka 的 `acks` 属性配置相同，`required_acks` 不能为 0。详情请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。 |
+| key | string | 否 | | | 用于消息分区的键。 |
+| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间（秒）。 |
+| name | string | 否 | "kafka logger" | | 批处理器的唯一标识符。如果使用 Prometheus 监控 APISIX 指标，该名称将以 `apisix_batch_process_entries` 导出。 |
+| meta_format | enum | 否 | "default" | ["default","origin"] | 收集请求信息的格式。设置为 `default` 时以 JSON 格式收集信息，设置为 `origin` 时以 HTTP 原始请求格式收集信息。详情请参考下方 [示例](#meta_format-示例)。 |
+| log_format | object | 否 | | | 以 JSON 键值对声明的日志格式。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
+| include_req_body | boolean | 否 | false | [false, true] | 设置为 `true` 时，在日志中包含请求体。**注意**：如果请求体过大无法完全存放在内存中，由于 NGINX 的限制，将无法记录。 |
+| include_req_body_expr | array | 否 | | | 当 `include_req_body` 设置为 `true` 时的过滤条件。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。详情请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
+| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许推送到 Kafka 的最大请求体大小（字节）。如果超过该值，请求体在推送前会被截断。 |
+| include_resp_body | boolean | 否 | false | [false, true] | 设置为 `true` 时，在日志中包含响应体。 |
+| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 设置为 `true` 时的过滤条件。只有当此处设置的表达式计算结果为 `true` 时，才会记录响应体。详情请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
+| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许推送到 Kafka 的最大响应体大小（字节）。如果超过该值，响应体在推送前会被截断。 |
+| cluster_name | integer | 否 | 1 | [0,...] | Kafka 集群的名称，在有两个或多个 Kafka 集群时使用。仅当 `producer_type` 设置为 `async` 时有效。 |
Review Comment:
https://github.com/apache/apisix/blob/5ca64d18b03db3deda73098ca030f6f33d33a678/apisix/plugins/kafka-logger.lua#L124
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update kafka-logger plugin documentation [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn commented on code in PR #13278:
URL: https://github.com/apache/apisix/pull/13278#discussion_r3123132803
##########
docs/zh/latest/plugins/kafka-logger.md:
##########
@@ -27,123 +27,174 @@ description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/kafka-logger" />
+</head>
+
## 描述
-`kafka-logger` 插件用于将日志作为 JSON 对象推送到 Apache Kafka 集群中。可用作 `ngx_lua` NGINX 模块的 Kafka 客户端驱动程序。
+`kafka-logger` 插件将请求和响应日志作为 JSON 对象批量推送到 Apache Kafka 集群，并支持自定义日志格式。
+
+接收日志数据可能需要一些时间。数据将在 [批处理器](../batch-processor.md) 中的计时器函数到期后自动发送。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------------- | ------- | ------ | -------------- | --------------------- | ------------------------------------------------ |
-| broker_list | object | 是 | | | 已废弃，现使用 `brokers` 属性代替。原指需要推送的 Kafka 的 broker 列表。 |
-| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
-| brokers.host | string | 是 | | | Kafka broker 的节点 host 配置，例如 `192.168.1.1` |
-| brokers.port | string | 是 | | | Kafka broker 的节点端口配置 |
-| brokers.sasl_config | object | 否 | | | Kafka broker 中的 sasl_config |
-| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | Kafka broker 中的 sasl 认证机制 |
-| brokers.sasl_config.user | string | 是 | | | Kafka broker 中 sasl 配置中的 user，如果 sasl_config 存在，则必须填写 |
-| brokers.sasl_config.password | string | 是 | | | Kafka broker 中 sasl 配置中的 password，如果 sasl_config 存在，则必须填写 |
-| kafka_topic | string | 是 | | | 需要推送的 topic。 |
-| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
-| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的反馈信息的数量。该参数是为了保证发送请求的可靠性。该属性的配置与 Kafka `acks` 属性相同，具体配置请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。required_acks 还不支持为 0。 |
-| key | string | 否 | | | 用于消息分区而分配的密钥。 |
-| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 |
-| name | string | 否 | "kafka logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 |
-| meta_format | enum | 否 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。更多信息，请参考 [meta_format](#meta_format-示例)。|
-| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
-| include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。|
-| include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
-| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大请求正文（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 |
-| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时才会记录响应体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。|
-| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大响应正文（以字节为单位）。低于此限制的响应主体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| cluster_name | integer | 否 | 1 | [0,...] | Kafka 集群的名称，当有两个及以上 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,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数，单位为字节。 |
-| producer_max_buffering | integer | 否 | 50000 | [1,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数，表示最大缓冲区，单位为条。 |
-| 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` 参数，用于指定自动刷新 metadata 的间隔时长，单位为秒。 |
-
-该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
-
-:::tip 提示
-
-数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，则会将数据发送到 Kafka 服务器并刷新缓冲区。
+| 名称 | 类型 | 是否必需 | 默认值 | 有效值 | 描述 |
+| -------------------------------- | ------- | -------- | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| broker_list | object | 否 | | | 已废弃，请改用 `brokers` 属性。原指需要推送的 Kafka 的 broker 列表。 |
+| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
+| brokers.host | string | 是 | | | Kafka broker 的节点地址，例如 `192.168.1.1`。 |
+| brokers.port | integer | 是 | | [0, 65535] | Kafka broker 的节点端口。 |
Review Comment:
https://github.com/apache/apisix/blob/5ca64d18b03db3deda73098ca030f6f33d33a678/apisix/plugins/kafka-logger.lua#L66-L70
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update kafka-logger plugin documentation [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn merged PR #13278:
URL: https://github.com/apache/apisix/pull/13278
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update kafka-logger plugin documentation [apisix]
Posted by "Yilialinn (via GitHub)" <gi...@apache.org>.
Yilialinn commented on code in PR #13278:
URL: https://github.com/apache/apisix/pull/13278#discussion_r3158219355
##########
docs/zh/latest/plugins/kafka-logger.md:
##########
@@ -27,224 +27,460 @@ description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/kafka-logger" />
+</head>
+
## 描述
-`kafka-logger` 插件用于将日志作为 JSON 对象推送到 Apache Kafka 集群中。可用作 `ngx_lua` NGINX 模块的 Kafka 客户端驱动程序。
+`kafka-logger` 插件将请求和响应日志作为 JSON 对象批量推送到 Apache Kafka 集群，并支持自定义日志格式。
+
+接收日志数据可能需要一些时间。数据将在 [批处理器](../batch-processor.md) 中的计时器函数到期后自动发送。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------------- | ------- | ------ | -------------- | --------------------- | ------------------------------------------------ |
-| broker_list | object | 是 | | | 已废弃，现使用 `brokers` 属性代替。原指需要推送的 Kafka 的 broker 列表。 |
-| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
-| brokers.host | string | 是 | | | Kafka broker 的节点 host 配置，例如 `192.168.1.1` |
-| brokers.port | string | 是 | | | Kafka broker 的节点端口配置 |
-| brokers.sasl_config | object | 否 | | | Kafka broker 中的 sasl_config |
-| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | Kafka broker 中的 sasl 认证机制 |
-| brokers.sasl_config.user | string | 是 | | | Kafka broker 中 sasl 配置中的 user，如果 sasl_config 存在，则必须填写 |
-| brokers.sasl_config.password | string | 是 | | | Kafka broker 中 sasl 配置中的 password，如果 sasl_config 存在，则必须填写 |
-| kafka_topic | string | 是 | | | 需要推送的 topic。 |
-| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
-| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的反馈信息的数量。该参数是为了保证发送请求的可靠性。该属性的配置与 Kafka `acks` 属性相同，具体配置请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。required_acks 还不支持为 0。 |
-| key | string | 否 | | | 用于消息分区而分配的密钥。 |
-| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 |
-| name | string | 否 | "kafka logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 |
-| meta_format | enum | 否 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。更多信息，请参考 [meta_format](#meta_format-示例)。|
-| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
-| include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。|
-| include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
-| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大请求正文（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 |
-| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时才会记录响应体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。|
-| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大响应正文（以字节为单位）。低于此限制的响应主体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| cluster_name | integer | 否 | 1 | [0,...] | Kafka 集群的名称，当有两个及以上 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,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数，单位为字节。 |
-| producer_max_buffering | integer | 否 | 50000 | [1,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数，表示最大缓冲区，单位为条。 |
-| 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` 参数，用于指定自动刷新 metadata 的间隔时长，单位为秒。 |
-
-该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
-
-:::tip 提示
-
-数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，则会将数据发送到 Kafka 服务器并刷新缓冲区。
+| 名称 | 类型 | 是否必需 | 默认值 | 有效值 | 描述 |
+| -------------------------------- | ------- | -------- | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| broker_list | object | 否 | | | 已废弃，请改用 `brokers` 属性。原指需要推送的 Kafka 的 broker 列表。 |
+| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
+| brokers.host | string | 是 | | | Kafka broker 的节点地址，例如 `192.168.1.1`。 |
+| brokers.port | integer | 是 | | [1, 65535] | Kafka broker 的节点端口。 |
+| brokers.sasl_config | object | 否 | | | Kafka broker 的 SASL 配置。 |
+| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | SASL 认证机制。 |
+| brokers.sasl_config.user | string | 是 | | | SASL 配置中的用户名。如果配置了 `sasl_config`，则必须填写。 |
+| brokers.sasl_config.password | string | 是 | | | SASL 配置中的密码。如果配置了 `sasl_config`，则必须填写。 |
+| kafka_topic | string | 是 | | | 用于推送日志的目标 topic。 |
+| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
+| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的确认信息数量，用于保证发送请求的可靠性。该属性与 Kafka 的 `acks` 属性配置相同，`required_acks` 不能为 0。详情请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。 |
+| key | string | 否 | | | 用于消息分区的键。 |
+| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间（秒）。 |
+| name | string | 否 | "kafka logger" | | 批处理器的唯一标识符。如果使用 Prometheus 监控 APISIX 指标，该名称将以 `apisix_batch_process_entries` 导出。 |
+| meta_format | enum | 否 | "default" | ["default","origin"] | 收集请求信息的格式。设置为 `default` 时以 JSON 格式收集信息，设置为 `origin` 时以 HTTP 原始请求格式收集信息。详情请参考下方 [示例](#meta_format-示例)。 |
+| log_format | object | 否 | | | 以 JSON 键值对声明的日志格式。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
+| include_req_body | boolean | 否 | false | [false, true] | 设置为 `true` 时，在日志中包含请求体。**注意**：如果请求体过大无法完全存放在内存中，由于 NGINX 的限制，将无法记录。 |
+| include_req_body_expr | array | 否 | | | 当 `include_req_body` 设置为 `true` 时的过滤条件。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。详情请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
+| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许推送到 Kafka 的最大请求体大小（字节）。如果超过该值，请求体在推送前会被截断。 |
+| include_resp_body | boolean | 否 | false | [false, true] | 设置为 `true` 时，在日志中包含响应体。 |
+| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 设置为 `true` 时的过滤条件。只有当此处设置的表达式计算结果为 `true` 时，才会记录响应体。详情请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
+| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许推送到 Kafka 的最大响应体大小（字节）。如果超过该值，响应体在推送前会被截断。 |
+| cluster_name | integer | 否 | 1 | [1,...] | Kafka 集群的名称，在有两个或多个 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,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数，单位为字节。 |
+| producer_max_buffering | integer | 否 | 50000 | [1,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数，表示最大缓冲区大小，单位为条。 |
+| 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` 参数，用于指定自动刷新 metadata 的间隔时长，单位为秒。 |
+
+该插件支持使用批处理器来聚合并批量处理条目（日志/数据），避免频繁提交数据。默认情况下，批处理器每 `5` 秒或队列中的数据达到 `1000` 条时提交数据。如需了解批处理器相关参数设置，请参考[批处理器](../batch-processor.md#配置)配置部分。
+
+:::info 重要
+
+数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，数据将发送到 Kafka 服务器并刷新缓冲区。
如果发送成功，则返回 `true`。如果出现错误，则返回 `nil`，并带有描述错误的字符串 `buffer overflow`。
:::
### meta_format 示例
-- `default`:
-
- ```json
- {
- "upstream": "127.0.0.1:1980",
- "start_time": 1619414294760,
- "client_ip": "127.0.0.1",
- "service_id": "",
- "route_id": "1",
- "request": {
- "querystring": {
- "ab": "cd"
- },
- "size": 90,
- "uri": "/hello?ab=cd",
- "url": "http://localhost:1984/hello?ab=cd",
- "headers": {
- "host": "localhost",
- "content-length": "6",
- "connection": "close"
- },
- "body": "abcdef",
- "method": "GET"
- },
- "response": {
- "headers": {
- "connection": "close",
- "content-type": "text/plain; charset=utf-8",
- "date": "Mon, 26 Apr 2021 05:18:14 GMT",
- "server": "APISIX/2.5",
- "transfer-encoding": "chunked"
- },
- "size": 190,
- "status": 200
- },
- "server": {
- "hostname": "localhost",
- "version": "2.5"
- },
- "latency": 0
- }
- ```
+- `default`：
Review Comment:
fixed
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update kafka-logger plugin documentation [apisix]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #13278:
URL: https://github.com/apache/apisix/pull/13278#discussion_r3122106332
##########
docs/zh/latest/plugins/kafka-logger.md:
##########
@@ -27,123 +27,174 @@ description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/kafka-logger" />
+</head>
+
## 描述
-`kafka-logger` 插件用于将日志作为 JSON 对象推送到 Apache Kafka 集群中。可用作 `ngx_lua` NGINX 模块的 Kafka 客户端驱动程序。
+`kafka-logger` 插件将请求和响应日志作为 JSON 对象批量推送到 Apache Kafka 集群，并支持自定义日志格式。
+
+接收日志数据可能需要一些时间。数据将在 [批处理器](../batch-processor.md) 中的计时器函数到期后自动发送。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------------- | ------- | ------ | -------------- | --------------------- | ------------------------------------------------ |
-| broker_list | object | 是 | | | 已废弃，现使用 `brokers` 属性代替。原指需要推送的 Kafka 的 broker 列表。 |
-| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
-| brokers.host | string | 是 | | | Kafka broker 的节点 host 配置，例如 `192.168.1.1` |
-| brokers.port | string | 是 | | | Kafka broker 的节点端口配置 |
-| brokers.sasl_config | object | 否 | | | Kafka broker 中的 sasl_config |
-| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | Kafka broker 中的 sasl 认证机制 |
-| brokers.sasl_config.user | string | 是 | | | Kafka broker 中 sasl 配置中的 user，如果 sasl_config 存在，则必须填写 |
-| brokers.sasl_config.password | string | 是 | | | Kafka broker 中 sasl 配置中的 password，如果 sasl_config 存在，则必须填写 |
-| kafka_topic | string | 是 | | | 需要推送的 topic。 |
-| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
-| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的反馈信息的数量。该参数是为了保证发送请求的可靠性。该属性的配置与 Kafka `acks` 属性相同，具体配置请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。required_acks 还不支持为 0。 |
-| key | string | 否 | | | 用于消息分区而分配的密钥。 |
-| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 |
-| name | string | 否 | "kafka logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 |
-| meta_format | enum | 否 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。更多信息，请参考 [meta_format](#meta_format-示例)。|
-| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
-| include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。|
-| include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
-| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大请求正文（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 |
-| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时才会记录响应体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。|
-| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大响应正文（以字节为单位）。低于此限制的响应主体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| cluster_name | integer | 否 | 1 | [0,...] | Kafka 集群的名称，当有两个及以上 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,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数，单位为字节。 |
-| producer_max_buffering | integer | 否 | 50000 | [1,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数，表示最大缓冲区，单位为条。 |
-| 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` 参数，用于指定自动刷新 metadata 的间隔时长，单位为秒。 |
-
-该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
-
-:::tip 提示
-
-数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，则会将数据发送到 Kafka 服务器并刷新缓冲区。
+| 名称 | 类型 | 是否必需 | 默认值 | 有效值 | 描述 |
+| -------------------------------- | ------- | -------- | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| broker_list | object | 否 | | | 已废弃，请改用 `brokers` 属性。原指需要推送的 Kafka 的 broker 列表。 |
+| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
+| brokers.host | string | 是 | | | Kafka broker 的节点地址，例如 `192.168.1.1`。 |
+| brokers.port | integer | 是 | | [0, 65535] | Kafka broker 的节点端口。 |
Review Comment:
`brokers.port` 的有效值写为 `[0, 65535]`，但插件 schema 中该字段 `minimum = 1`（端口 0 不合法）。建议将有效范围改为 `[1, 65535]` 以与实际校验一致。
```suggestion
| brokers.port | integer | 是 | | [1, 65535] | Kafka broker 的节点端口。 |
```
##########
docs/zh/latest/plugins/kafka-logger.md:
##########
@@ -155,96 +206,289 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
:::
+### 使用不同的元日志格式记录日志
+
+以下示例演示了如何在路由上启用 `kafka-logger` 插件记录客户端请求并将日志推送到 Kafka，同时介绍 `default` 和 `origin` 元日志格式的区别。
+
+在另一个终端中，等待配置的 Kafka topic 中的消息：
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/kafka-logger \
--H "X-API-KEY: $admin_key" -X PUT -d '
+docker exec -it kafka kafka-console-consumer --bootstrap-server localhost:9092 --topic test2 --from-beginning
+```
+
+打开一个新终端，执行以下操作。
+
+创建一条启用 `kafka-logger` 插件的路由。将 `meta_format` 设置为 `default` 日志格式，并将 `batch_max_size` 设置为 `1` 以立即发送日志条目：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "kafka-logger-route",
+ "uri": "/get",
+ "plugins": {
+ "kafka-logger": {
+ "meta_format": "default",
+ "brokers": [
+ {
+ "host": "kafka",
+ "port": 29092
+ }
+ ],
+ "kafka_topic": "test2",
+ "key": "key1",
+ "batch_max_size": 1
+ }
+ },
+ "upstream": {
+ "nodes": {
+ "httpbin.org:80": 1
+ },
+ "type": "roundrobin"
+ }
+ }'
+```
+
+向路由发送请求以生成日志条目：
+
+```shell
+curl -i "http://127.0.0.1:9080/get"
+```
+
+你应该收到一个 `HTTP/1.1 200 OK` 响应。
+
+你应该在 Kafka topic 中看到类似如下的日志条目：
+
+```json
{
- "log_format": {
- "host": "$host",
- "@timestamp": "$time_iso8601",
- "client_ip": "$remote_addr",
- "request": { "method": "$request_method", "uri": "$request_uri" },
- "response": { "status": "$status" }
+ "latency": 411.00001335144,
+ "request": {
+ "querystring": {},
+ "headers": {
+ "host": "127.0.0.1:9080",
+ "user-agent": "curl/8.7.1",
+ "accept": "*/*",
+ "x-forwarded-proto": "http",
+ "x-forwarded-host": "127.0.0.1",
+ "x-forwarded-port": "9080"
+ },
+ "method": "GET",
+ "size": 83,
+ "uri": "/get",
+ "url": "http://127.0.0.1:9080/get"
+ },
+ "response": {
+ "headers": {
+ "content-length": "233",
+ "access-control-allow-credentials": "true",
+ "content-type": "application/json",
+ "connection": "close",
+ "access-control-allow-origin": "*",
+ "date": "Fri, 10 Nov 2023 06:02:44 GMT",
+ "server": "APISIX/3.16.0"
+ },
+ "status": 200,
+ "size": 475
+ },
+ "route_id": "kafka-logger-route",
+ "client_ip": "127.0.0.1",
+ "server": {
+ "hostname": "apisix",
+ "version": "3.16.0"
+ },
+ "apisix_latency": 18.00001335144,
+ "service_id": "",
+ "upstream_latency": 393,
+ "start_time": 1699596164550,
+ "upstream": "54.90.18.68:80"
+}
+```
+
+将元日志格式更新为 `origin`：
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/kafka-logger-route" -X PATCH \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "plugins": {
+ "kafka-logger": {
+ "meta_format": "origin"
+ }
}
-}'
+ }'
```
-配置完成后，你将在日志系统中看到如下类似日志：
+再次向路由发送请求以生成新的日志条目：
```shell
-{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"}
-{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"}
+curl -i "http://127.0.0.1:9080/get"
+```
+
+你应该收到一个 `HTTP/1.1 200 OK` 响应。
+
+你应该在 Kafka topic 中看到类似如下的日志条目：
+
+```text
+GET /get HTTP/1.1
+x-forwarded-proto: http
+x-forwarded-host: 127.0.0.1
+user-agent: curl/8.7.1
+x-forwarded-port: 9080
+host: 127.0.0.1:9080
+accept: */*
```
-## 如何启用
+### 通过插件元数据记录请求和响应头
-你可以通过如下命令在指定路由上启用 `kafka-logger` 插件：
+以下示例演示了如何使用[插件元数据](../terminology/plugin.md)和[内置变量](../apisix-variable.md)自定义日志格式，以记录请求和响应中的特定头字段。
Review Comment:
文中“插件元数据”的链接指向了 `../terminology/plugin.md`，但该概念有专门页面 `../terminology/plugin-metadata.md`。建议更新链接目标，方便读者查阅正确的术语说明。
```suggestion
以下示例演示了如何使用[插件元数据](../terminology/plugin-metadata.md)和[内置变量](../apisix-variable.md)自定义日志格式，以记录请求和响应中的特定头字段。
```
##########
docs/en/latest/plugins/kafka-logger.md:
##########
@@ -158,95 +206,289 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
:::
+### Log in Different Meta Log Formats
+
+The following example demonstrates how to enable the `kafka-logger` Plugin on a Route, which logs client requests and pushes logs to Kafka. You will also understand the differences between the `default` and `origin` meta log formats.
+
+In a separate terminal, wait for messages in the configured Kafka topic:
+
```shell
-curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/kafka-logger -H "X-API-KEY: $admin_key" -X PUT -d '
+docker exec -it kafka kafka-console-consumer --bootstrap-server localhost:9092 --topic test2 --from-beginning
+```
+
+Open a new terminal session for the following steps.
+
+Create a Route with `kafka-logger`. Set `meta_format` to the `default` log format, and set `batch_max_size` to `1` to send the log entry immediately:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "id": "kafka-logger-route",
+ "uri": "/get",
+ "plugins": {
+ "kafka-logger": {
+ "meta_format": "default",
+ "brokers": [
+ {
+ "host": "kafka",
+ "port": 29092
+ }
+ ],
+ "kafka_topic": "test2",
+ "key": "key1",
+ "batch_max_size": 1
+ }
+ },
+ "upstream": {
+ "nodes": {
+ "httpbin.org:80": 1
+ },
+ "type": "roundrobin"
+ }
+ }'
+```
+
+Send a request to the Route to generate a log entry:
+
+```shell
+curl -i "http://127.0.0.1:9080/get"
+```
+
+You should see an `HTTP/1.1 200 OK` response.
+
+You should see a log entry in the Kafka topic similar to the following:
+
+```json
{
- "log_format": {
- "host": "$host",
- "@timestamp": "$time_iso8601",
- "client_ip": "$remote_addr",
- "request": { "method": "$request_method", "uri": "$request_uri" },
- "response": { "status": "$status" }
+ "latency": 411.00001335144,
+ "request": {
+ "querystring": {},
+ "headers": {
+ "host": "127.0.0.1:9080",
+ "user-agent": "curl/8.7.1",
+ "accept": "*/*",
+ "x-forwarded-proto": "http",
+ "x-forwarded-host": "127.0.0.1",
+ "x-forwarded-port": "9080"
+ },
+ "method": "GET",
+ "size": 83,
+ "uri": "/get",
+ "url": "http://127.0.0.1:9080/get"
+ },
+ "response": {
+ "headers": {
+ "content-length": "233",
+ "access-control-allow-credentials": "true",
+ "content-type": "application/json",
+ "connection": "close",
+ "access-control-allow-origin": "*",
+ "date": "Fri, 10 Nov 2023 06:02:44 GMT",
+ "server": "APISIX/3.16.0"
+ },
+ "status": 200,
+ "size": 475
+ },
+ "route_id": "kafka-logger-route",
+ "client_ip": "127.0.0.1",
+ "server": {
+ "hostname": "apisix",
+ "version": "3.16.0"
+ },
+ "apisix_latency": 18.00001335144,
+ "service_id": "",
+ "upstream_latency": 393,
+ "start_time": 1699596164550,
+ "upstream": "54.90.18.68:80"
+}
+```
+
+Update the meta log format to `origin`:
+
+```shell
+curl "http://127.0.0.1:9180/apisix/admin/routes/kafka-logger-route" -X PATCH \
+ -H "X-API-KEY: ${admin_key}" \
+ -d '{
+ "plugins": {
+ "kafka-logger": {
+ "meta_format": "origin"
+ }
}
-}'
+ }'
```
-With this configuration, your logs would be formatted as shown below:
+Send a request to the Route again to generate a new log entry:
```shell
-{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"}
-{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","request":{"method":"GET","uri":"/hello"},"response":{"status":200},"route_id":"1"}
+curl -i "http://127.0.0.1:9080/get"
```
-## Enable Plugin
+You should see an `HTTP/1.1 200 OK` response.
+
+You should see a log entry in the Kafka topic similar to the following:
+
+```text
+GET /get HTTP/1.1
+x-forwarded-proto: http
+x-forwarded-host: 127.0.0.1
+user-agent: curl/8.7.1
+x-forwarded-port: 9080
+host: 127.0.0.1:9080
+accept: */*
+```
-The example below shows how you can enable the `kafka-logger` Plugin on a specific Route:
+### Log Request and Response Headers With Plugin Metadata
+
+The following example demonstrates how to customize the log format using [plugin metadata](../terminology/plugin.md) and [built-in variables](../apisix-variable.md) to log specific headers from request and response.
Review Comment:
The link for “plugin metadata” points to `../terminology/plugin.md`, but the dedicated terminology page is `../terminology/plugin-metadata.md`. Please update the link target so readers land on the correct concept page.
```suggestion
The following example demonstrates how to customize the log format using [plugin metadata](../terminology/plugin-metadata.md) and [built-in variables](../apisix-variable.md) to log specific headers from request and response.
```
##########
docs/en/latest/plugins/kafka-logger.md:
##########
@@ -27,44 +27,48 @@ description: This document contains information about the Apache APISIX kafka-lo
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/kafka-logger" />
+</head>
+
## Description
-The `kafka-logger` Plugin is used to push logs as JSON objects to Apache Kafka clusters. It works as a Kafka client driver for the ngx_lua Nginx module.
+The `kafka-logger` Plugin pushes request and response logs as JSON objects to Apache Kafka clusters in batches and supports the customization of log formats.
It might take some time to receive the log data. It will be automatically sent after the timer function in the [batch processor](../batch-processor.md) expires.
## Attributes
-| Name | Type | Required | Default | Valid values | Description |
-| ---------------------- | ------- | -------- | -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| broker_list | object | True | | | Deprecated, use `brokers` instead. List of Kafka brokers. (nodes). |
-| brokers | array | True | | | List of Kafka brokers (nodes). |
-| brokers.host | string | True | | | The host of Kafka broker, e.g, `192.168.1.1`. |
-| brokers.port | integer | True | | [0, 65535] | The port of Kafka broker |
-| brokers.sasl_config | object | False | | | The sasl config of Kafka broker |
-| brokers.sasl_config.mechanism | string | False | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | The mechaism of sasl config |
-| brokers.sasl_config.user | string | True | | | The user of sasl_config. If sasl_config exists, it's required. |
-| brokers.sasl_config.password | string | True | | | The password of sasl_config. If sasl_config exists, it's required. |
-| kafka_topic | string | True | | | Target topic to push the logs for organisation. |
-| producer_type | string | False | async | ["async", "sync"] | Message sending mode of the producer. |
-| required_acks | integer | False | 1 | [1, -1] | Number of acknowledgements the leader needs to receive for the producer to consider the request complete. This controls the durability of the sent records. The attribute follows the same configuration as the Kafka `acks` attribute. `required_acks` cannot be 0. See [Apache Kafka documentation](https://kafka.apache.org/documentation/#producerconfigs_acks) for more. |
-| key | string | False | | | Key used for allocating partitions for messages. |
-| timeout | integer | False | 3 | [1,...] | Timeout for the upstream to send data. |
-| name | string | False | "kafka logger" | | Unique identifier for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. |
-| meta_format | enum | False | "default" | ["default"，"origin"] | Format to collect the request information. Setting to `default` collects the information in JSON format and `origin` collects the information with the original HTTP request. See [examples](#meta_format-example) below. |
-| log_format | object | False | | | Log format declared as key-value pairs in JSON. Values support strings and nested objects (up to five levels deep; deeper fields are truncated). Within strings, [APISIX](../apisix-variable.md) or [NGINX](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. |
-| include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. If the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitations. |
-| include_req_body_expr | array | False | | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. |
-| max_req_body_bytes | integer | False | 524288 | >=1 | Maximum request body allowed in bytes. Request bodies falling within this limit will be pushed to Kafka. If the size exceeds the configured value, the body will be truncated before being pushed to Kafka. |
-| include_resp_body | boolean | False | false | [false, true] | When set to `true` includes the response body in the log. |
-| include_resp_body_expr | array | False | | | Filter for when the `include_resp_body` attribute is set to `true`. Response body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. |
-| max_resp_body_bytes | integer | False | 524288 | >=1 | Maximum response body allowed in bytes. Response bodies falling within this limit will be pushed to Kafka. If the size exceeds the configured value, the body will be truncated before being pushed to Kafka. |
-| cluster_name | integer | False | 1 | [0,...] | Name of the cluster. Used when there are two or more Kafka clusters. Only works if the `producer_type` attribute is set to `async`. |
-| producer_batch_num | integer | optional | 200 | [1,...] | `batch_num` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka). The merge message and batch is send to the server. Unit is message count. |
-| producer_batch_size | integer | optional | 1048576 | [0,...] | `batch_size` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) in bytes. |
-| producer_max_buffering | integer | optional | 50000 | [1,...] | `max_buffering` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) representing maximum buffer size. Unit is message count. |
-| producer_time_linger | integer | optional | 1 | [1,...] | `flush_time` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) in seconds. |
-| meta_refresh_interval | integer | optional | 30 | [1,...] | `refresh_interval` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) specifies the time to auto refresh the metadata, in seconds. |
+| Name | Type | Required | Default | Valid values | Description |
+| -------------------------------- | ------- | -------- | -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| broker_list | object | False | | | Deprecated, use `brokers` instead. List of Kafka brokers (nodes). |
+| brokers | array | True | | | List of Kafka brokers (nodes). |
+| brokers.host | string | True | | | The host of Kafka broker, e.g. `192.168.1.1`. |
+| brokers.port | integer | True | | [0, 65535] | The port of Kafka broker. |
+| brokers.sasl_config | object | False | | | The SASL config of Kafka broker. |
+| brokers.sasl_config.mechanism | string | False | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | The mechanism of SASL config. |
+| brokers.sasl_config.user | string | True | | | The user of `sasl_config`. Required if `sasl_config` is configured. |
+| brokers.sasl_config.password | string | True | | | The password of `sasl_config`. Required if `sasl_config` is configured. |
+| kafka_topic | string | True | | | Target topic to push the logs. |
+| producer_type | string | False | async | ["async", "sync"] | Message sending mode of the producer. |
+| required_acks | integer | False | 1 | [1, -1] | Number of acknowledgements the leader needs to receive for the producer to consider the request complete. This controls the durability of the sent records. The attribute follows the same configuration as the Kafka `acks` attribute. `required_acks` cannot be 0. See [Apache Kafka documentation](https://kafka.apache.org/documentation/#producerconfigs_acks) for more. |
+| key | string | False | | | Key used for allocating partitions for messages. |
+| timeout | integer | False | 3 | [1,...] | Timeout in seconds for the upstream to send data. |
+| name | string | False | "kafka logger" | | Unique identifier for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. |
+| meta_format | enum | False | "default" | ["default","origin"] | Format to collect the request information. Setting to `default` collects the information in JSON format and `origin` collects the information with the original HTTP request. See [examples](#meta_format-example) below. |
+| log_format | object | False | | | Log format declared as key-value pairs in JSON. Values support strings and nested objects (up to five levels deep; deeper fields are truncated). Within strings, [APISIX](../apisix-variable.md) or [NGINX](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. |
+| include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. If the request body is too big to be kept in the memory, it can't be logged due to NGINX's limitations. |
+| include_req_body_expr | array | False | | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. |
+| max_req_body_bytes | integer | False | 524288 | >=1 | Maximum request body size in bytes to push to Kafka. If the size exceeds the configured value, the body will be truncated before being pushed. |
+| include_resp_body | boolean | False | false | [false, true] | When set to `true` includes the response body in the log. |
+| include_resp_body_expr | array | False | | | Filter for when the `include_resp_body` attribute is set to `true`. Response body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. |
+| max_resp_body_bytes | integer | False | 524288 | >=1 | Maximum response body size in bytes to push to Kafka. If the size exceeds the configured value, the body will be truncated before being pushed. |
+| cluster_name | integer | False | 1 | [0,...] | Name of the cluster. Used when there are two or more Kafka clusters. Only works if the `producer_type` attribute is set to `async`. |
Review Comment:
`cluster_name` valid values are documented as `[0,...]`, but the schema enforces `minimum = 1` (see `cluster_name = {type = "integer", minimum = 1, default = 1}`). Please update the valid range to start at 1 (e.g. `[1,...]` or `>= 1`).
```suggestion
| cluster_name | integer | False | 1 | [1,...] | Name of the cluster. Used when there are two or more Kafka clusters. Only works if the `producer_type` attribute is set to `async`. |
```
##########
docs/zh/latest/plugins/kafka-logger.md:
##########
@@ -27,123 +27,174 @@ description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/kafka-logger" />
+</head>
+
## 描述
-`kafka-logger` 插件用于将日志作为 JSON 对象推送到 Apache Kafka 集群中。可用作 `ngx_lua` NGINX 模块的 Kafka 客户端驱动程序。
+`kafka-logger` 插件将请求和响应日志作为 JSON 对象批量推送到 Apache Kafka 集群，并支持自定义日志格式。
+
+接收日志数据可能需要一些时间。数据将在 [批处理器](../batch-processor.md) 中的计时器函数到期后自动发送。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------------- | ------- | ------ | -------------- | --------------------- | ------------------------------------------------ |
-| broker_list | object | 是 | | | 已废弃，现使用 `brokers` 属性代替。原指需要推送的 Kafka 的 broker 列表。 |
-| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
-| brokers.host | string | 是 | | | Kafka broker 的节点 host 配置，例如 `192.168.1.1` |
-| brokers.port | string | 是 | | | Kafka broker 的节点端口配置 |
-| brokers.sasl_config | object | 否 | | | Kafka broker 中的 sasl_config |
-| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | Kafka broker 中的 sasl 认证机制 |
-| brokers.sasl_config.user | string | 是 | | | Kafka broker 中 sasl 配置中的 user，如果 sasl_config 存在，则必须填写 |
-| brokers.sasl_config.password | string | 是 | | | Kafka broker 中 sasl 配置中的 password，如果 sasl_config 存在，则必须填写 |
-| kafka_topic | string | 是 | | | 需要推送的 topic。 |
-| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
-| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的反馈信息的数量。该参数是为了保证发送请求的可靠性。该属性的配置与 Kafka `acks` 属性相同，具体配置请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。required_acks 还不支持为 0。 |
-| key | string | 否 | | | 用于消息分区而分配的密钥。 |
-| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 |
-| name | string | 否 | "kafka logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 |
-| meta_format | enum | 否 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。更多信息，请参考 [meta_format](#meta_format-示例)。|
-| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
-| include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。|
-| include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
-| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大请求正文（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 |
-| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时才会记录响应体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。|
-| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大响应正文（以字节为单位）。低于此限制的响应主体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| cluster_name | integer | 否 | 1 | [0,...] | Kafka 集群的名称，当有两个及以上 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,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数，单位为字节。 |
-| producer_max_buffering | integer | 否 | 50000 | [1,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数，表示最大缓冲区，单位为条。 |
-| 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` 参数，用于指定自动刷新 metadata 的间隔时长，单位为秒。 |
-
-该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
-
-:::tip 提示
-
-数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，则会将数据发送到 Kafka 服务器并刷新缓冲区。
+| 名称 | 类型 | 是否必需 | 默认值 | 有效值 | 描述 |
+| -------------------------------- | ------- | -------- | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| broker_list | object | 否 | | | 已废弃，请改用 `brokers` 属性。原指需要推送的 Kafka 的 broker 列表。 |
+| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
+| brokers.host | string | 是 | | | Kafka broker 的节点地址，例如 `192.168.1.1`。 |
+| brokers.port | integer | 是 | | [0, 65535] | Kafka broker 的节点端口。 |
+| brokers.sasl_config | object | 否 | | | Kafka broker 的 SASL 配置。 |
+| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | SASL 认证机制。 |
+| brokers.sasl_config.user | string | 是 | | | SASL 配置中的用户名。如果配置了 `sasl_config`，则必须填写。 |
+| brokers.sasl_config.password | string | 是 | | | SASL 配置中的密码。如果配置了 `sasl_config`，则必须填写。 |
+| kafka_topic | string | 是 | | | 用于推送日志的目标 topic。 |
+| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
+| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的确认信息数量，用于保证发送请求的可靠性。该属性与 Kafka 的 `acks` 属性配置相同，`required_acks` 不能为 0。详情请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。 |
+| key | string | 否 | | | 用于消息分区的键。 |
+| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间（秒）。 |
+| name | string | 否 | "kafka logger" | | 批处理器的唯一标识符。如果使用 Prometheus 监控 APISIX 指标，该名称将以 `apisix_batch_process_entries` 导出。 |
+| meta_format | enum | 否 | "default" | ["default","origin"] | 收集请求信息的格式。设置为 `default` 时以 JSON 格式收集信息，设置为 `origin` 时以 HTTP 原始请求格式收集信息。详情请参考下方 [示例](#meta_format-示例)。 |
+| log_format | object | 否 | | | 以 JSON 键值对声明的日志格式。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
+| include_req_body | boolean | 否 | false | [false, true] | 设置为 `true` 时，在日志中包含请求体。**注意**：如果请求体过大无法完全存放在内存中，由于 NGINX 的限制，将无法记录。 |
+| include_req_body_expr | array | 否 | | | 当 `include_req_body` 设置为 `true` 时的过滤条件。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。详情请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
+| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许推送到 Kafka 的最大请求体大小（字节）。如果超过该值，请求体在推送前会被截断。 |
+| include_resp_body | boolean | 否 | false | [false, true] | 设置为 `true` 时，在日志中包含响应体。 |
+| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 设置为 `true` 时的过滤条件。只有当此处设置的表达式计算结果为 `true` 时，才会记录响应体。详情请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
+| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许推送到 Kafka 的最大响应体大小（字节）。如果超过该值，响应体在推送前会被截断。 |
+| cluster_name | integer | 否 | 1 | [0,...] | Kafka 集群的名称，在有两个或多个 Kafka 集群时使用。仅当 `producer_type` 设置为 `async` 时有效。 |
Review Comment:
`cluster_name` 的有效值写为 `[0,...]`，但插件 schema 中该字段 `minimum = 1`。请将有效范围改为从 1 开始（例如 `[1,...]` 或 `>= 1`），避免与实际校验不一致。
```suggestion
| cluster_name | integer | 否 | 1 | [1,...] | Kafka 集群的名称，在有两个或多个 Kafka 集群时使用。仅当 `producer_type` 设置为 `async` 时有效。 |
```
##########
docs/en/latest/plugins/kafka-logger.md:
##########
@@ -27,44 +27,48 @@ description: This document contains information about the Apache APISIX kafka-lo
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/kafka-logger" />
+</head>
+
## Description
-The `kafka-logger` Plugin is used to push logs as JSON objects to Apache Kafka clusters. It works as a Kafka client driver for the ngx_lua Nginx module.
+The `kafka-logger` Plugin pushes request and response logs as JSON objects to Apache Kafka clusters in batches and supports the customization of log formats.
It might take some time to receive the log data. It will be automatically sent after the timer function in the [batch processor](../batch-processor.md) expires.
## Attributes
-| Name | Type | Required | Default | Valid values | Description |
-| ---------------------- | ------- | -------- | -------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| broker_list | object | True | | | Deprecated, use `brokers` instead. List of Kafka brokers. (nodes). |
-| brokers | array | True | | | List of Kafka brokers (nodes). |
-| brokers.host | string | True | | | The host of Kafka broker, e.g, `192.168.1.1`. |
-| brokers.port | integer | True | | [0, 65535] | The port of Kafka broker |
-| brokers.sasl_config | object | False | | | The sasl config of Kafka broker |
-| brokers.sasl_config.mechanism | string | False | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | The mechaism of sasl config |
-| brokers.sasl_config.user | string | True | | | The user of sasl_config. If sasl_config exists, it's required. |
-| brokers.sasl_config.password | string | True | | | The password of sasl_config. If sasl_config exists, it's required. |
-| kafka_topic | string | True | | | Target topic to push the logs for organisation. |
-| producer_type | string | False | async | ["async", "sync"] | Message sending mode of the producer. |
-| required_acks | integer | False | 1 | [1, -1] | Number of acknowledgements the leader needs to receive for the producer to consider the request complete. This controls the durability of the sent records. The attribute follows the same configuration as the Kafka `acks` attribute. `required_acks` cannot be 0. See [Apache Kafka documentation](https://kafka.apache.org/documentation/#producerconfigs_acks) for more. |
-| key | string | False | | | Key used for allocating partitions for messages. |
-| timeout | integer | False | 3 | [1,...] | Timeout for the upstream to send data. |
-| name | string | False | "kafka logger" | | Unique identifier for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. |
-| meta_format | enum | False | "default" | ["default"，"origin"] | Format to collect the request information. Setting to `default` collects the information in JSON format and `origin` collects the information with the original HTTP request. See [examples](#meta_format-example) below. |
-| log_format | object | False | | | Log format declared as key-value pairs in JSON. Values support strings and nested objects (up to five levels deep; deeper fields are truncated). Within strings, [APISIX](../apisix-variable.md) or [NGINX](http://nginx.org/en/docs/varindex.html) variables can be referenced by prefixing with `$`. |
-| include_req_body | boolean | False | false | [false, true] | When set to `true` includes the request body in the log. If the request body is too big to be kept in the memory, it can't be logged due to Nginx's limitations. |
-| include_req_body_expr | array | False | | | Filter for when the `include_req_body` attribute is set to `true`. Request body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. |
-| max_req_body_bytes | integer | False | 524288 | >=1 | Maximum request body allowed in bytes. Request bodies falling within this limit will be pushed to Kafka. If the size exceeds the configured value, the body will be truncated before being pushed to Kafka. |
-| include_resp_body | boolean | False | false | [false, true] | When set to `true` includes the response body in the log. |
-| include_resp_body_expr | array | False | | | Filter for when the `include_resp_body` attribute is set to `true`. Response body is only logged when the expression set here evaluates to `true`. See [lua-resty-expr](https://github.com/api7/lua-resty-expr) for more. |
-| max_resp_body_bytes | integer | False | 524288 | >=1 | Maximum response body allowed in bytes. Response bodies falling within this limit will be pushed to Kafka. If the size exceeds the configured value, the body will be truncated before being pushed to Kafka. |
-| cluster_name | integer | False | 1 | [0,...] | Name of the cluster. Used when there are two or more Kafka clusters. Only works if the `producer_type` attribute is set to `async`. |
-| producer_batch_num | integer | optional | 200 | [1,...] | `batch_num` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka). The merge message and batch is send to the server. Unit is message count. |
-| producer_batch_size | integer | optional | 1048576 | [0,...] | `batch_size` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) in bytes. |
-| producer_max_buffering | integer | optional | 50000 | [1,...] | `max_buffering` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) representing maximum buffer size. Unit is message count. |
-| producer_time_linger | integer | optional | 1 | [1,...] | `flush_time` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) in seconds. |
-| meta_refresh_interval | integer | optional | 30 | [1,...] | `refresh_interval` parameter in [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) specifies the time to auto refresh the metadata, in seconds. |
+| Name | Type | Required | Default | Valid values | Description |
+| -------------------------------- | ------- | -------- | -------------- | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| broker_list | object | False | | | Deprecated, use `brokers` instead. List of Kafka brokers (nodes). |
+| brokers | array | True | | | List of Kafka brokers (nodes). |
+| brokers.host | string | True | | | The host of Kafka broker, e.g. `192.168.1.1`. |
+| brokers.port | integer | True | | [0, 65535] | The port of Kafka broker. |
Review Comment:
`brokers.port` is documented as allowing `[0, 65535]`, but the plugin schema enforces `minimum = 1` (port 0 is invalid). Please update the valid range to `[1, 65535]` to match actual validation.
```suggestion
| brokers.port | integer | True | | [1, 65535] | The port of Kafka broker. |
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] docs: update kafka-logger plugin documentation [apisix]
Posted by "LiteSun (via GitHub)" <gi...@apache.org>.
LiteSun commented on code in PR #13278:
URL: https://github.com/apache/apisix/pull/13278#discussion_r3157977874
##########
docs/zh/latest/plugins/kafka-logger.md:
##########
@@ -27,224 +27,460 @@ description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作
#
-->
+<head>
+ <link rel="canonical" href="https://docs.api7.ai/hub/kafka-logger" />
+</head>
+
## 描述
-`kafka-logger` 插件用于将日志作为 JSON 对象推送到 Apache Kafka 集群中。可用作 `ngx_lua` NGINX 模块的 Kafka 客户端驱动程序。
+`kafka-logger` 插件将请求和响应日志作为 JSON 对象批量推送到 Apache Kafka 集群，并支持自定义日志格式。
+
+接收日志数据可能需要一些时间。数据将在 [批处理器](../batch-processor.md) 中的计时器函数到期后自动发送。
## 属性
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------------- | ------- | ------ | -------------- | --------------------- | ------------------------------------------------ |
-| broker_list | object | 是 | | | 已废弃，现使用 `brokers` 属性代替。原指需要推送的 Kafka 的 broker 列表。 |
-| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
-| brokers.host | string | 是 | | | Kafka broker 的节点 host 配置，例如 `192.168.1.1` |
-| brokers.port | string | 是 | | | Kafka broker 的节点端口配置 |
-| brokers.sasl_config | object | 否 | | | Kafka broker 中的 sasl_config |
-| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | Kafka broker 中的 sasl 认证机制 |
-| brokers.sasl_config.user | string | 是 | | | Kafka broker 中 sasl 配置中的 user，如果 sasl_config 存在，则必须填写 |
-| brokers.sasl_config.password | string | 是 | | | Kafka broker 中 sasl 配置中的 password，如果 sasl_config 存在，则必须填写 |
-| kafka_topic | string | 是 | | | 需要推送的 topic。 |
-| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
-| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的反馈信息的数量。该参数是为了保证发送请求的可靠性。该属性的配置与 Kafka `acks` 属性相同，具体配置请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。required_acks 还不支持为 0。 |
-| key | string | 否 | | | 用于消息分区而分配的密钥。 |
-| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 |
-| name | string | 否 | "kafka logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 |
-| meta_format | enum | 否 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。更多信息，请参考 [meta_format](#meta_format-示例)。|
-| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
-| include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。|
-| include_req_body_expr | array | 否 | | | 当 `include_req_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
-| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大请求正文（以字节为单位）。在此限制内的请求体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| include_resp_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时，包含响应体。 |
-| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 属性设置为 `true` 时进行过滤。只有当此处设置的表达式计算结果为 `true` 时才会记录响应体。更多信息，请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。|
-| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许的最大响应正文（以字节为单位）。低于此限制的响应主体将被推送到 Kafka。如果大小超过配置值，则正文在推送到 Kafka 之前将被截断。 |
-| cluster_name | integer | 否 | 1 | [0,...] | Kafka 集群的名称，当有两个及以上 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,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数，单位为字节。 |
-| producer_max_buffering | integer | 否 | 50000 | [1,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数，表示最大缓冲区，单位为条。 |
-| 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` 参数，用于指定自动刷新 metadata 的间隔时长，单位为秒。 |
-
-该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
-
-:::tip 提示
-
-数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，则会将数据发送到 Kafka 服务器并刷新缓冲区。
+| 名称 | 类型 | 是否必需 | 默认值 | 有效值 | 描述 |
+| -------------------------------- | ------- | -------- | --------------- | ------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| broker_list | object | 否 | | | 已废弃，请改用 `brokers` 属性。原指需要推送的 Kafka 的 broker 列表。 |
+| brokers | array | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
+| brokers.host | string | 是 | | | Kafka broker 的节点地址，例如 `192.168.1.1`。 |
+| brokers.port | integer | 是 | | [1, 65535] | Kafka broker 的节点端口。 |
+| brokers.sasl_config | object | 否 | | | Kafka broker 的 SASL 配置。 |
+| brokers.sasl_config.mechanism | string | 否 | "PLAIN" | ["PLAIN", "SCRAM-SHA-256", "SCRAM-SHA-512"] | SASL 认证机制。 |
+| brokers.sasl_config.user | string | 是 | | | SASL 配置中的用户名。如果配置了 `sasl_config`，则必须填写。 |
+| brokers.sasl_config.password | string | 是 | | | SASL 配置中的密码。如果配置了 `sasl_config`，则必须填写。 |
+| kafka_topic | string | 是 | | | 用于推送日志的目标 topic。 |
+| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
+| required_acks | integer | 否 | 1 | [1, -1] | 生产者在确认一个请求发送完成之前需要收到的确认信息数量，用于保证发送请求的可靠性。该属性与 Kafka 的 `acks` 属性配置相同，`required_acks` 不能为 0。详情请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。 |
+| key | string | 否 | | | 用于消息分区的键。 |
+| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间（秒）。 |
+| name | string | 否 | "kafka logger" | | 批处理器的唯一标识符。如果使用 Prometheus 监控 APISIX 指标，该名称将以 `apisix_batch_process_entries` 导出。 |
+| meta_format | enum | 否 | "default" | ["default","origin"] | 收集请求信息的格式。设置为 `default` 时以 JSON 格式收集信息，设置为 `origin` 时以 HTTP 原始请求格式收集信息。详情请参考下方 [示例](#meta_format-示例)。 |
+| log_format | object | 否 | | | 以 JSON 键值对声明的日志格式。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
+| include_req_body | boolean | 否 | false | [false, true] | 设置为 `true` 时，在日志中包含请求体。**注意**：如果请求体过大无法完全存放在内存中，由于 NGINX 的限制，将无法记录。 |
+| include_req_body_expr | array | 否 | | | 当 `include_req_body` 设置为 `true` 时的过滤条件。只有当此处设置的表达式计算结果为 `true` 时，才会记录请求体。详情请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
+| max_req_body_bytes | integer | 否 | 524288 | >=1 | 允许推送到 Kafka 的最大请求体大小（字节）。如果超过该值，请求体在推送前会被截断。 |
+| include_resp_body | boolean | 否 | false | [false, true] | 设置为 `true` 时，在日志中包含响应体。 |
+| include_resp_body_expr | array | 否 | | | 当 `include_resp_body` 设置为 `true` 时的过滤条件。只有当此处设置的表达式计算结果为 `true` 时，才会记录响应体。详情请参考 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 |
+| max_resp_body_bytes | integer | 否 | 524288 | >=1 | 允许推送到 Kafka 的最大响应体大小（字节）。如果超过该值，响应体在推送前会被截断。 |
+| cluster_name | integer | 否 | 1 | [1,...] | Kafka 集群的名称，在有两个或多个 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,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `batch_size` 参数，单位为字节。 |
+| producer_max_buffering | integer | 否 | 50000 | [1,...] | 对应 [lua-resty-kafka](https://github.com/doujiang24/lua-resty-kafka) 中的 `max_buffering` 参数，表示最大缓冲区大小，单位为条。 |
+| 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` 参数，用于指定自动刷新 metadata 的间隔时长，单位为秒。 |
+
+该插件支持使用批处理器来聚合并批量处理条目（日志/数据），避免频繁提交数据。默认情况下，批处理器每 `5` 秒或队列中的数据达到 `1000` 条时提交数据。如需了解批处理器相关参数设置，请参考[批处理器](../batch-processor.md#配置)配置部分。
+
+:::info 重要
+
+数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，数据将发送到 Kafka 服务器并刷新缓冲区。
如果发送成功，则返回 `true`。如果出现错误，则返回 `nil`，并带有描述错误的字符串 `buffer overflow`。
:::
### meta_format 示例
-- `default`:
-
- ```json
- {
- "upstream": "127.0.0.1:1980",
- "start_time": 1619414294760,
- "client_ip": "127.0.0.1",
- "service_id": "",
- "route_id": "1",
- "request": {
- "querystring": {
- "ab": "cd"
- },
- "size": 90,
- "uri": "/hello?ab=cd",
- "url": "http://localhost:1984/hello?ab=cd",
- "headers": {
- "host": "localhost",
- "content-length": "6",
- "connection": "close"
- },
- "body": "abcdef",
- "method": "GET"
- },
- "response": {
- "headers": {
- "connection": "close",
- "content-type": "text/plain; charset=utf-8",
- "date": "Mon, 26 Apr 2021 05:18:14 GMT",
- "server": "APISIX/2.5",
- "transfer-encoding": "chunked"
- },
- "size": 190,
- "status": 200
- },
- "server": {
- "hostname": "localhost",
- "version": "2.5"
- },
- "latency": 0
- }
- ```
+- `default`：
Review Comment:
typo?
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org