Copilot commented on code in PR #13272: URL: https://github.com/apache/apisix/pull/13272#discussion_r3122030683
########## docs/en/latest/plugins/clickhouse-logger.md: ########## @@ -127,86 +93,168 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Log in the Default Log Format + +The following example demonstrates how to log requests in the default log format. + +Create a table named `default_logs` in your ClickHouse database with columns corresponding to the default log format: + ```shell -curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/clickhouse-logger -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "log_format": { - "host": "$host", - "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" +curl "http://127.0.0.1:8123"; -X POST -d ' + CREATE TABLE default.default_logs ( + host String, + client_ip String, + route_id String, + service_id String, + start_time String, + latency String, + upstream_latency String, + apisix_latency String, + consumer String, + request String, + response String, + server String, + PRIMARY KEY(`start_time`) + ) + ENGINE = MergeTree() Review Comment: The ClickHouse `CREATE TABLE ... ENGINE = MergeTree()` examples are missing an `ORDER BY` clause. For `MergeTree`, `ORDER BY` is required (and `PRIMARY KEY` is optional / defaults to the sorting key). Please add an explicit `ORDER BY` (for example, `ORDER BY (start_time)`) so the example can be executed successfully. ```suggestion server String ) ENGINE = MergeTree() PRIMARY KEY (`start_time`) ORDER BY (`start_time`) ``` ########## docs/zh/latest/plugins/splunk-hec-logging.md: ########## @@ -28,71 +28,63 @@ description: API 网关 Apache APISIX 的 splunk-hec-logging 插件可用于将 # --> -## 描述 +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/splunk-hec-logging"; /> +</head> -`splunk-hec-logging` 插件可用于将请求日志转发到 Splunk HTTP 事件收集器（HEC）中进行分析和存储。 +## 描述 -启用该插件后，APISIX 将在 `Log Phase` 获取请求上下文信息，并将其序列化为 [Splunk Event Data 格式](https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata) 后提交到批处理队列中，当触发批处理队列每批次最大处理容量或刷新缓冲区的最大时间时会将队列中的数据提交到 `Splunk HEC` 中。 +`splunk-hec-logging` 插件将请求和响应上下文信息序列化为 [Splunk Event Data 格式](https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata)并批量推送到 [Splunk HTTP Event Collector（HEC）](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector)。该插件还支持自定义日志格式。 ## 属性 -| 名称 | 必选项 | 默认值 | 描述 | -| ------------------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| endpoint | 是 | | Splunk HEC 端点配置信息。 | -| endpoint.uri | 是 | | Splunk HEC 事件收集 API。 | -| endpoint.token | 是 | | Splunk HEC 身份令牌。 | -| endpoint.channel | 否 | | Splunk HEC 发送渠道标识，更多信息请参考 [About HTTP Event Collector Indexer Acknowledgment](https://docs.splunk.com/Documentation/Splunk/8.2.3/Data/AboutHECIDXAck)。 | -| endpoint.timeout | 否 | 10 | Splunk HEC 数据提交超时时间（以秒为单位）。 | -| ssl_verify | 否 | true | 当设置为 `true` 时，启用 `SSL` 验证。 | -| log_format | 否 | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|----------------------------|---------|--------|--------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| endpoint | object | True | | | Splunk HEC endpoint 配置。 | +| endpoint.uri | string | True | | | Splunk HEC 事件收集器 API 端点。 | +| endpoint.token | string | True | | | Splunk HEC 鉴权 token。 | +| endpoint.channel | string | False | | | Splunk HEC 发送数据通道标识符。详情参见 [About HTTP Event Collector Indexer Acknowledgment](https://docs.splunk.com/Documentation/Splunk/latest/Data/AboutHECIDXAck)。 | +| endpoint.timeout | integer | False | 10 | | Splunk HEC 发送数据超时时间（秒）。 | +| endpoint.keepalive_timeout | integer | False | 60000 | >= 1000 | 保持连接的超时时间（毫秒）。 | +| ssl_verify | boolean | False | true | | 若为 `true`，则按照 [OpenResty 文档](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) 启用 SSL 验证。 | +| log_format | object | False | | | 以 JSON 键值对形式声明的自定义日志格式。值可通过 `$` 前缀引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。也可通过[插件元数据](#插件元数据)全局配置日志格式。 | +| name | string | False | splunk-hec-logging | | 批处理器中插件的唯一标识符。 | +| batch_max_size | integer | False | 1000 | 大于 0 | 单批允许的日志条目数。达到此数量后，批次将被发送至 Splunk HEC。设置为 `1` 表示立即处理。 | +| inactive_timeout | integer | False | 5 | 大于 0 | 在发送批次到日志服务之前等待新日志的最长时间（秒）。该值应小于 `buffer_duration`。 | +| buffer_duration | integer | False | 60 | 大于 0 | 在发送批次到日志服务之前，允许最早条目存在的最长时间（秒）。 | +| retry_delay | integer | False | 1 | >= 0 | 批次发送失败后重试的时间间隔（秒）。 | +| max_retry_count | integer | False | 60 | >= 0 | 在丢弃日志条目之前允许的最大重试次数。 | + +该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认情况下批处理器每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据。如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置)。 -本插件支持使用批处理器来聚合并批量处理条目（日志和数据）。这样可以避免该插件频繁地提交数据。默认情况下每 `5` 秒钟或队列中的数据达到 `1000` 条时，批处理器会自动提交数据，如需了解更多信息或自定义配置，请参考 [Batch-Processor](../batch-processor.md#配置)。 +## 插件元数据 -### 默认日志格式示例 +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|--------------------|---------|--------|--------|--------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| log_format | object | False | | | 以 JSON 键值对形式声明的自定义日志格式。值可通过 `$` 前缀引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。该配置全局生效，对所有绑定 `splunk-hec-logging` 的路由和服务生效。 | +| max_pending_entries | integer | False | | >= 1 | 批处理器中允许的最大未处理条目数。达到此限制后，新条目将被丢弃，直到积压减少。 | -```json -{ - "sourcetype": "_json", - "time": 1704513555.392, - "event": { - "upstream": "127.0.0.1:1980", - "request_url": "http://localhost:1984/hello";, - "request_query": {}, - "request_size": 59, - "response_headers": { - "content-length": "12", - "server": "APISIX/3.7.0", - "content-type": "text/plain", - "connection": "close" - }, - "response_status": 200, - "response_size": 118, - "latency": 108.00004005432, - "request_method": "GET", - "request_headers": { - "connection": "close", - "host": "localhost" - } - }, - "source": "apache-apisix-splunk-hec-logging", - "host": "localhost" -} -``` +## 示例 -## 插件元数据 +以下示例演示了如何为不同场景配置 `splunk-hec-logging` 插件。 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ | -| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | -| max_pending_entries | integer | 否 | | | 在批处理器中开始删除待处理条目之前可以购买的最大待处理条目数。| +按照示例操作，请先完成以下步骤设置 Splunk： -:::info 注意 +* 安装 [Splunk](https://www.splunk.com/en_us/download.html)。Splunk Web 默认运行在 `localhost:8000`。 +* 参见[在 Splunk Web 中设置和使用 HTTP Event Collector](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) 来设置 HTTP Event Collector。 +* 在控制台右上角导航至 **Settings > Data Inputs**，您应该看到 HTTP Event Collector 中至少有一条 input。记录下 token 值。 +* 在控制台右上角导航至 **Settings > Data Inputs** 并选择 **HTTP Event Collector**。在 **Global Settings** 中启用所有 tokens。 +* 在 **Global Settings** 中，您还可以找到收集器的默认端口为 `8088`。 -该设置全局生效。如果指定了 `log_format`，则所有绑定 `splunk-hec-logging` 的路由或服务都将使用该日志格式。 +通过以下命令验证设置（替换为您的 token）： -::: +```shell +curl "http://localhost:8088/services/collector/event"; \ Review Comment: Splunk 验证命令的续行反斜杠后多了一个空格（`\ `），会导致部分 shell 无法正确续行执行。建议删除反斜杠后的空格以确保命令可复制运行。 ```suggestion curl "http://localhost:8088/services/collector/event"; \ ``` ########## docs/en/latest/plugins/clickhouse-logger.md: ########## @@ -127,86 +93,168 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### Log in the Default Log Format + +The following example demonstrates how to log requests in the default log format. + +Create a table named `default_logs` in your ClickHouse database with columns corresponding to the default log format: + ```shell -curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/clickhouse-logger -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "log_format": { - "host": "$host", - "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" +curl "http://127.0.0.1:8123"; -X POST -d ' + CREATE TABLE default.default_logs ( + host String, + client_ip String, + route_id String, + service_id String, + start_time String, + latency String, + upstream_latency String, + apisix_latency String, + consumer String, + request String, + response String, + server String, + PRIMARY KEY(`start_time`) + ) + ENGINE = MergeTree() +' --user default: +``` + +Create a Route with the `clickhouse-logger` Plugin: + +```shell +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "clickhouse-logger-route", + "uri": "/get", + "plugins": { + "clickhouse-logger": { + "user": "default", + "password": "", + "database": "default", + "logtable": "default_logs", + "endpoint_addrs": ["http://127.0.0.1:8123";] + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } } -}' + }' ``` -You can use the clickhouse docker image to create a container like so: +Send a request to the Route to generate a log entry: ```shell -docker run -d -p 8123:8123 -p 9000:9000 -p 9009:9009 --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server +curl -i "http://127.0.0.1:9080/get"; ``` -Then create a table in your ClickHouse database to store the logs. +You should see an `HTTP/1.1 200 OK` response. + +Send a request to ClickHouse to see the log entries: ```shell -curl -X POST 'http://localhost:8123/' \ ---data-binary 'CREATE TABLE default.test (host String, client_ip String, route_id String, service_id String, `@timestamp` String, PRIMARY KEY(`@timestamp`)) ENGINE = MergeTree()' --user default: +echo 'SELECT * FROM default.default_logs FORMAT Pretty' | curl "http://127.0.0.1:8123/?"; -d @- +``` + +You should see a log entry similar to the following: + +```text + +┏━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓ +┃ host ┃ client_ip ┃ route_id ┃ service_id ┃ start_time ┃ latency ┃ upstream_latency ┃ apisix_latency ┃ consumer ┃ request ┃ response ┃ server ┃ +┡━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩ +│ │ 172.19.0.1 │ clickhouse-logger-route │ │ 1703026935235 │ 481.00018501282 │ 473 │ 8.0001850128174 │ │ {...} │ {...} │ {...} │ +└──────┴────────────┴─────────────────────────┴────────────┴───────────────┴─────────────────┴──────────────────┴─────────────────┴──────────┴─────────┴──────────┴─────────┘ ``` -## Enable Plugin +### Customize Log Format With Plugin Metadata -If multiple endpoints are configured, they will be written randomly. -The example below shows how you can enable the Plugin on a specific Route: +The following example demonstrates how to customize the log format using Plugin Metadata and [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). + +Plugin Metadata is global in scope and applies to all instances of `clickhouse-logger`. If the log format configured on an individual Plugin instance differs from the log format configured in Plugin Metadata, the instance-level configuration takes precedence. + +Create a table named `custom_logs` in your ClickHouse database with columns corresponding to your customized log format: ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 -H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "plugins": { - "clickhouse-logger": { - "user": "default", - "password": "", - "database": "default", - "logtable": "test", - "endpoint_addrs": ["http://127.0.0.1:8123";] - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } - }, - "uri": "/hello" -}' +curl "http://127.0.0.1:8123"; -X POST -d ' + CREATE TABLE default.custom_logs ( + host String, + client_ip String, + route_id String, + service_id String, + `@timestamp` String, + PRIMARY KEY(`@timestamp`) + ) + ENGINE = MergeTree() Review Comment: The ClickHouse `CREATE TABLE ... ENGINE = MergeTree()` example for `custom_logs` is missing an `ORDER BY` clause, which is required for `MergeTree`. Please add `ORDER BY` (for example, `ORDER BY (@timestamp)`) so readers can run the SQL successfully. ```suggestion ENGINE = MergeTree() ORDER BY (`@timestamp`) ``` ########## docs/zh/latest/plugins/rocketmq-logger.md: ########## @@ -27,202 +27,384 @@ description: API 网关 Apache APISIX 的 rocketmq-logger 插件用于将日志 # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/rocketmq-logger"; /> +</head> + ## 描述 -`rocketmq-logger` 插件可以将日志以 JSON 的形式推送给外部 RocketMQ 集群。 +`rocketmq-logger` 插件将请求和响应日志以 JSON 对象批量推送到 RocketMQ 集群，并支持自定义日志格式。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ---------------------- | ------- | ------ | ---------------- | ------------- ------- | ------------------------------------------------ | -| nameserver_list | object | 是 | | | RocketMQ 的 nameserver 列表。 | -| topic | string | 是 | | | 要推送的 topic 名称。 | -| key | string | 否 | | | 发送消息的 keys。 | -| tag | string | 否 | | | 发送消息的 tags。 | -| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | -| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 | -| use_tls | boolean | 否 | false | | 当设置为 `true` 时，开启 TLS 加密。 | -| access_key | string | 否 | "" | | ACL 认证的 Access key，空字符串表示不开启 ACL。 | -| secret_key | string | 否 | "" | | ACL 认证的 Secret key。 | -| name | string | 否 | "rocketmq logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 | -| 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)。 | +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------------------------|---------|--------|--------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| nameserver_list | array[string] | True | | | RocketMQ nameserver 列表。 | +| topic | string | True | | | 要推送数据的目标 topic。 | +| key | string | False | | | 消息的 key。 | +| tag | string | False | | | 消息的 tag。 | +| log_format | object | False | | | 以 JSON 键值对形式声明的自定义日志格式，值可以引用 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。也可以通过[插件元数据](../plugin-metadata.md)在全局范围内配置日志格式，将应用于所有 `rocketmq-logger` 插件实例。如果插件实例的日志格式与插件元数据的日志格式不同，插件实例的日志格式优先生效。 | +| timeout | integer | False | 3 | | 向上游发送数据的超时时间。 | +| use_tls | boolean | False | false | | 若为 true，则验证 SSL。 | +| access_key | string | False | | | ACL 的 Access key。设置为空字符串将禁用 ACL。 | +| secret_key | string | False | | | ACL 的 Secret key。 | +| name | string | False | `rocketmq logger` | | 批处理器中插件的唯一标识符。若使用 Prometheus 监控 APISIX 指标，该名称将以 `apisix_batch_process_entries` 导出。 | +| meta_format | string | False | `default` | `default` 或 `origin` | 收集请求信息的格式。设为 `default` 以 JSON 格式收集，设为 `origin` 以原始 HTTP 请求格式收集。 | +| include_req_body | boolean | False | false | | 若为 true，则在日志中包含请求体。注意：若请求体太大而无法保存在内存中，由于 NGINX 的限制，将无法记录。 | +| include_req_body_expr | array | False | | | [lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式数组。当 `include_req_body` 为 true 时使用，仅当此处表达式求值为 true 时才记录请求体。 | +| include_resp_body | boolean | False | false | | 若为 true，则在日志中包含响应体。 | +| include_resp_body_expr | array | False | | | [lua-resty-expr](https://github.com/api7/lua-resty-expr) 表达式数组。当 `include_resp_body` 为 true 时使用，仅当此处表达式求值为 true 时才记录响应体。 | +| max_req_body_bytes | integer | False | 524288 | 大于等于 1 | 日志中记录的最大请求体字节数。超出该值的请求体将被截断。在 APISIX 3.16.0 版本中可用。 | +| max_resp_body_bytes | integer | False | 524288 | 大于等于 1 | 日志中记录的最大响应体字节数。超出该值的响应体将被截断。在 APISIX 3.16.0 版本中可用。 | +| batch_max_size | integer | False | 1000 | 大于 0 | 每批次允许的最大日志条目数。达到该值后，批次将被发送至日志服务。设置为 1 表示立即处理。 | +| inactive_timeout | integer | False | 5 | 大于 0 | 在将批次发送至日志服务前等待新日志的最长时间（秒）。该值应小于 `buffer_duration`。 | +| buffer_duration | integer | False | 60 | 大于 0 | 发送批次前允许最早条目存在的最长时间（秒）。 | +| retry_delay | integer | False | 1 | 大于等于 0 | 批次发送失败后重试的时间间隔（秒）。 | +| max_retry_count | integer | False | 60 | 大于等于 0 | 丢弃日志条目前允许的最大重试次数。 | + +注意：schema 中还定义了 `encrypt_fields = {"secret_key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考[加密存储字段](../plugin-develop.md#加密存储字段)。 + +## 插件元数据 + +也可以通过配置插件元数据来设置日志格式，可用配置如下： + +| 名称 | 类型 | 必选项 | 描述 | +|---------------------|---------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------| +| log_format | object | False | 以 JSON 键值对形式声明的自定义日志格式，值可以引用 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。 | +| max_pending_entries | integer | False | 批处理器中允许的最大未处理条目数。达到此限制后，新条目将被丢弃，直到积压减少。在 APISIX 3.15.0 版本中可用。 | + +:::info IMPORTANT + +插件元数据的配置为全局范围生效，将作用于所有使用 `rocketmq-logger` 插件的路由和服务。 -注意：schema 中还定义了 `encrypt_fields = {"secret_key"}`，这意味着该字段将会被加密存储在 etcd 中。具体参考 [加密存储字段](../plugin-develop.md#加密存储字段)。 +::: -该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置)。 +## 使用示例 + +以下示例演示如何在不同场景下配置 `rocketmq-logger` 插件。 + +请先启动一个示例 RocketMQ 集群： + +```yaml title="docker-compose.yml" +version: "3" + +services: + rocketmq_namesrv: + image: apacherocketmq/rocketmq:4.6.0 + container_name: rmqnamesrv + restart: unless-stopped + ports: + - "9876:9876" + command: sh mqnamesrv + networks: + rocketmq_net: + + rocketmq_broker: + image: apacherocketmq/rocketmq:4.6.0 + container_name: rmqbroker + restart: unless-stopped + ports: + - "10909:10909" + - "10911:10911" + - "10912:10912" + depends_on: + - rocketmq_namesrv + command: sh mqbroker -n rmqnamesrv:9876 -c ../conf/broker.conf + networks: + rocketmq_net: + +networks: + rocketmq_net: +``` -:::tip 提示 +启动容器： -数据首先写入缓冲区。当缓冲区超过 `batch_max_size` 或 `buffer_duration` 设置的值时，则会将数据发送到 RocketMQ 服务器并刷新缓冲区。 +```shell +docker compose up -d +``` -如果发送成功，则返回 `true`。如果出现错误，则返回 `nil`，并带有描述错误的字符串 `buffer overflow`。 +稍等片刻，nameserver 和 broker 应相继启动。 -::: +创建 `TopicTest` topic： -### meta_format 示例 +```shell +docker exec -i rmqnamesrv rm /home/rocketmq/rocketmq-4.6.0/conf/tools.yml +docker exec -i rmqnamesrv /home/rocketmq/rocketmq-4.6.0/bin/mqadmin updateTopic -n rmqnamesrv:9876 -t TopicTest -c DefaultCluster +``` -- default: +等待来自已配置 RocketMQ topic 的消息： -```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" - }, - "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 - } +```shell +docker run -it --name rockemq_consumer -e NAMESRV_ADDR=localhost:9876 --net host apacherocketmq/rocketmq:4.6.0 sh tools.sh org.apache.rocketmq.example.quickstart.Consumer Review Comment: 示例里容器名写成了 `rockemq_consumer`，看起来是 `rocketmq_consumer` 的拼写错误。虽然不影响功能，但建议修正以避免读者困惑。 ```suggestion docker run -it --name rocketmq_consumer -e NAMESRV_ADDR=localhost:9876 --net host apacherocketmq/rocketmq:4.6.0 sh tools.sh org.apache.rocketmq.example.quickstart.Consumer ``` ########## docs/en/latest/plugins/syslog.md: ########## @@ -26,58 +26,72 @@ description: This document contains information about the Apache APISIX syslog P # --> -## Description +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/syslog"; /> +</head> -The `syslog` Plugin is used to push logs to a Syslog server. +## Description -Logs can be set as JSON objects. +The `syslog` Plugin pushes request and response logs as JSON objects to syslog servers in batches and supports the customization of log formats. ## Attributes -| Name | Type | Required | Default | Valid values | Description | -|------------------|---------|----------|--------------|---------------|--------------------------------------------------------------------------------------------------------------------------| -| host | string | True | | | IP address or the hostname of the Syslog server. | -| port | integer | True | | | Target port of the Syslog server. | -| name | string | False | "sys logger" | | Identifier for the server. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. | -| timeout | integer | False | 3000 | [1, ...] | Timeout in ms for the upstream to send data. | -| tls | boolean | False | false | | When set to `true` performs TLS verification. | -| flush_limit | integer | False | 4096 | [1, ...] | Maximum size of the buffer (KB) and the current message before it is flushed and written to the server. | -| drop_limit | integer | False | 1048576 | | Maximum size of the buffer (KB) and the current message before the current message is dropped because of the size limit. | -| sock_type | string | False | "tcp" | ["tcp", "udp] | Transport layer protocol to use. | -| pool_size | integer | False | 5 | [5, ...] | Keep-alive pool size used by `sock:keepalive`. | -| 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. | -| 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 | Request bodies within this size will be logged, if the size exceeds the configured value it will be truncated before logging. | -| 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 | | | When the `include_resp_body` attribute is set to `true`, use this to filter based on [lua-resty-expr](https://github.com/api7/lua-resty-expr). If present, only logs the response if the expression evaluates to `true`. | -| max_resp_body_bytes | integer | False | 524288 | >=1 | Response bodies within this size will be logged, if the size exceeds the configured value it will be truncated before logging. | +| Name | Type | Required | Default | Valid values | Description | +|------------------------|---------|----------|--------------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| host | string | True | | | IP address or hostname of the syslog server. | +| port | integer | True | | | Target port of the syslog server. | +| timeout | integer | False | 3000 | greater than 0 | Timeout for the upstream to send data, in milliseconds. | +| tls | boolean | False | false | | If true, verify TLS. | +| flush_limit | integer | False | 4096 | greater than 0 | Maximum size of the buffer and the current message in KB before the logs are pushed to the syslog server. | +| drop_limit | integer | False | 1048576 | greater than 0 | Maximum size of the buffer and the current message allowed in KB before the logs are dropped. | Review Comment: The table describes `flush_limit`/`drop_limit` as KB, but the plugin schema defaults are 4096 and 1048576 and these options are passed directly to `resty.logger.socket` (byte-sized buffer limits). Please change the unit in the docs to bytes (B), or otherwise clarify the unit to match the schema to avoid misconfiguration. ```suggestion | flush_limit | integer | False | 4096 | greater than 0 | Maximum size of the buffer and the current message in bytes (B) before the logs are pushed to the syslog server. | | drop_limit | integer | False | 1048576 | greater than 0 | Maximum size of the buffer and the current message allowed in bytes (B) before the logs are dropped. | ``` ########## docs/en/latest/plugins/splunk-hec-logging.md: ########## @@ -28,76 +28,66 @@ description: This document contains information about the Apache APISIX splunk-h # --> -## Description +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/splunk-hec-logging"; /> +</head> -The `splunk-hec-logging` Plugin is used to forward logs to [Splunk HTTP Event Collector (HEC)](https://docs.splunk.com/Documentation/Splunk/8.2.6/Data/UsetheHTTPEventCollector) for analysis and storage. +## Description -When the Plugin is enabled, APISIX will serialize the request context information to [Splunk Event Data format](https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata) and submit it to the batch queue. When the maximum batch size is exceeded, the data in the queue is pushed to Splunk HEC. See [batch processor](../batch-processor.md) for more details. +The `splunk-hec-logging` Plugin serializes request and response context information to [Splunk Event Data format](https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata) and pushes to your [Splunk HTTP Event Collector (HEC)](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) in batches. The Plugin also supports the customization of log formats. ## Attributes -| Name | Required | Default | Description | -|------------------|----------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| endpoint | True | | Splunk HEC endpoint configurations. | -| endpoint.uri | True | | Splunk HEC event collector API endpoint. | -| endpoint.token | True | | Splunk HEC authentication token. | -| endpoint.channel | False | | Splunk HEC send data channel identifier. Read more: [About HTTP Event Collector Indexer Acknowledgment](https://docs.splunk.com/Documentation/Splunk/8.2.3/Data/AboutHECIDXAck). | -| endpoint.timeout | False | 10 | Splunk HEC send data timeout in seconds. | -| endpoint.keepalive_timeout | False | 60000 | Keepalive timeout in milliseconds. | -| ssl_verify | False | true | When set to `true` enables SSL verification as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake). | -| log_format | 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 `$`. | +| Name | Type | Required | Default | Valid values | Description | +|----------------------------|---------|----------|------------------|----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| endpoint | object | True | | | Splunk HEC endpoint configurations. | +| endpoint.uri | string | True | | | Splunk HEC event collector API endpoint. | +| endpoint.token | string | True | | | Splunk HEC authentication token. | +| endpoint.channel | string | False | | | Splunk HEC send data channel identifier. For more information, see [About HTTP Event Collector Indexer Acknowledgment](https://docs.splunk.com/Documentation/Splunk/latest/Data/AboutHECIDXAck). | +| endpoint.timeout | integer | False | 10 | | Splunk HEC send data timeout in seconds. | +| endpoint.keepalive_timeout | integer | False | 60000 | >= 1000 | Keepalive timeout in milliseconds. | +| ssl_verify | boolean | False | true | | If `true`, enables SSL verification as per [OpenResty docs](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake). | +| log_format | object | False | | | Custom log format using key-value pairs in JSON format. Values can reference [APISIX variables](../apisix-variable.md) or [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html) by prefixing with `$`. You can also configure log format on a global scale using [Plugin Metadata](#plugin-metadata). | +| name | string | False | splunk-hec-logging | | Unique identifier of the Plugin for the batch processor. | +| batch_max_size | integer | False | 1000 | greater than 0 | The number of log entries allowed in one batch. Once reached, the batch will be sent to Splunk HEC. Setting this parameter to `1` means immediate processing. | +| inactive_timeout | integer | False | 5 | greater than 0 | The maximum time in seconds to wait for new logs before sending the batch to the logging service. The value should be smaller than `buffer_duration`. | +| buffer_duration | integer | False | 60 | greater than 0 | The maximum time in seconds from the earliest entry allowed before sending the batch to the logging service. | +| retry_delay | integer | False | 1 | >= 0 | The time interval in seconds to retry sending the batch to the logging service if the batch was not successfully sent. | +| max_retry_count | integer | False | 60 | >= 0 | The maximum number of unsuccessful retries allowed before dropping the log entries. | This Plugin supports using batch processors to aggregate and process entries (logs/data) in a batch. This avoids the need for frequently submitting the data. The batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. See [Batch Processor](../batch-processor.md#configuration) for more information or setting your custom configuration. -### Example of default log format +## Plugin Metadata -```json -{ - "sourcetype": "_json", - "time": 1704513555.392, - "event": { - "upstream": "127.0.0.1:1980", - "request_url": "http://localhost:1984/hello";, - "request_query": {}, - "request_size": 59, - "response_headers": { - "content-length": "12", - "server": "APISIX/3.7.0", - "content-type": "text/plain", - "connection": "close" - }, - "response_status": 200, - "response_size": 118, - "latency": 108.00004005432, - "request_method": "GET", - "request_headers": { - "connection": "close", - "host": "localhost" - } - }, - "source": "apache-apisix-splunk-hec-logging", - "host": "localhost" -} -``` +| Name | Type | Required | Default | Valid values | Description | +|--------------------|---------|----------|---------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| log_format | object | False | | | Custom log format using key-value pairs in JSON format. Values can reference [APISIX variables](../apisix-variable.md) or [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html) by prefixing with `$`. This configuration is global and applies to all Routes and Services that use the `splunk-hec-logging` Plugin. | +| max_pending_entries | integer | False | | >= 1 | Maximum number of unprocessed entries allowed in the batch processor. When this limit is reached, new entries will be dropped until the backlog is reduced. | -## Metadata +## Examples -You can also set the format of the logs by configuring the Plugin metadata. The following configurations are available: +The examples below demonstrate how you can configure the `splunk-hec-logging` Plugin for different use cases. -| Name | Type | Required | Default | Description | -| ---------- | ------ | -------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| 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 `$`. | -| max_pending_entries | integer | False | | Maximum number of pending entries that can be buffered in batch processor before it starts dropping them. | +To follow along with the examples, please complete the following steps to set up Splunk: -:::info IMPORTANT +* Install [Splunk](https://www.splunk.com/en_us/download.html). Splunk Web should be running at `localhost:8000` by default. +* See [set up and use HTTP Event Collector in Splunk Web](https://docs.splunk.com/Documentation/Splunk/latest/Data/UsetheHTTPEventCollector) to set up an HTTP Event Collector. +* Navigate to **Settings > Data Inputs** at the upper-right corner of the console. You should see at least one input for the HTTP Event Collector. Note down the token value. +* Navigate to **Settings > Data Inputs** at the upper-right corner of the console and select **HTTP Event Collector**. In **Global Settings**, enable all tokens. +* In **Global Settings**, you should also find the collector's default port to be `8088`. -Configuring the Plugin metadata is global in scope. This means that it will take effect on all Routes and Services which use the `splunk-hec-logging` Plugin. +To verify the setup, execute the following command with your token: -::: +```shell +curl "http://localhost:8088/services/collector/event"; \ Review Comment: The Splunk verification command has a trailing space after the line-continuation backslash (`\ `), which will break the command in many shells. Remove the trailing space so the multi-line curl works as intended. ```suggestion curl "http://localhost:8088/services/collector/event"; \ ``` ########## docs/zh/latest/plugins/clickhouse-logger.md: ########## @@ -118,95 +93,167 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### 使用默认日志格式记录日志 + +以下示例演示如何使用默认日志格式记录请求日志。 + +在 ClickHouse 数据库中创建名为 `default_logs` 的表，列对应默认日志格式： + ```shell -curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/clickhouse-logger \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "log_format": { - "host": "$host", - "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" - } -}' +curl "http://127.0.0.1:8123"; -X POST -d ' + CREATE TABLE default.default_logs ( + host String, + client_ip String, + route_id String, + service_id String, + start_time String, + latency String, + upstream_latency String, + apisix_latency String, + consumer String, + request String, + response String, + server String, + PRIMARY KEY(`start_time`) + ) + ENGINE = MergeTree() +' --user default: ``` -您可以使用 Clickhouse docker 镜像来创建一个容器，如下所示： +创建一条启用 `clickhouse-logger` 插件的路由： ```shell -docker run -d -p 8123:8123 -p 9000:9000 -p 9009:9009 --name some-clickhouse-server --ulimit nofile=262144:262144 clickhouse/clickhouse-server +curl "http://127.0.0.1:9180/apisix/admin/routes"; -X PUT \ + -H "X-API-KEY: ${admin_key}" \ + -d '{ + "id": "clickhouse-logger-route", + "uri": "/get", + "plugins": { + "clickhouse-logger": { + "user": "default", + "password": "", + "database": "default", + "logtable": "default_logs", + "endpoint_addrs": ["http://127.0.0.1:8123";] + } + }, + "upstream": { + "type": "roundrobin", + "nodes": { + "httpbin.org": 1 + } + } + }' ``` -然后在您的 ClickHouse 数据库中创建一个表来存储日志。 +向路由发送请求以生成日志条目： ```shell -curl -X POST 'http://localhost:8123/' \ ---data-binary 'CREATE TABLE default.test (host String, client_ip String, route_id String, service_id String, `@timestamp` String, PRIMARY KEY(`@timestamp`)) ENGINE = MergeTree()' --user default: +curl -i "http://127.0.0.1:9080/get"; ``` -## 启用插件 +您应该看到 `HTTP/1.1 200 OK` 响应。 -你可以通过以下命令在指定路由中启用该插件： +向 ClickHouse 发送请求以查看日志条目： ```shell -curl http://127.0.0.1:9180/apisix/admin/routes/1 \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "plugins": { - "clickhouse-logger": { - "user": "default", - "password": "", - "database": "default", - "logtable": "test", - "endpoint_addrs": ["http://127.0.0.1:8123";] - } - }, - "upstream": { - "type": "roundrobin", - "nodes": { - "127.0.0.1:1980": 1 - } - }, - "uri": "/hello" -}' +echo 'SELECT * FROM default.default_logs FORMAT Pretty' | curl "http://127.0.0.1:8123/?"; -d @- ``` -:::note 注意 +您应该看到类似如下的日志条目： -如果配置多个 `endpoints`，日志将会随机写入到各个 `endpoints`。 +```text +┏━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━┓ +┃ host ┃ client_ip ┃ route_id ┃ service_id ┃ start_time ┃ latency ┃ upstream_latency ┃ apisix_latency ┃ consumer ┃ request ┃ response ┃ server ┃ +┡━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━┩ +│ │ 172.19.0.1 │ clickhouse-logger-route │ │ 1703026935235 │ 481.00018501282 │ 473 │ 8.0001850128174 │ │ {...} │ {...} │ {...} │ +└──────┴────────────┴─────────────────────────┴────────────┴───────────────┴─────────────────┴──────────────────┴─────────────────┴──────────┴─────────┴──────────┴─────────┘ +``` -::: +### 使用插件元数据自定义日志格式 + +以下示例演示如何使用插件元数据和 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html) 自定义日志格式。 -## 测试插件 +插件元数据全局生效，对所有 `clickhouse-logger` 实例有效。如果单个插件实例上配置的日志格式与插件元数据中配置的日志格式不同，则实例级别的配置优先。 -现在你可以向 APISIX 发起请求： +在 ClickHouse 数据库中创建名为 `custom_logs` 的表，列对应自定义日志格式： ```shell -curl -i http://127.0.0.1:9080/hello +curl "http://127.0.0.1:8123"; -X POST -d ' + CREATE TABLE default.custom_logs ( + host String, + client_ip String, + route_id String, + service_id String, + `@timestamp` String, + PRIMARY KEY(`@timestamp`) + ) + ENGINE = MergeTree() Review Comment: ClickHouse 的 `custom_logs` 建表示例同样缺少 `ORDER BY` 子句（`MergeTree` 需要）。建议增加 `ORDER BY`（例如 `ORDER BY (@timestamp)`）以保证示例可运行。 ```suggestion ENGINE = MergeTree() ORDER BY (`@timestamp`) ``` ########## docs/zh/latest/plugins/clickhouse-logger.md: ########## @@ -118,95 +93,167 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/ ::: +### 使用默认日志格式记录日志 + +以下示例演示如何使用默认日志格式记录请求日志。 + +在 ClickHouse 数据库中创建名为 `default_logs` 的表，列对应默认日志格式： + ```shell -curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/clickhouse-logger \ --H "X-API-KEY: $admin_key" -X PUT -d ' -{ - "log_format": { - "host": "$host", - "@timestamp": "$time_iso8601", - "client_ip": "$remote_addr" - } -}' +curl "http://127.0.0.1:8123"; -X POST -d ' + CREATE TABLE default.default_logs ( + host String, + client_ip String, + route_id String, + service_id String, + start_time String, + latency String, + upstream_latency String, + apisix_latency String, + consumer String, + request String, + response String, + server String, + PRIMARY KEY(`start_time`) + ) + ENGINE = MergeTree() Review Comment: ClickHouse 的 `CREATE TABLE ... ENGINE = MergeTree()` 示例缺少 `ORDER BY` 子句。`MergeTree` 引擎通常要求显式 `ORDER BY`（`PRIMARY KEY` 可选且默认与排序键相关）。建议补充 `ORDER BY`（例如 `ORDER BY (start_time)`），保证示例 SQL 可直接执行。 ```suggestion ENGINE = MergeTree() ORDER BY (start_time) ``` ########## docs/en/latest/plugins/rocketmq-logger.md: ########## @@ -26,260 +26,384 @@ description: This document contains information about the Apache APISIX rocketmq # --> -## Description +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/rocketmq-logger"; /> +</head> -The `rocketmq-logger` Plugin provides the ability to push logs as JSON objects to your RocketMQ clusters. +## Description -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. +The `rocketmq-logger` Plugin pushes request and response logs as JSON objects to RocketMQ clusters in batches and supports the customization of log formats. ## Attributes -| Name | Type | Required | Default | Valid values | Description | -|------------------------|---------|----------|-------------------------------------------------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| nameserver_list | object | True | | | List of RocketMQ nameservers. | -| topic | string | True | | | Target topic to push the data to. | -| key | string | False | | | Key of the messages. | -| tag | string | False | | | Tag of the messages. | -| 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 `$`. | -| timeout | integer | False | 3 | [1,...] | Timeout for the upstream to send data. | -| use_tls | boolean | False | false | | When set to `true`, uses TLS. | -| access_key | string | False | "" | | Access key for ACL. Setting to an empty string will disable the ACL. | -| secret_key | string | False | "" | | secret key for ACL. | -| name | string | False | "rocketmq logger" | | Unique identifier for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. processor. | -| 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. | -| 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 | Request bodies within this size will be logged, if the size exceeds the configured value it will be truncated before logging. | -| 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 | Response bodies within this size will be logged, if the size exceeds the configured value it will be truncated before logging. | +| Name | Type | Required | Default | Valid values | Description | +|------------------------|---------|----------|--------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| nameserver_list | array[string] | True | | | List of RocketMQ nameservers. | +| topic | string | True | | | Target topic to push the data to. | +| key | string | False | | | Key of the message. | +| tag | string | False | | | Tag of the message. | +| log_format | object | False | | | Custom log format using key-value pairs in JSON format. Values can reference [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). You can also configure log format on a global scale using the [plugin metadata](../plugin-metadata.md), which configures the log format for all `rocketmq-logger` Plugin instances. If the log format configured on the individual Plugin instance differs from the log format configured on Plugin metadata, the log format configured on the individual Plugin instance takes precedence. | +| timeout | integer | False | 3 | | Timeout for the upstream to send data. | +| use_tls | boolean | False | false | | If true, verify SSL. | Review Comment: `use_tls` is only used to enable TLS in the plugin implementation (it toggles `setUseTLS(true)`), it does not mean “verify SSL”. Please update the description to reflect that it enables TLS encryption/connection. ```suggestion | use_tls | boolean | False | false | | If true, enable TLS encryption for the connection. | ``` ########## docs/zh/latest/plugins/rocketmq-logger.md: ########## @@ -27,202 +27,384 @@ description: API 网关 Apache APISIX 的 rocketmq-logger 插件用于将日志 # --> +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/rocketmq-logger"; /> +</head> + ## 描述 -`rocketmq-logger` 插件可以将日志以 JSON 的形式推送给外部 RocketMQ 集群。 +`rocketmq-logger` 插件将请求和响应日志以 JSON 对象批量推送到 RocketMQ 集群，并支持自定义日志格式。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ---------------------- | ------- | ------ | ---------------- | ------------- ------- | ------------------------------------------------ | -| nameserver_list | object | 是 | | | RocketMQ 的 nameserver 列表。 | -| topic | string | 是 | | | 要推送的 topic 名称。 | -| key | string | 否 | | | 发送消息的 keys。 | -| tag | string | 否 | | | 发送消息的 tags。 | -| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | -| timeout | integer | 否 | 3 | [1,...] | 发送数据的超时时间。 | -| use_tls | boolean | 否 | false | | 当设置为 `true` 时，开启 TLS 加密。 | -| access_key | string | 否 | "" | | ACL 认证的 Access key，空字符串表示不开启 ACL。 | -| secret_key | string | 否 | "" | | ACL 认证的 Secret key。 | -| name | string | 否 | "rocketmq logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 | -| 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)。 | +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------------------------|---------|--------|--------------------|-----------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| nameserver_list | array[string] | True | | | RocketMQ nameserver 列表。 | +| topic | string | True | | | 要推送数据的目标 topic。 | +| key | string | False | | | 消息的 key。 | +| tag | string | False | | | 消息的 tag。 | +| log_format | object | False | | | 以 JSON 键值对形式声明的自定义日志格式，值可以引用 [NGINX 变量](https://nginx.org/en/docs/http/ngx_http_core_module.html)。也可以通过[插件元数据](../plugin-metadata.md)在全局范围内配置日志格式，将应用于所有 `rocketmq-logger` 插件实例。如果插件实例的日志格式与插件元数据的日志格式不同，插件实例的日志格式优先生效。 | +| timeout | integer | False | 3 | | 向上游发送数据的超时时间。 | +| use_tls | boolean | False | false | | 若为 true，则验证 SSL。 | Review Comment: `use_tls` 在代码里仅用于开启 TLS（`setUseTLS(true)`），并不表示“验证 SSL”。建议将该属性描述改为“启用 TLS 连接/加密传输”，避免与 `tls_verify` 一类含义混淆。 ```suggestion | use_tls | boolean | False | false | | 若为 true，则启用 TLS 连接以加密传输。 | ``` ########## docs/en/latest/plugins/rocketmq-logger.md: ########## @@ -26,260 +26,384 @@ description: This document contains information about the Apache APISIX rocketmq # --> -## Description +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/rocketmq-logger"; /> +</head> -The `rocketmq-logger` Plugin provides the ability to push logs as JSON objects to your RocketMQ clusters. +## Description -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. +The `rocketmq-logger` Plugin pushes request and response logs as JSON objects to RocketMQ clusters in batches and supports the customization of log formats. ## Attributes -| Name | Type | Required | Default | Valid values | Description | -|------------------------|---------|----------|-------------------------------------------------------------------------------|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| nameserver_list | object | True | | | List of RocketMQ nameservers. | -| topic | string | True | | | Target topic to push the data to. | -| key | string | False | | | Key of the messages. | -| tag | string | False | | | Tag of the messages. | -| 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 `$`. | -| timeout | integer | False | 3 | [1,...] | Timeout for the upstream to send data. | -| use_tls | boolean | False | false | | When set to `true`, uses TLS. | -| access_key | string | False | "" | | Access key for ACL. Setting to an empty string will disable the ACL. | -| secret_key | string | False | "" | | secret key for ACL. | -| name | string | False | "rocketmq logger" | | Unique identifier for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. processor. | -| 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. | -| 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 | Request bodies within this size will be logged, if the size exceeds the configured value it will be truncated before logging. | -| 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 | Response bodies within this size will be logged, if the size exceeds the configured value it will be truncated before logging. | +| Name | Type | Required | Default | Valid values | Description | +|------------------------|---------|----------|--------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| nameserver_list | array[string] | True | | | List of RocketMQ nameservers. | +| topic | string | True | | | Target topic to push the data to. | +| key | string | False | | | Key of the message. | +| tag | string | False | | | Tag of the message. | +| log_format | object | False | | | Custom log format using key-value pairs in JSON format. Values can reference [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). You can also configure log format on a global scale using the [plugin metadata](../plugin-metadata.md), which configures the log format for all `rocketmq-logger` Plugin instances. If the log format configured on the individual Plugin instance differs from the log format configured on Plugin metadata, the log format configured on the individual Plugin instance takes precedence. | +| timeout | integer | False | 3 | | Timeout for the upstream to send data. | +| use_tls | boolean | False | false | | If true, verify SSL. | +| access_key | string | False | | | Access key for ACL. Setting to an empty string will disable the ACL. | +| secret_key | string | False | | | Secret key for ACL. | +| name | string | False | `rocketmq logger` | | Unique identifier of the Plugin for the batch processor. If you use Prometheus to monitor APISIX metrics, the name is exported in `apisix_batch_process_entries`. | +| meta_format | string | False | `default` | `default` or `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. | +| include_req_body | boolean | False | false | | If true, include the request body in the log. Note that if the request body is too big to be kept in the memory, it cannot be logged due to NGINX's limitations. | +| include_req_body_expr | array | False | | | An array of one or more conditions in the form of [lua-resty-expr](https://github.com/api7/lua-resty-expr) expressions. Used when `include_req_body` is true. Request body is only logged when the expressions configured here evaluate to true. | +| include_resp_body | boolean | False | false | | If true, include the response body in the log. | +| include_resp_body_expr | array | False | | | An array of one or more conditions in the form of [lua-resty-expr](https://github.com/api7/lua-resty-expr) expressions. Used when `include_resp_body` is true. Response body is only logged when the expressions configured here evaluate to true. | +| max_req_body_bytes | integer | False | 524288 | greater than or equal to 1 | Maximum request body size in bytes to include in the log. If the request body exceeds this value, it will be truncated. Available in APISIX from 3.16.0. | +| max_resp_body_bytes | integer | False | 524288 | greater than or equal to 1 | Maximum response body size in bytes to include in the log. If the response body exceeds this value, it will be truncated. Available in APISIX from 3.16.0. | +| batch_max_size | integer | False | 1000 | greater than 0 | The number of log entries allowed in one batch. Once reached, the batch will be sent to the logging service. Setting this parameter to 1 means immediate processing. | +| inactive_timeout | integer | False | 5 | greater than 0 | The maximum time in seconds to wait for new logs before sending the batch to the logging service. The value should be smaller than `buffer_duration`. | +| buffer_duration | integer | False | 60 | greater than 0 | The maximum time in seconds from the earliest entry allowed before sending the batch to the logging service. | +| retry_delay | integer | False | 1 | greater than or equal to 0 | The time interval in seconds to retry sending the batch to the logging service if the batch was not successfully sent. | +| max_retry_count | integer | False | 60 | greater than or equal to 0 | The maximum number of unsuccessful retries allowed before dropping the log entries. | NOTE: `encrypt_fields = {"secret_key"}` is also defined in the schema, which means that the field will be stored encrypted in etcd. See [encrypted storage fields](../plugin-develop.md#encrypted-storage-fields). -This Plugin supports using batch processors to aggregate and process entries (logs/data) in a batch. This avoids the need for frequently submitting the data. The batch processor submits data every `5` seconds or when the data in the queue reaches `1000`. See [Batch Processor](../batch-processor.md#configuration) for more information or setting your custom configuration. +## Metadata -:::info IMPORTANT +You can also set the format of the logs by configuring the Plugin metadata. The following configurations are available: -The data is first written to a buffer. When the buffer exceeds the `batch_max_size` or `buffer_duration` attribute, the data is sent to the RocketMQ server and the buffer is flushed. +| Name | Type | Required | Description | +|---------------------|---------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| log_format | object | False | Custom log format using key-value pairs in JSON format. Values can reference [NGINX variables](https://nginx.org/en/docs/http/ngx_http_core_module.html). | +| max_pending_entries | integer | False | Maximum number of unprocessed entries allowed in the batch processor. When this limit is reached, new entries will be dropped until the backlog is reduced. Available in APISIX from version 3.15.0. | -If the process is successful, it will return `true` and if it fails, returns `nil` with a string with the "buffer overflow" error. +:::info IMPORTANT + +Configuring the Plugin metadata is global in scope. This means that it will take effect on all Routes and Services which use the `rocketmq-logger` Plugin. ::: -### meta_format example +## Examples + +The examples below demonstrate how you can configure the `rocketmq-logger` Plugin for different scenarios. + +To follow along the examples, start a sample RocketMQ cluster: + +```yaml title="docker-compose.yml" +version: "3" + +services: + rocketmq_namesrv: + image: apacherocketmq/rocketmq:4.6.0 + container_name: rmqnamesrv + restart: unless-stopped + ports: + - "9876:9876" + command: sh mqnamesrv + networks: + rocketmq_net: + + rocketmq_broker: + image: apacherocketmq/rocketmq:4.6.0 + container_name: rmqbroker + restart: unless-stopped + ports: + - "10909:10909" + - "10911:10911" + - "10912:10912" + depends_on: + - rocketmq_namesrv + command: sh mqbroker -n rmqnamesrv:9876 -c ../conf/broker.conf + networks: + rocketmq_net: + +networks: + rocketmq_net: +``` -- default: +Start containers: -```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" - }, - "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 - } +```shell +docker compose up -d ``` -- origin: +In a few seconds, the name server and broker should start. -```http - GET /hello?ab=cd HTTP/1.1 - host: localhost - content-length: 6 - connection: close +Create the `TopicTest` topic: - abcdef +```shell +docker exec -i rmqnamesrv rm /home/rocketmq/rocketmq-4.6.0/conf/tools.yml +docker exec -i rmqnamesrv /home/rocketmq/rocketmq-4.6.0/bin/mqadmin updateTopic -n rmqnamesrv:9876 -t TopicTest -c DefaultCluster ``` -### meta_format example - -- `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 - } - ``` - -- `origin`: +Wait for messages in the configured RocketMQ topic: - ```http - GET /hello?ab=cd HTTP/1.1 - host: localhost - content-length: 6 - connection: close +```shell +docker run -it --name rockemq_consumer -e NAMESRV_ADDR=localhost:9876 --net host apacherocketmq/rocketmq:4.6.0 sh tools.sh org.apache.rocketmq.example.quickstart.Consumer Review Comment: The container name `rockemq_consumer` looks like a typo (should likely be `rocketmq_consumer`). Consider fixing it to avoid confusion when readers follow the example. ```suggestion docker run -it --name rocketmq_consumer -e NAMESRV_ADDR=localhost:9876 --net host apacherocketmq/rocketmq:4.6.0 sh tools.sh org.apache.rocketmq.example.quickstart.Consumer ``` ########## docs/zh/latest/plugins/syslog.md: ########## @@ -27,118 +27,302 @@ description: API 网关 Apache APISIX syslog 插件可用于将日志推送到 S # --> -## 描述 +<head> + <link rel="canonical" href="https://docs.api7.ai/hub/syslog"; /> +</head> -`syslog` 插件可用于将日志推送到 Syslog 服务器。 +## 描述 -该插件还实现了将日志数据以 JSON 格式发送到 Syslog 服务的能力。 +`syslog` 插件将请求和响应日志以 JSON 对象批量推送到 syslog 服务器，并支持自定义日志格式。 ## 属性 -| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | -| ---------------- | ------- | ------ | ------------ | ------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| host | string | 是 | | | IP 地址或主机名。 | -| port | integer | 是 | | | 目标上游端口。 | -| name | string | 否 | "sys logger" | | 标识 logger 的唯一标识符。如果您使用 Prometheus 监视 APISIX 指标，名称将以 `apisix_batch_process_entries` 导出。 | -| timeout | integer | 否 | 3000 | [1, ...] | 上游发送数据超时（以毫秒为单位）。 | -| tls | boolean | 否 | false | | 当设置为 `true` 时执行 SSL 验证。 | -| flush_limit | integer | 否 | 4096 | [1, ...] | 如果缓冲的消息的大小加上当前消息的大小达到（> =）此限制（以字节为单位），则缓冲的日志消息将被写入日志服务器，默认为 4096（4KB）。 | -| drop_limit | integer | 否 | 1048576 | | 如果缓冲的消息的大小加上当前消息的大小大于此限制（以字节为单位），则由于缓冲区大小有限，当前的日志消息将被丢弃，默认为 1048576（1MB）。 | -| sock_type | string | 否 | "tcp" | ["tcp","udp"] | 用于传输层的 IP 协议类型。 | -| max_retry_count | integer | 否 | | [1, ...] | 连接到日志服务器失败或将日志消息发送到日志服务器失败后的最大重试次数。 | -| retry_delay | integer | 否 | | [0, ...] | 重试连接到日志服务器或重试向日志服务器发送日志消息之前的时间延迟（以毫秒为单位）。 | -| pool_size | integer | 否 | 5 | [5, ...] | `sock：keepalive` 使用的 Keepalive 池大小。 | -| log_format | object | 否 | | | 日志格式以 JSON 的键值对声明。值支持字符串和嵌套对象（最多五层，超出部分将被截断）。字符串中可通过在前面加上 `$` 来引用 [APISIX 变量](../apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 | -| include_req_body | boolean | 否 | false | [false, true] | 当设置为 `true` 时包括请求体。 | -| 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)。 | - -该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认情况下批处理器每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置)。 - -### 默认日志格式示例 - -```text -"<46>1 2024-01-06T02:30:59.145Z 127.0.0.1 apisix 82324 - - {\"response\":{\"status\":200,\"size\":141,\"headers\":{\"content-type\":\"text/plain\",\"server\":\"APISIX/3.7.0\",\"transfer-encoding\":\"chunked\",\"connection\":\"close\"}},\"route_id\":\"1\",\"server\":{\"hostname\":\"baiyundeMacBook-Pro.local\",\"version\":\"3.7.0\"},\"request\":{\"uri\":\"/opentracing\",\"url\":\"http://127.0.0.1:1984/opentracing\",\"querystring\":{},\"method\":\"GET\",\"size\":155,\"headers\":{\"content-type\":\"application/x-www-form-urlencoded\",\"host\":\"127.0.0.1:1984\",\"user-agent\":\"lua-resty-http/0.16.1 (Lua) ngx_lua/10025\"}},\"upstream\":\"127.0.0.1:1982\",\"apisix_latency\":100.99999809265,\"service_id\":\"\",\"upstream_latency\":1,\"start_time\":1704508259044,\"client_ip\":\"127.0.0.1\",\"latency\":101.99999809265}\n" -``` +| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 | +|------------------------|---------|--------|--------------|-----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| host | string | True | | | syslog 服务器的 IP 地址或主机名。 | +| port | integer | True | | | syslog 服务器的目标端口。 | +| timeout | integer | False | 3000 | 大于 0 | 向上游发送数据的超时时间（毫秒）。 | +| tls | boolean | False | false | | 若为 true，则验证 TLS。 | +| flush_limit | integer | False | 4096 | 大于 0 | 推送日志到 syslog 服务器前，缓冲区和当前消息的最大大小（KB）。 | +| drop_limit | integer | False | 1048576 | 大于 0 | 丢弃日志前，缓冲区和当前消息允许的最大大小（KB）。 | Review Comment: `flush_limit`/`drop_limit` 的单位这里写成了 KB，但 syslog 插件 schema 中的默认值分别是 4096 和 1048576（更符合字节语义，且与旧文档描述一致）。建议将单位改为字节（B），或明确说明这些值的单位与 APISIX schema 一致，以免用户按 KB 理解导致配置偏差。 ```suggestion | flush_limit | integer | False | 4096 | 大于 0 | 推送日志到 syslog 服务器前，缓冲区和当前消息的最大大小（字节，B）。 | | drop_limit | integer | False | 1048576 | 大于 0 | 丢弃日志前，缓冲区和当前消息允许的最大大小（字节，B）。 | ``` -- 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]
