You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by sy...@apache.org on 2022/08/23 01:23:31 UTC
[apisix] branch master updated: docs: refactor kafka-logger plugin doc (#7662)
This is an automated email from the ASF dual-hosted git repository.
sylviasu pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/apisix.git
The following commit(s) were added to refs/heads/master by this push:
new 96f1adb1c docs: refactor kafka-logger plugin doc (#7662)
96f1adb1c is described below
commit 96f1adb1c6aa51658aa4fa2fe4213ded8690a254
Author: Fei Han <97...@users.noreply.github.com>
AuthorDate: Tue Aug 23 09:23:24 2022 +0800
docs: refactor kafka-logger plugin doc (#7662)
* docs: refactor kafka-logger plugin doc
* Update docs/zh/latest/plugins/kafka-logger.md
Co-authored-by: Sylvia <39...@users.noreply.github.com>
Co-authored-by: hf400159 <hf...@163.com>
Co-authored-by: Sylvia <39...@users.noreply.github.com>
---
docs/zh/latest/plugins/kafka-logger.md | 156 +++++++++++++++++----------------
1 file changed, 80 insertions(+), 76 deletions(-)
diff --git a/docs/zh/latest/plugins/kafka-logger.md b/docs/zh/latest/plugins/kafka-logger.md
index 302b273f3..84bc505d4 100644
--- a/docs/zh/latest/plugins/kafka-logger.md
+++ b/docs/zh/latest/plugins/kafka-logger.md
@@ -1,5 +1,11 @@
---
title: kafka-logger
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - Kafka Logger
+description: API 网关 Apache APISIX 的 kafka-logger 插件用于将日志作为 JSON 对象推送到 Apache Kafka 集群中。
---
<!--
@@ -23,40 +29,43 @@ title: kafka-logger
## 描述
-`kafka-logger` 是一个插件，可用作 ngx_lua nginx 模块的 Kafka 客户端驱动程序。
+`kafka-logger` 插件用于将日志作为 JSON 对象推送到 Apache Kafka 集群中。可用作 `ngx_lua` NGINX 模块的 Kafka 客户端驱动程序。
-它可以将接口请求日志以 JSON 的形式推送给外部 Kafka 集群。如果在短时间内没有收到日志数据，请放心，它会在我们的批处理处理器中的计时器功能到期后自动发送日志。
+## 属性
-有关 Apache APISIX 中 Batch-Processor 的更多信息，请参考。
-[Batch-Processor](../batch-processor.md)
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+| ---------------------- | ------- | ------ | -------------- | --------------------- | ------------------------------------------------ |
+| broker_list | object | 是 | | | 需要推送的 Kafka 的 broker 列表。 |
+| kafka_topic | string | 是 | | | 需要推送的 topic。 |
+| producer_type | string | 否 | async | ["async", "sync"] | 生产者发送消息的模式。 |
+| required_acks | integer | 否 | 1 | [0, 1, -1] | 生产者在确认一个请求发送完成之前需要收到的反馈信息的数量。该参数是为了保证发送请求的可靠性。该属性的配置与 Kafka `acks` 属性相同，具体配置请参考 [Apache Kafka 文档](https://kafka.apache.org/documentation/#producerconfigs_acks)。 |
+| key | string | 否 | | | 用于消息分区而分配的密钥。 |
+| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 |
+| name | string | 否 | "kafka logger" | | batch processor 的唯一标识。 |
+| meta_format | enum | 否 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。更多信息，请参考 [meta_format](#meta_format-参考示例)。|
+| 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)。 |
+| 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)。|
+| 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` 参数，单位为秒。|
-## 属性
+该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
+
+:::tip 提示
+
+数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，则会将数据发送到 Kafka 服务器并刷新缓冲区。
+
+如果发送成功，则返回 `true`。如果出现错误，则返回 `nil`，并带有描述错误的字符串 `buffer overflow`。
+
+:::
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------- | ------- | ------ | -------------- | ------- | ------------------------------------------------ |
-| broker_list | object | 必须 | | | 要推送的 kafka 的 broker 列表。 |
-| kafka_topic | string | 必须 | | | 要推送的 topic。 |
-| producer_type | string | 可选 | async | ["async", "sync"] | 生产者发送消息的模式。 |
-| required_acks | integer | 可选 | 1 | [0, 1, -1] | 生产者在确认一个请求发送完成之前需要收到的反馈信息的数量。这个参数是为了保证发送请求的可靠性。语义同 kafka 生产者的 acks 参数（如果设置 `acks=0`，则 producer 不会等待服务器的反馈。该消息会被立刻添加到 socket buffer 中并认为已经发送完成。如果设置 `acks=1`，leader 节点会将记录写入本地日志，并且在所有 follower 节点反馈之前就先确认成功。如果设置 `acks=-1`，这就意味着 leader 节点会等待所有同步中的副本确认之后再确认这条记录是否发送完成。）。 |
-| key | string | 可选 | | | 用于消息的分区分配。 |
-| timeout | integer | 可选 | 3 | [1,...] | 发送数据的超时时间。 |
-| name | string | 可选 | "kafka logger" | | batch processor 的唯一标识。 |
-| meta_format | enum | 可选 | "default" | ["default"，"origin"] | `default`：获取请求信息以默认的 JSON 编码方式。`origin`：获取请求信息以 HTTP 原始请求方式。[具体示例](#meta_format-参考示例)|
-| include_req_body | boolean | 可选 | false | [false, true] | 是否包括请求 body。false： 表示不包含请求的 body ；true： 表示包含请求的 body。注意：如果请求 body 没办法完全放在内存中，由于 Nginx 的限制，我们没有办法把它记录下来。|
-| include_req_body_expr | array | 可选 | | | 当 `include_req_body` 开启时，基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式的结果进行记录。如果该选项存在，只有在表达式为真的时候才会记录请求 body。 |
-| include_resp_body| boolean | 可选 | false | [false, true] | 是否包括响应体。包含响应体，当为`true`。 |
-| include_resp_body_expr | array | 可选 | | | 是否采集响体，基于 [lua-resty-expr](https://github.com/api7/lua-resty-expr)。 该选项需要开启 `include_resp_body`|
-| 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`参数，单位为秒 |
-
-本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
-
-### meta_format 参考示例
-
-- **default**:
+### meta_format 示例
+
+- `default`:
```json
{
@@ -99,7 +108,7 @@ title: kafka-logger
}
```
-- **origin**:
+- `origin`:
```http
GET /hello?ab=cd HTTP/1.1
@@ -110,32 +119,46 @@ title: kafka-logger
abcdef
```
-## 工作原理
+## 插件元数据
-消息将首先写入缓冲区。
-当缓冲区超过 `batch_max_size` 时，它将发送到 kafka 服务器，
-或每个 `buffer_duration` 刷新缓冲区。
+| 名称 | 类型 | 必选项 | 默认值 | 描述 |
+| ---------------- | ------- | ------ | ------------- |------------------------------------------------ |
+| log_format | object | 否 | {"host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr"} | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
-如果成功，则返回 `true`。
-如果出现错误，则返回 `nil`，并带有描述错误的字符串（`buffer overflow`）。
+:::note 注意
-### Broker 列表
+该设置全局生效。如果指定了 `log_format`，则所有绑定 `kafka-logger` 的路由或服务都将使用该日志格式。
-插件支持一次推送到多个 Broker，如下配置：
+:::
-```json
+以下示例展示了如何通过 Admin API 配置插件元数据：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/kafka-logger \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
- "127.0.0.1":9092,
- "127.0.0.1":9093
-}
+ "log_format": {
+ "host": "$host",
+ "@timestamp": "$time_iso8601",
+ "client_ip": "$remote_addr"
+ }
+}'
+```
+
+配置完成后，你将在日志系统中看到如下类似日志：
+
+```shell
+{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}
+{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}
```
## 如何启用
-1. 为特定路由启用 kafka-logger 插件。
+你可以通过如下命令在指定路由上启用 `kafka-logger` 插件：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"kafka-logger": {
@@ -157,49 +180,30 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-## 测试插件
-
- 成功
-
-```shell
-$ curl -i http://127.0.0.1:9080/hello
-HTTP/1.1 200 OK
-...
-hello, world
-```
-
-## 插件元数据设置
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ |
-| log_format | object | 可选 | {"host": "$host", "@timestamp": "$time_iso8601", "client_ip": "$remote_addr"} | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [Nginx 内置变量](http://nginx.org/en/docs/varindex.html)。请注意，**该设置是全局生效的**，因此在指定 log_format 后，将对所有绑定 kafka-logger 的 Route 或 Service 生效。 |
-
-### 设置日志格式示例
+该插件还支持一次推送到多个 Broker，示例如下：
-```shell
-curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/kafka-logger -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+```json
{
- "log_format": {
- "host": "$host",
- "@timestamp": "$time_iso8601",
- "client_ip": "$remote_addr"
- }
-}'
+ "127.0.0.1":9092,
+ "127.0.0.1":9093
+}
```
-在日志收集处，将得到类似下面的日志：
+## 测试插件
+
+你可以通过以下命令向 APISIX 发出请求：
```shell
-{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}
-{"host":"localhost","@timestamp":"2020-09-23T19:05:05-04:00","client_ip":"127.0.0.1","route_id":"1"}
+curl -i http://127.0.0.1:9080/hello
```
## 禁用插件
-当您要禁用 `kafka-logger` 插件时，这很简单，您可以在插件配置中删除相应的 json 配置，无需重新启动服务，它将立即生效：
+当你需要禁用该插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
```shell
-$ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"methods": ["GET"],
"uri": "/hello",