docs(plugin): refactor proxy-mirror.md (#7667)

* docs: update proxy-mirror.md
apache · Aug 17, 2022 · c437f76 · c437f76
1 parent 1913ac2
commit c437f76
Show file tree

Hide file tree

Showing 2 changed files with 99 additions and 65 deletions.
diff --git a/docs/en/latest/plugins/proxy-mirror.md b/docs/en/latest/plugins/proxy-mirror.md
@@ -2,10 +2,9 @@
 title: proxy-mirror
 keywords:
   - APISIX
-  - Plugin
+  - API Gateway
   - Proxy Mirror
-  - proxy-mirror
-description: This document contains information about the Apache APISIX proxy-mirror Plugin.
+description: This document describes the information about the Apache APISIX proxy-mirror Plugin, you can use it to mirror the client requests.
 ---
 <!--
 #
@@ -28,7 +27,7 @@ description: This document contains information about the Apache APISIX proxy-mi
 
 ## Description
 
-The `proxy-mirror` Plugin can be used to mirror client requests.
+The `proxy-mirror` Plugin can be used to mirror client requests. Traffic mirroring duplicates the real online traffic to the mirroring service. This enables specific analysis of the online traffic or request content without interrupting the online service.
 
 :::note
 
@@ -66,7 +65,8 @@ plugin_attr:
 You can enable the Plugin on a specific Route as shown below:
 
 ```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": {
         "proxy-mirror": {
@@ -83,26 +83,29 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f1
 }'
 ```
 
-## Example usage
+### Specify the timeout for mirror subrequests
 
-Once you have configured the Plugin as shown above, the requests made will be mirrored to the configured host.
+We can specify the `timeout` for subrequests in `plugin_attr` in `conf/config.yaml`. This is useful in connection reuse scenarios when mirroring traffic to a very slow backend service.
 
-```shell
-curl http://127.0.0.1:9080/hello -i
-```
+Since mirror requests are implemented as sub-requests, delays in sub-requests will block the original request until the sub-requests are completed. So you can configure the timeout time to protect the sub-requests from excessive delays that affect the original requests.
 
-```shell
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Content-Length: 12
-Connection: keep-alive
-Server: APISIX web server
-Date: Wed, 18 Mar 2020 13:01:11 GMT
-Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| connect | string | 60s | Connection timeout for mirror request to upstream. |
+| read | string | 60s | The time that APISIX maintains the connection with the mirror server; if APISIX does not receive a response from the mirror server within this time, the connection is closed. |
+| send | string | 60s | The time that APISIX maintains the connection with the mirror server; if APISIX does not send a request within this time, the connection is closed. |
 
-hello world
+```yaml
+plugin_attr:
+  proxy-mirror:
+    timeout:
+      connect: 2000ms
+      read: 2000ms
+      send: 2000ms
 ```
 
+## Example usage
+
 :::tip
 
 For testing you can create a test server by running:
@@ -113,12 +116,25 @@ python -m http.server 9797
 
 :::
 
+Once you have configured the Plugin as shown above, the requests made will be mirrored to the configured host.
+
+```shell
+curl http://127.0.0.1:9080/hello -i
+```
+
+```shell
+HTTP/1.1 200 OK
+...
+hello world
+```
+
 ## Disable Plugin
 
 To disable the `proxy-mirror` 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: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/proxy-mirror.md b/docs/zh/latest/plugins/proxy-mirror.md
@@ -1,5 +1,10 @@
 ---
 title: proxy-mirror
+keywords:
+  - APISIX
+  - API 网关
+  - Proxy Mirror
+description: 本文介绍了 Apache APISIX proxy-mirror 插件的相关操作，你可以使用此插件镜像客户端的请求。
 ---
 
 <!--
@@ -23,26 +28,29 @@ title: proxy-mirror
 
 ## 描述
 
-代理镜像插件，该插件提供了镜像客户端请求的能力。
+`proxy-mirror` 插件提供了镜像客户端请求的能力。流量镜像是将线上真实流量拷贝到镜像服务中，以便在不影响线上服务的情况下，对线上流量或请求内容进行具体的分析。
 
-注：镜像请求返回的响应会被忽略。
+:::note 注意
+
+镜像请求返回的响应会被忽略。
+
+:::
 
 ## 参数
 
 | 名称 | 类型   | 必选项 | 默认值 | 有效值 | 描述                                                                                                    |
 | ---- | ------ | ------ | ------ | ------ | ------------------------------------------------------------------------------------------------------- |
-| host | string | 必须   |        |        | 指定镜像服务地址，例如：http://127.0.0.1:9797（地址中需要包含 schema ：http 或 https，不能包含 path 部分）|
-| path | string | 可选   |        |        | 指定镜像请求的路径。如不指定，当前路径将被使用。 |
-| sample_ratio | number | 可选    | 1       |  [0.00001, 1]     | 镜像请求采样率 |
-
-## 示例
+| host | string | 是   |        |        | 指定镜像服务的地址，地址中需要包含 `schema`（`http` 或 `https`），但不能包含 `path` 部分。例如 `http://127.0.0.1:9797`。 |
+| path | string | 否   |        |        | 指定镜像请求的路径。如果不指定，则默认会使用当前路径。 |
+| sample_ratio | number | 否    | 1       |  [0.00001, 1]     | 镜像请求的采样率。当设置为 `1` 时为全采样。 |
 
-### 启用插件
+## 启用插件
 
-示例 1：为特定路由启用 `proxy-mirror` 插件：
+以下示例展示了如何在指定路由上启用 `proxy-mirror` 插件：
 
 ```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": {
         "proxy-mirror": {
@@ -59,29 +67,60 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f1
 }'
 ```
 
-测试：
+### 指定镜像子请求的超时时间
+
+我们可以在 `conf/config.yaml` 文件内的 `plugin_attr` 中指定子请求的超时时间。由于镜像请求是以子请求的方式实现，子请求的延迟将会导致原始请求阻塞，直到子请求完成，才可以恢复正常。因此可以配置超时时间，来避免子请求出现过大的延迟而影响原始请求。
+
+| 名称 | 类型 | 默认值 | 描述 |
+| --- | --- | --- | --- |
+| connect | string | 60s | 镜像请求到上游的连接超时时间。 |
+| read | string | 60s | APISIX 与镜像服务器维持连接的时间；如果在该时间内，APISIX 没有收到镜像服务器的响应，则关闭连接。 |
+| send | string | 60s | APISIX 与镜像服务器维持连接的时间；如果在该时间内，APISIX 没有发送请求，则关闭连接。 |
+
+```yaml
+plugin_attr:
+  proxy-mirror:
+    timeout:
+      connect: 2000ms
+      read: 2000ms
+      send: 2000ms
+```
+
+## 测试插件
+
+:::tip 提示
+
+因为指定的镜像地址是 `127.0.0.1:9797`，所以验证此插件是否正常工作需要在端口为 `9797` 的服务上确认。
+
+我们可以通过 `python` 启动一个简单的服务：
 
 ```shell
-$ curl http://127.0.0.1:9080/hello -i
-HTTP/1.1 200 OK
-Content-Type: application/octet-stream
-Content-Length: 12
-Connection: keep-alive
-Server: APISIX web server
-Date: Wed, 18 Mar 2020 13:01:11 GMT
-Last-Modified: Thu, 20 Feb 2020 14:21:41 GMT
+python -m http.server 9797
+```
 
-hello world
+:::
+
+按上述配置启用插件后，使用 `curl` 命令请求该路由，请求将被镜像到所配置的主机上：
+
+```shell
+curl http://127.0.0.1:9080/hello -i
 ```
 
-> 由于指定的 mirror 地址是 127.0.0.1:9797，所以验证此插件是否已经正常工作需要在端口为 9797 的服务上确认，例如，我们可以通过 python 启动一个简单的 server： python -m SimpleHTTPServer 9797。
+返回的 HTTP 响应头中如果带有 `200` 状态码，则表示插件生效：
+
+```shell
+HTTP/1.1 200 OK
+...
+hello world
+```
 
-### 禁用插件
+## 禁用插件
 
-移除插件配置中相应的 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": {},
@@ -93,24 +132,3 @@ curl http://127.0.0.1:9080/apisix/admin/routes/1  -H 'X-API-KEY: edd1c9f034335f1
     }
 }'
 ```
-
-这时该插件已被禁用。
-
-## 指定 mirror 子请求的超时时间
-
-我们可以在 `conf/config.yaml` 的 `plugin_attr` 中指定子请求的超时时间。这在连接复用的场景下 mirror 流量到一个非常慢的后端服务时非常有用。
-
-| 名称 | 类型 | 默认值 | 描述 |
-| --- | --- | --- | --- |
-| connect | string | 60s | 镜像请求到上游的连接超时时间 |
-| read | string | 60s | 镜像请求到上游的读超时时间 |
-| send | string | 60s | 镜像请求到上游的写超时时间 |
-
-```yaml
-plugin_attr:
-  proxy-mirror:
-    timeout:
-      connect: 2000ms
-      read: 2000ms
-      send: 2000ms
-```