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 73ca5fe23 docs: add doc for tencent cloud cls (#7856)
73ca5fe23 is described below
commit 73ca5fe233e7aa50f62c26c0040bd1e3e6d86f48
Author: ychensha <[email protected]>
AuthorDate: Thu Sep 15 09:38:18 2022 +0800
docs: add doc for tencent cloud cls (#7856)
* add doc for tencent cloud cls
---
docs/en/latest/config.json | 3 +-
docs/en/latest/plugins/tencent-cloud-cls.md | 142 +++++++++++++++++++++++++++
docs/zh/latest/README.md | 2 +-
docs/zh/latest/config.json | 3 +-
docs/zh/latest/plugins/tencent-cloud-cls.md | 147 ++++++++++++++++++++++++++++
5 files changed, 294 insertions(+), 3 deletions(-)
diff --git a/docs/en/latest/config.json b/docs/en/latest/config.json
index fcb04951f..3214b61fc 100644
--- a/docs/en/latest/config.json
+++ b/docs/en/latest/config.json
@@ -150,7 +150,8 @@
"plugins/splunk-hec-logging",
"plugins/file-logger",
"plugins/loggly",
- "plugins/elasticsearch-logger"
+ "plugins/elasticsearch-logger",
+ "plugins/tencent-cloud-cls"
]
}
]
diff --git a/docs/en/latest/plugins/tencent-cloud-cls.md
b/docs/en/latest/plugins/tencent-cloud-cls.md
new file mode 100644
index 000000000..fcdc6d0f5
--- /dev/null
+++ b/docs/en/latest/plugins/tencent-cloud-cls.md
@@ -0,0 +1,142 @@
+---
+title: tencent-cloud-cls
+keywords:
+ - APISIX
+ - API Gateway
+ - Plugin
+ - CLS
+ - Tencent Cloud
+description: This document contains information about the Apache APISIX
tencent-cloud-cls Plugin.
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## Description
+
+The `tencent-cloud-cls` Plugin uses [TencentCloud
CLS](https://cloud.tencent.com/document/product/614)API to forward APISIX logs
to your topic.
+
+## Attributes
+
+| Name | Type | Required | Default | Valid values |
Description
|
+| ----------------- | ------- | -------- |---------| -------------
|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| cls_host | string | Yes | | | CLS API
host，please refer [Uploading Structured
Logs](https://www.tencentcloud.com/document/api/614/16873).
|
+| cls_topic | string | Yes | | | topic id
of CLS.
|
+| secret_id | string | Yes | | | SecretId
of your API key.
|
+| secret_key | string | Yes | | | SecretKey
of your API key.
|
+| sample_ratio | number | No | 1 | [0.00001, 1] | How often
to sample the requests. Setting to `1` will sample all requests.
|
+| include_req_body | boolean | No | 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_resp_body | boolean | No | false | [false, true] | When set
to `true` includes the response body in the log.
|
+| global_tag | object | No | | | kv pairs
in JSON，send with each log.
|
+
+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
+
+You can also set the format of the logs by configuring the Plugin metadata.
The following configurations are available:
+
+| Name | Type | Required | Default
| Description
|
+| ---------- | ------ | -------- |
----------------------------------------------------------------------------- |
-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
|
+| log_format | object | False | {"host": "$host", "@timestamp":
"$time_iso8601", "client_ip": "$remote_addr"} | 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 `$`. |
+
+:::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 `tencent-cloud-cls` Plugin.
+
+:::
+
+The example below shows how you can configure through the Admin API:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tencent-cloud-cls \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "log_format": {
+ "host": "$host",
+ "@timestamp": "$time_iso8601",
+ "client_ip": "$remote_addr"
+ }
+}'
+```
+
+With this configuration, your logs would be formatted as shown below:
+
+```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"}
+```
+
+## Enabling the Plugin
+
+The example below shows how you can enable the Plugin on a specific Route:
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "tencent-cloud-cls": {
+ "cls_host": "ap-guangzhou.cls.tencentyun.com",
+ "cls_topic": "${your CLS topic name}",
+ "global_tag": {
+ "module": "cls-logger",
+ "server_name": "YourApiGateWay"
+ },
+ "include_req_body": true,
+ "include_resp_body": true,
+ "secret_id": "${your secret id}",
+ "secret_key": "${your secret key}"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "uri": "/hello"
+}'
+```
+
+## Example usage
+
+Now, if you make a request to APISIX, it will be logged in your cls topic:
+
+```shell
+curl -i http://127.0.0.1:9080/hello
+```
+
+## Disable Plugin
+
+To disable this Plugin, you can delete the corresponding JSON configuration
from the Plugin configuration. APISIX will automatically reload and you do not
have to restart for this to take effect.
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "uri": "/hello",
+ "plugins": {},
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
diff --git a/docs/zh/latest/README.md b/docs/zh/latest/README.md
index 4c5f6004c..3e1ef754b 100644
--- a/docs/zh/latest/README.md
+++ b/docs/zh/latest/README.md
@@ -143,7 +143,7 @@ A/B 测试、金丝雀发布（灰度发布）、蓝绿部署、限流限速、
- 高性能：在单核上 QPS 可以达到 18k，同时延迟只有 0.2 毫秒。
- [故障注入](plugins/fault-injection.md)
- [REST Admin API](admin-api.md)：使用 REST Admin API 来控制 Apache APISIX，默认只允许
127.0.0.1 访问，你可以修改 `conf/config.yaml` 中的 `allow_admin` 字段，指定允许调用 Admin API 的 IP
列表。同时需要注意的是，Admin API 使用 key auth 来校验调用者身份，**在部署前需要修改 `conf/config.yaml` 中的
`admin_key` 字段，来保证安全。**
- - 外部日志记录器：将访问日志导出到外部日志管理工具。（[HTTP Logger](plugins/http-logger.md)、[TCP
Logger](plugins/tcp-logger.md)、[Kafka Logger](plugins/kafka-logger.md)、[UDP
Logger](plugins/udp-logger.md)、[RocketMQ
Logger](plugins/rocketmq-logger.md)、[SkyWalking
Logger](plugins/skywalking-logger.md)、[Alibaba Cloud
Logging(SLS)](plugins/sls-logger.md)、[Google Cloud
Logging](plugins/google-cloud-logging.md)、[Splunk HEC
Logging](plugins/splunk-hec-logging.md)、[File
Logger](plugins/file-logger.md)、[Elasticsearch L [...]
+ - 外部日志记录器：将访问日志导出到外部日志管理工具。（[HTTP Logger](plugins/http-logger.md)、[TCP
Logger](plugins/tcp-logger.md)、[Kafka Logger](plugins/kafka-logger.md)、[UDP
Logger](plugins/udp-logger.md)、[RocketMQ
Logger](plugins/rocketmq-logger.md)、[SkyWalking
Logger](plugins/skywalking-logger.md)、[Alibaba Cloud
Logging(SLS)](plugins/sls-logger.md)、[Google Cloud
Logging](plugins/google-cloud-logging.md)、[Splunk HEC
Logging](plugins/splunk-hec-logging.md)、[File
Logger](plugins/file-logger.md)、[Elasticsearch L [...]
- [Helm charts](https://github.com/apache/apisix-helm-chart)
- **高度可扩展**
diff --git a/docs/zh/latest/config.json b/docs/zh/latest/config.json
index 5d68a50ee..743e647e8 100644
--- a/docs/zh/latest/config.json
+++ b/docs/zh/latest/config.json
@@ -154,7 +154,8 @@
"plugins/splunk-hec-logging",
"plugins/file-logger",
"plugins/loggly",
- "plugins/elasticsearch-logger"
+ "plugins/elasticsearch-logger",
+ "plugins/tencent-cloud-cls"
]
}
]
diff --git a/docs/zh/latest/plugins/tencent-cloud-cls.md
b/docs/zh/latest/plugins/tencent-cloud-cls.md
new file mode 100644
index 000000000..32a2b9e5c
--- /dev/null
+++ b/docs/zh/latest/plugins/tencent-cloud-cls.md
@@ -0,0 +1,147 @@
+---
+title: tencent-cloud-cls
+keywords:
+ - APISIX
+ - API 网关
+ - Plugin
+ - CLS
+ - 腾讯云
+description: API 网关 Apache APISIX tencent-cloud-cls
插件可用于将日志推送到[腾讯云日志服务](https://cloud.tencent.com/document/product/614)。
+---
+
+<!--
+#
+# 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.
+#
+-->
+
+## 描述
+
+`tencent-cloud-cls` 插件可用于将 APISIX
日志使用[腾讯云日志服务](https://cloud.tencent.com/document/product/614) API 推送到您的日志主题。
+
+## 属性
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+| ----------------- | ------- | ------ |-------| ------------
|------------------------------------------------------------------------------|
+| cls_host | string | 是 | | | CLS API
域名，参考[使用 API 上传日志](https://cloud.tencent.com/document/api/614/16873)。|
+| cls_topic | string | 是 | | | CLS 日志主题 id。
|
+| secret_id | string | 是 | | | 云 API 密钥的 id。
|
+| secret_key | string | 是 | | | 云 API 密钥的 key。
|
+| sample_ratio | number | 否 | 1 | [0.00001, 1] | 采样的比例。设置为 `1`
时，将对所有请求进行采样。 |
+| include_req_body | boolean | 否 | false | [false, true]| 当设置为 `true`
时，日志中将包含请求体。 |
+| include_resp_body | boolean | 否 | false | [false, true]| 当设置为 `true`
时，日志中将包含响应体。 |
+| global_tag | object | 否 | | | kv 形式的 JSON
数据，可以写入每一条日志，便于在 CLS 中检索。 |
+
+该插件支持使用批处理器来聚合并批量处理条目（日志/数据）。这样可以避免插件频繁地提交数据，默认情况下批处理器每 `5` 秒钟或队列中的数据达到 `1000`
条时提交数据，如需了解批处理器相关参数设置，请参考 [Batch-Processor](../batch-processor.md#配置)。
+
+## 插件元数据
+
+| 名称 | 类型 | 必选项 | 默认值 | 有效值 | 描述
|
+| ---------------- | ------- | ------ | ------------- | ------- |
------------------------------------------------ |
+| 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)。 |
+
+:::info 重要
+
+该设置全局生效。如果指定了 `log_format`，则所有绑定 `tencent-cloud-cls` 的路由或服务都将使用该日志格式。
+
+:::
+
+以下示例展示了如何通过 Admin API 配置插件元数据：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/plugin_metadata/tencent-cloud-cls \
+-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"}
+```
+
+## 启用插件
+
+你可以通过以下命令在指定路由中启用该插件：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "plugins": {
+ "tencent-cloud-cls": {
+ "cls_host": "ap-guangzhou.cls.tencentyun.com",
+ "cls_topic": "${your CLS topic name}",
+ "global_tag": {
+ "module": "cls-logger",
+ "server_name": "YourApiGateWay"
+ },
+ "include_req_body": true,
+ "include_resp_body": true,
+ "secret_id": "${your secret id}",
+ "secret_key": "${your secret key}"
+ }
+ },
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ },
+ "uri": "/hello"
+}'
+```
+
+## 测试插件
+
+现在你可以向 APISIX 发起请求：
+
+```shell
+curl -i http://127.0.0.1:9080/hello
+```
+
+```
+HTTP/1.1 200 OK
+...
+hello, world
+```
+
+## 禁用插件
+
+当你需要禁用该插件时，可通过以下命令删除相应的 JSON 配置，APISIX 将会自动重新加载相关配置，无需重启服务：
+
+```shell
+curl http://127.0.0.1:9180/apisix/admin/routes/1 \
+-H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
+{
+ "methods": ["GET"],
+ "uri": "/hello",
+ "plugins": {},
+ "upstream": {
+ "type": "roundrobin",
+ "nodes": {
+ "127.0.0.1:1980": 1
+ }
+ }
+}'
+```
