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 08:43:31 UTC
[apisix] branch master updated: docs: refactor loggers plugin doc (2) (#7708)
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 1aeb3a651 docs: refactor loggers plugin doc (2) (#7708)
1aeb3a651 is described below
commit 1aeb3a6517458bce94988e0d6e05a210fb70cfa2
Author: Fei Han <97...@users.noreply.github.com>
AuthorDate: Tue Aug 23 16:43:24 2022 +0800
docs: refactor loggers plugin doc (2) (#7708)
* docs: update loggly
Co-authored-by: hf400159 <hf...@163.com>
---
docs/en/latest/plugins/google-cloud-logging.md | 2 +-
docs/en/latest/plugins/loggly.md | 4 +-
docs/zh/latest/config.json | 3 +-
docs/zh/latest/plugins/file-logger.md | 84 +++++++------
docs/zh/latest/plugins/google-cloud-logging.md | 70 ++++++-----
docs/zh/latest/plugins/http-logger.md | 6 +-
docs/zh/latest/plugins/loggly.md | 166 +++++++++++++++++++++++++
docs/zh/latest/plugins/splunk-hec-logging.md | 58 +++++----
8 files changed, 293 insertions(+), 100 deletions(-)
diff --git a/docs/en/latest/plugins/google-cloud-logging.md b/docs/en/latest/plugins/google-cloud-logging.md
index 19c98bbc7..241f91ddc 100644
--- a/docs/en/latest/plugins/google-cloud-logging.md
+++ b/docs/en/latest/plugins/google-cloud-logging.md
@@ -39,7 +39,7 @@ This plugin also allows to push logs as a batch to your Google Cloud Logging Ser
| auth_config | True | | Either `auth_config` or `auth_file` must be provided. |
| auth_config.private_key | True | | Private key of the Google Cloud service account. |
| auth_config.project_id | True | | Project ID in the Google Cloud service account. |
-| auth_config.token_uri | False | https://oauth2.googleapis.com/token | Token URI of the Google Cloud service account. |
+| auth_config.token_uri | True | https://oauth2.googleapis.com/token | Token URI of the Google Cloud service account. |
| auth_config.entries_uri | False | https://logging.googleapis.com/v2/entries:write | Google Cloud Logging Service API. |
| auth_config.scopes | False | ["https://www.googleapis.com/auth/logging.read", "https://www.googleapis.com/auth/logging.write", "https://www.googleapis.com/auth/logging.admin", "https://www.googleapis.com/auth/cloud-platform"] | Access scopes of the Google Cloud service account. See [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes#logging). |
| auth_file | True | | Path to the Google Cloud service account authentication JSON file. Either `auth_config` or `auth_file` must be provided. |
diff --git a/docs/en/latest/plugins/loggly.md b/docs/en/latest/plugins/loggly.md
index bb8ef625c..537cd5b16 100644
--- a/docs/en/latest/plugins/loggly.md
+++ b/docs/en/latest/plugins/loggly.md
@@ -44,7 +44,7 @@ When the maximum batch size is exceeded, the data in the queue is pushed to Logg
| severity_map | object | False | nil | A way to map upstream HTTP response codes to Syslog severity. Key-value pairs where keys are the HTTP response codes and the values are the Syslog severity levels. For example `{"410": "CRIT"}`. |
| tags | array | False | | Metadata to be included with any event log to aid in segmentation and filtering. |
| include_req_body | boolean | False | false | 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_resp_body | boolean | False | false | When set to `true` includes the request body in the log. |
+| include_resp_body | boolean | False | false | 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`. |
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.
@@ -63,7 +63,7 @@ You can also configure the Plugin through Plugin metadata. The following configu
| protocol | string | False | "syslog" | [ "syslog" , "http", "https" ] | Protocol in which the logs are sent to Loggly. |
| log_format | object | False | nil | | Log format declared as key value pairs in JSON format. Values only support strings. [APISIX](../apisix-variable.md) or [Nginx](http://nginx.org/en/docs/varindex.html) variables can be used by prefixing the string with `$`. |
-We support [Syslog](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/streaming-syslog-without-using-files.htm), [HTTP/S](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/http-bulk-endpoint.htm) (bulk endpoint) protocols to send log events to Loggly. By default, in APISIX side, the protocol is set to "syslog". It lets you send RFC5424 compliant syslog events with some fine-grained control (log severity mapping based on upstream HTTP re [...]
+We support [Syslog](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/streaming-syslog-without-using-files.htm), [HTTP/S](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/http-bulk-endpoint.htm) (bulk endpoint) protocols to send log events to Loggly. By default, in APISIX side, the protocol is set to "syslog". It lets you send RFC5424 compliant syslog events with some fine-grained control (log severity mapping based on upstream HTTP re [...]
:::note
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 14c45fa6f..6d70ff30e 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -152,7 +152,8 @@
"plugins/sls-logger",
"plugins/google-cloud-logging",
"plugins/splunk-hec-logging",
- "plugins/file-logger"
+ "plugins/file-logger",
+ "plugins/loggly"
]
}
]
diff --git a/docs/zh/latest/plugins/file-logger.md b/docs/zh/latest/plugins/file-logger.md
index 41de2b657..4e07a9528 100644
--- a/docs/zh/latest/plugins/file-logger.md
+++ b/docs/zh/latest/plugins/file-logger.md
@@ -1,5 +1,11 @@
---
title: file-logger
+keywords:
+ - APISIX
+ - API 网关
+ - Plugin
+ - file-logger
+description: API 网关 Apache APISIX file-logger 插件可用于将日志数据存储到指定位置。
---
<!--
@@ -23,20 +29,48 @@ title: file-logger
## 描述
-`file-logger` 是一个插件，可将 Log 数据流推送到指定位置，例如，可以自定义输出路径：`logs/file.log`。
+`file-logger` 插件可用于将日志数据存储到指定位置。
## 属性
+| 名称 | 类型 | 必选项 | 描述 |
+| ---------------- | ------- | ------ | ------------------------------------------------ |
+| path | string | 是 | 自定义输出文件路径。例如：`logs/file.log`。 |
+
+## 插件元数据设置
+
| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
| ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ |
-| path | string | 必须 | | | 自定义输出文件路径 |
+| 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` 后，将对所有绑定 `file-logger` 插件的路由或服务生效。 |
-## 如何开启
+以下示例展示了如何通过 Admin API 配置插件元数据：
-这是有关如何为特定路由启用 `file-logger` 插件的示例。
+```shell
+curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/file-logger \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "log_format": {
+ "host": "$host",
+ "@timestamp": "$time_iso8601",
+ "client_ip": "$remote_addr"
+ }
+}'
+```
+
+配置完成后，你可以在日志系统中看到如下类似日志：
```shell
-curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{"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"}
+```
+
+## 启用插件
+
+你可以通过以下命令在指定路由中启用该插件：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
"plugins": {
"file-logger": {
@@ -55,49 +89,27 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
-> 成功：
+你可以通过以下命令向 APISIX 发出请求：
```shell
-$ curl -i http://127.0.0.1:9080/hello
+curl -i http://127.0.0.1:9080/hello
+```
+
+```
HTTP/1.1 200 OK
...
hello, world
```
-然后你可以在对应的 `logs` 目录下找到 `file.log` 文件。
-
-## 插件元数据设置
-
-| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
-| ---------------- | ------- | ------ | ------------- | ------- | ------------------------------------------------ |
-| 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 后，将对所有绑定 file-logger 的 Route 或 Service 生效。 |
-
-### 设置日志格式示例
-
-```shell
-curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/file-logger -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
-{
- "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"}
-```
+访问成功后，你可以在对应的 `logs` 目录下找到 `file.log` 文件。
## 禁用插件
-在插件配置中删除相应的 json 配置以禁用 file-logger。APISIX 插件是热重载的，因此无需重新启动 APISIX：
+当你需要禁用该插件时，可以通过如下命令删除相应的 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",
diff --git a/docs/zh/latest/plugins/google-cloud-logging.md b/docs/zh/latest/plugins/google-cloud-logging.md
index 3e96a80d3..1b44b1898 100644
--- a/docs/zh/latest/plugins/google-cloud-logging.md
+++ b/docs/zh/latest/plugins/google-cloud-logging.md
@@ -1,5 +1,12 @@
---
title: google-cloud-logging
+keywords:
+ - APISIX
+ - API 网关
+ - 插件
+ - Splunk
+ - 日志
+description: API 网关 Apache APISIX 的 google-cloud-logging 插件可用于将请求日志转发到 Google Cloud Logging Service 中进行分析和存储。
---
<!--
@@ -23,38 +30,34 @@ title: google-cloud-logging
## 描述
-`google-cloud-logging` 插件用于将 `Apache APISIX` 的请求日志发送到 [Google Cloud Logging Service](https://cloud.google.com/logging/)。
-
-该插件提供了将请求的日志数据以批处理队列的形式推送到谷歌云日志服务的功能。
-
-有关 `Apache APISIX` 的 `Batch-Processor` 的更多信息，请参考：
-[Batch-Processor](../batch-processor.md)
+`google-cloud-logging` 插件可用于将请求日志发送到 [Google Cloud Logging Service](https://cloud.google.com/logging/) 进行分析和存储。
## 属性
-| 名称 | 是否必需 | 默认值 | 描述 |
-| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
-| auth_config | 半可选 | | 必须配置 `auth_config` 或 `auth_file` 之一 |
-| auth_config.private_key | 必选 | | 谷歌服务帐号的私钥参数 |
-| auth_config.project_id | 必选 | | 谷歌服务帐号的项目 ID |
-| auth_config.token_uri | 可选 | https://oauth2.googleapis.com/token | 请求谷歌服务帐户的令牌的 URI |
-| auth_config.entries_uri | 可选 | https://logging.googleapis.com/v2/entries:write | 谷歌日志服务写入日志条目的 API |
-| auth_config.scopes | 可选 | ["https://www.googleapis.com/auth/logging.read","https://www.googleapis.com/auth/logging.write","https://www.googleapis.com/auth/logging.admin","https://www.googleapis.com/auth/cloud-platform"] | 谷歌服务账号的访问范围，参考：[OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes#logging) |
-| auth_file | 半可选 | | 谷歌服务账号 JSON 文件的路径（必须配置 `auth_config` 或 `auth_file` 之一）|
-| ssl_verify | 可选 | true | 启用 `SSL` 验证，配置根据 [OpenResty 文档](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) 选项 |
-| resource | 可选 | {"type": "global"} | 谷歌监控资源，参考： [MonitoredResource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource) |
-| log_id | 可选 | apisix.apache.org%2Flogs | 谷歌日志 ID，参考： [LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry) |
+| 名称 | 必选项 | 默认值 | 描述 |
+| ----------------------- | -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| auth_config | 是 | | `auth_config` 和 `auth_file` 必须配置一个。 |
+| auth_config.private_key | 是 | | 谷歌服务帐号的私钥参数。 |
+| auth_config.project_id | 是 | | 谷歌服务帐号的项目 ID。 |
+| auth_config.token_uri | 是 | https://oauth2.googleapis.com/token | 请求谷歌服务帐户的令牌的 URI。 |
+| auth_config.entries_uri | 否 | https://logging.googleapis.com/v2/entries:write | 谷歌日志服务写入日志条目的 API。 |
+| auth_config.scopes | 否 | | 谷歌服务账号的访问范围，可参考 [OAuth 2.0 Scopes for Google APIs](https://developers.google.com/identity/protocols/oauth2/scopes#logging)。可选项："https://www.googleapis.com/auth/logging.read"、"https://www.googleapis.com/auth/logging.write"、"https://www.googleapis.com/auth/logging.admin"、"https://www.googleapis.com/auth/cloud-platform"。|
+| auth_file | 是 | | `auth_config` 和 `auth_file` 必须配置一个。 |
+| ssl_verify | 否 | true | 当设置为 `true` 时，启用 `SSL` 验证。 |
+| resource | 否 | {"type": "global"} | 谷歌监控资源，请参考 [MonitoredResource](https://cloud.google.com/logging/docs/reference/v2/rest/v2/MonitoredResource)。 |
+| log_id | 否 | apisix.apache.org%2Flogs | 谷歌日志 ID，请参考 [LogEntry](https://cloud.google.com/logging/docs/reference/v2/rest/v2/LogEntry)。 |
-本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
+该插件支持使用批处理器来聚合并批量处理条目（日志和数据）。这样可以避免该插件频繁地提交数据。默认情况下每 `5` 秒钟或队列中的数据达到 `1000` 条时，批处理器会自动提交数据，如需了解更多信息或自定义配置，请参考 [Batch Processor](../batch-processor.md#配置)。
-## 如何开启
+## 启用插件
-下面例子展示了如何为指定路由开启 `google-cloud-logging` 插件。
+以下示例展示了如何在指定路由上启用该插件：
-### 完整配置
+**完整配置**
```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": {
"google-cloud-logging": {
@@ -89,10 +92,11 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-### 最小化配置
+**最小化配置**
```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": {
"google-cloud-logging": {
@@ -114,25 +118,27 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
-* 向配置 `google-cloud-logging` 插件的路由发送请求
+你可以通过以下命令向 APISIX 发出请求：
```shell
-$ curl -i http://127.0.0.1:9080/hello
+curl -i http://127.0.0.1:9080/hello
+```
+
+```
HTTP/1.1 200 OK
...
hello, world
```
-* 登录谷歌云日志服务，查看日志
-
-[Google Cloud Logging Service](https://console.cloud.google.com/logs/viewer)
+访问成功后，你可以登录 [Google Cloud Logging Service](https://console.cloud.google.com/logs/viewer) 查看相关日志。
## 禁用插件
-禁用 `google-cloud-logging` 插件非常简单，只需将 `google-cloud-logging` 对应的 `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 '
{
"uri": "/hello",
"plugins": {},
diff --git a/docs/zh/latest/plugins/http-logger.md b/docs/zh/latest/plugins/http-logger.md
index ca874ef21..bbd0f8b5b 100644
--- a/docs/zh/latest/plugins/http-logger.md
+++ b/docs/zh/latest/plugins/http-logger.md
@@ -47,11 +47,7 @@ description: 本文介绍了 API 网关 Apache APISIX 的 http-logger 插件。
| concat_method | string | 否 | "json" | ["json", "new_line"] | 枚举类型： **json**：对所有待发日志使用 `json.encode` 编码。**new_line**：对每一条待发日志单独使用 `json.encode` 编码并使用 `\n` 连接起来。 |
| ssl_verify | boolean | 否 | false | [false, true] | 当设置为 `true` 时验证证书。 |
-:::note 注意
-
-本插件支持使用批处理器来聚合并批量处理条目（日志和数据）。这样可以避免该插件频繁地提交数据。默认情况下每 `5` 秒钟或队列中的数据达到 `1000` 条时，批处理器会自动提交数据，如需了解更多信息或自定义配置，请参考 [Batch Processor](../batch-processor.md#配置)。
-
-:::
+该插件支持使用批处理器来聚合并批量处理条目（日志和数据）。这样可以避免该插件频繁地提交数据。默认情况下每 `5` 秒钟或队列中的数据达到 `1000` 条时，批处理器会自动提交数据，如需了解更多信息或自定义配置，请参考 [Batch Processor](../batch-processor.md#配置)。
## 插件元数据
diff --git a/docs/zh/latest/plugins/loggly.md b/docs/zh/latest/plugins/loggly.md
new file mode 100644
index 000000000..4ec8d4b5c
--- /dev/null
+++ b/docs/zh/latest/plugins/loggly.md
@@ -0,0 +1,166 @@
+---
+title: loggly
+keywords:
+ - APISIX
+ - API 网关
+ - Plugin
+ - SolarWinds Loggly
+description: API 网关 Apache APISIX loggly 插件可用于将日志转发到 SolarWinds Loggly 进行分析和存储。
+---
+
+<!--
+#
+# Licensed to the Apache Software Foundation (ASF) under one or more
+# contributor license agreements. See the NOTICE file distributed with
+# this work for additional information regarding copyright ownership.
+# The ASF licenses this file to You under the Apache License, Version 2.0
+# (the "License"); you may not use this file except in compliance with
+# the License. You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+-->
+
+## 描述
+
+`loggly` 插件可用于将日志转发到 [SolarWinds Loggly](https://www.solarwinds.com/loggly) 进行分析和存储。
+
+当启用插件时，APISIX 会将请求上下文信息序列化为符合 [Loggly Syslog](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/streaming-syslog-without-using-files.htm?cshid=loggly_streaming-syslog-without-using-files) 的数据格式，即具有 [RFC5424](https://datatracker.ietf.org/doc/html/rfc5424) 兼容标头的 Syslog。
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 描述 |
+|------------------------|---------------|----------|---------|---------------------------------------------------------------------------------------------------------------------------------------------------|
+| customer_token | string | 是 | | 将日志发送到 Loggly 时使用的唯一标识符，以确保将日志发送到正确的组织帐户。 |
+| severity | string (enum) | 否 | INFO | Syslog 日志事件的严重性级别。 包括：`DEBUG`、`INFO`、`NOTICE`、`WARNING`、`ERR`、`CRIT`、`ALERT` 和 `EMEGR`。 |
+| severity_map | object | 否 | nil | 一种将上游 HTTP 响应代码映射到 Syslog 中的方法。 `key-value`，其中 `key` 是 HTTP 响应代码，`value`是 Syslog 严重级别。例如`{"410": "CRIT"}`。 |
+| tags | array | 否 | | 元数据将包含在任何事件日志中，以帮助进行分段和过滤。 |
+| include_req_body | boolean | 否 | false | 当设置为 `true` 时，包含请求体。**注意**：如果请求体无法完全存放在内存中，由于 NGINX 的限制，APISIX 无法将它记录下来。 |
+| include_resp_body | boolean | 否 | false | 当设置为 `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#配置)。
+
+如果要生成用户令牌，请在 Loggly 系统中的 `<your assigned subdomain>/loggly.com/tokens` 设置，或者在系统中单击 `Logs > Source setup > Customer tokens`。
+
+## 插件元数据设置
+
+你还可以通过插件元数据配置插件。详细配置如下：
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述 |
+|------------|---------|-------|----------------------|--------------------------------|---------------------------------------------------------------------|
+| host | string | 否 | "logs-01.loggly.com" | | 发送日志的主机的端点。 |
+| port | integer | 否 | 514 | | 要连接的 Loggly 端口。 仅用于 `syslog` 协议。 |
+| timeout | integer | 否 | 5000 | | 发送数据请求超时时间（以毫秒为单位）。 |
+| protocol | string | 否 | "syslog" | [ "syslog", "http", "https" ] | 将日志发送到 Loggly 的协议。 |
+| log_format | object | 否 | nil | | 以 JSON 格式的键值对来声明日志格式。对于值部分，仅支持字符串。如果是以 `$` 开头，则表明是要获取 [APISIX 变量](../../../en/latest/apisix-variable.md) 或 [NGINX 内置变量](http://nginx.org/en/docs/varindex.html)。 |
+
+APISIX 支持 [Syslog](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/streaming-syslog-without-using-files.htm)、[HTTP/S](https://documentation.solarwinds.com/en/success_center/loggly/content/admin/http-bulk-endpoint.htm)（批量端点）协议将日志事件发送到 Loggly。**默认情况下 `protocol` 的值为 `syslog`**。该协议允许你通过一些细粒度的控制（基于上游 HTTP 响应代码的日志严重性映射）发送符合 RFC5424 的系统日志事件。但是 HTTP/S 批量端点非常适合以更快的传输速度发送更大量的日志事件。
+
+:::note 注意
+
+Syslog 协议允许你发送符合 RFC5424 的 syslog 事件并进行细粒度控制。但是在以快速传输速度发送大量日志时，使用 HTTP/S 批量端点会更好。你可以通过以下方式更新元数据以更新使用的协议：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/plugin_metadata/loggly \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "protocol": "http"
+}'
+```
+
+:::
+
+## 启用插件
+
+以下示例展示了如何在指定路由上启用该插件：
+
+**完整配置**
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins":{
+ "loggly":{
+ "customer_token":"0e6fe4bf-376e-40f4-b25f-1d55cb29f5a2",
+ "tags":["apisix", "testroute"],
+ "severity":"info",
+ "severity_map":{
+ "503": "err",
+ "410": "alert"
+ },
+ "buffer_duration":60,
+ "max_retry_count":0,
+ "retry_delay":1,
+ "inactive_timeout":2,
+ "batch_max_size":10
+ }
+ },
+ "upstream":{
+ "type":"roundrobin",
+ "nodes":{
+ "127.0.0.1:80":1
+ }
+ },
+ "uri":"/index.html"
+}'
+```
+
+**最小化配置**
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins":{
+ "loggly":{
+ "customer_token":"0e6fe4bf-376e-40f4-b25f-1d55cb29f5a2",
+ }
+ },
+ "upstream":{
+ "type":"roundrobin",
+ "nodes":{
+ "127.0.0.1:80":1
+ }
+ },
+ "uri":"/index.html"
+}'
+```
+
+## 测试插件
+
+你可以通过以下命令向 APISIX 发出请求：
+
+```shell
+curl -i http://127.0.0.1:9080/index.html
+```
+
+发出请求后，你就可以在 Loggly 仪表盘上查看相关日志：
+
+
+
+## 禁用插件
+
+当你需要禁用该插件时，可以通过如下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+
+```shell
+curl http://127.0.0.1:9080/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/index.html",
+ "plugins": {},
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:80": 1
+ }
+ }
+}'
+```
diff --git a/docs/zh/latest/plugins/splunk-hec-logging.md b/docs/zh/latest/plugins/splunk-hec-logging.md
index 8c9d09983..95b3ebe1a 100644
--- a/docs/zh/latest/plugins/splunk-hec-logging.md
+++ b/docs/zh/latest/plugins/splunk-hec-logging.md
@@ -1,5 +1,12 @@
---
title: splunk-hec-logging
+keywords:
+ - APISIX
+ - API 网关
+ - 插件
+ - Splunk
+ - 日志
+description: API 网关 Apache APISIX 的 splunk-hec-logging 插件可用于将请求日志转发到 Splunk HTTP 事件收集器（HEC）中进行分析和存储。
---
<!--
@@ -23,32 +30,32 @@ title: splunk-hec-logging
## 描述
-`splunk-hec-logging` 插件用于将 `Apache APISIX` 的请求日志转发到 `Splunk HTTP 事件收集器（HEC）` 中进行分析和存储，启用该插件后 `Apache APISIX` 将在 `Log Phase` 获取请求上下文信息并序列化为 [Splunk Event Data 格式](https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata) 后提交到批处理队列中，当触发批处理队列每批次最大处理容量或刷新缓冲区的最大时间时会将队列中的数据提交到 `Splunk HEC` 中。
+`splunk-hec-logging` 插件可用于将请求日志转发到 Splunk HTTP 事件收集器（HEC）中进行分析和存储。
-有关 `Apache APISIX` 的 `Batch-Processor` 的更多信息，请参考：
-[Batch-Processor](../batch-processor.md)
+启用该插件后，APISIX 将在 `Log Phase` 获取请求上下文信息，并将其序列化为 [Splunk Event Data 格式](https://docs.splunk.com/Documentation/Splunk/latest/Data/FormateventsforHTTPEventCollector#Event_metadata) 后提交到批处理队列中，当触发批处理队列每批次最大处理容量或刷新缓冲区的最大时间时会将队列中的数据提交到 `Splunk HEC` 中。
## 属性
-| 名称 | 是否必需 | 默认值 | 描述 |
-| ----------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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 | 启用 `SSL` 验证，参考：[OpenResty 文档](https://github.com/openresty/lua-nginx-module#tcpsocksslhandshake) |
+| 名称 | 必选项 | 默认值 | 描述 |
+| ------------------ | ------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 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` 验证。 |
-本插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认设置情况下批处理器会每 `5` 秒钟或队列中的数据达到 `1000` 条时提交数据，如需了解或自定义批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置) 配置部分。
+本插件支持使用批处理器来聚合并批量处理条目（日志和数据）。这样可以避免该插件频繁地提交数据。默认情况下每 `5` 秒钟或队列中的数据达到 `1000` 条时，批处理器会自动提交数据，如需了解更多信息或自定义配置，请参考 [Batch-Processor](../batch-processor.md#配置)。
-## 如何开启
+## 启用插件
-下面例子展示了如何为指定路由开启 `splunk-hec-logging` 插件。
+以下示例展示了如何在指定路由上启用该插件：
-### 完整配置
+**完整配置**
```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":{
"splunk-hec-logging":{
@@ -75,10 +82,11 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
}'
```
-### 最小化配置
+**最小化配置**
```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":{
"splunk-hec-logging":{
@@ -100,25 +108,29 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1 -H 'X-API-KEY: edd1c9f034335f13
## 测试插件
-* 向配置 `splunk-hec-logging` 插件的路由发送请求
+你可以通过以下命令向 APISIX 发出请求：
```shell
-$ curl -i http://127.0.0.1:9080/splunk.do?q=hello
+curl -i http://127.0.0.1:9080/splunk.do?q=hello
+```
+
+```
HTTP/1.1 200 OK
...
hello, world
```
-* 登录 Splunk 控制台检索查看日志
+访问成功后，你可以登录 Splunk 控制台检索查看日志：
## 禁用插件
-禁用 `splunk-hec-logging` 插件非常简单，只需将 `splunk-hec-logging` 对应的 `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 '
{
"uri": "/hello",
"plugins": {},