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: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
