You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "Yilialinn (via GitHub)" <gi...@apache.org> on 2025/02/27 03:56:49 UTC

Re: [PR] docs: improve `proxy-mirror` plugin docs [apisix]

Yilialinn commented on code in PR #11912:
URL: https://github.com/apache/apisix/pull/11912#discussion_r1972802150


##########
docs/en/latest/plugins/proxy-mirror.md:
##########
@@ -25,47 +26,48 @@ description: This document describes the information about the Apache APISIX pro
 #
 -->
 
-## Description
-
-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.
+<head>
+  <link rel="canonical" href="https://docs.api7.ai/hub/proxy-mirror" />
+</head>
 
-:::note
+## Description
 
-The response returned by the mirror request is ignored.
+The `proxy-mirror` Plugin duplicates ingress traffic to APISIX and forwards them to a designated upstream, without interrupting the regular services. You can configure the Plugin to mirror all traffic or only a portion. The mechanism benefits a few use cases, including troubleshooting, security inspection, analytics, and more.
 
-:::
+Note that APISIX ignores any response from the Upstream host receiving mirrored traffic.
 
 ## Attributes
 
 | Name         | Type   | Required | Default | Valid values | Description                                                                                                               |
 |--------------|--------|----------|---------|--------------|---------------------------------------------------------------------------------------------------------------------------|
-| host         | string | True     |         |              | Address of the mirror service. It needs to contain the scheme (`http(s)` or `grpc(s)`) but without the path. For example, `http://127.0.0.1:9797`. |
-| path         | string | False    |         |              | Path of the mirror request. If unspecified, current path will be used. If it is for mirroring grpc traffic, this option is no longer applicable.                                                   |
-| path_concat_mode | string | False   |   replace     | ["replace", "prefix"]       | If the path of a mirror request is specified, set the concatenation mode of request paths. The `replace` mode will directly use `path` as the path of the mirror request. The `prefix` mode will use the `path` + `source request URI` as the path to the mirror request. If it is for mirroring grpc traffic, this option is no longer applicable too. |
-| sample_ratio | number | False    | 1       | [0.00001, 1] | Ratio of the requests that will be mirrored.                                                                              |
+| host         | string | True     |         |              | Address of the host to forward the mirrored traffic to. The address should contain the scheme but without the path, such as `http://127.0.0.1:8081`.  |
+| path         | string | False    |         |              | Path of the host to forward the mirrored traffic to. If unspecified, default to the current URI path of the route. Not applicable if the Plugin is mirroring gRPC traffic.    |

Review Comment:
   ```suggestion
   | path         | string | False    |         |              | Path of the host to forward the mirrored traffic to. If unspecified, default to the current URI path of the Route. Not applicable if the Plugin is mirroring gRPC traffic.    |
   ```



##########
docs/en/latest/plugins/proxy-mirror.md:
##########
@@ -74,85 +76,70 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
 
 :::
 
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1  \
-  -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "plugins": {
-        "proxy-mirror": {
-           "host": "http://127.0.0.1:9797"
-        }
-    },
-    "upstream": {
-        "nodes": {
-            "127.0.0.1:1999": 1
-        },
-        "type": "roundrobin"
-    },
-    "uri": "/hello"
-}'
-```
-
-### Specify the timeout for mirror subrequests
+### Mirror Partial Traffic
 
-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.
+The following example demonstrates how you can configure `proxy-mirror` to mirror 50% of the traffic to a Route and forward them to another Upstream service.
 
-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.
+Start a sample NGINX server for receiving mirrored traffic:
 
-| 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. |
-
-```yaml
-plugin_attr:
-  proxy-mirror:
-    timeout:
-      connect: 2000ms
-      read: 2000ms
-      send: 2000ms
+```shell
+docker run -p 8081:80 --name nginx nginx
 ```
 
-## Example usage
-
-:::tip
+You should see NGINX access log and error log on the terminal session.
 
-For testing you can create a test server by running:
+Open a new terminal session and create a Route with `proxy-mirror` to mirror 50% of the traffic:
 
 ```shell
-python -m http.server 9797
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "traffic-mirror-route",
+    "uri": "/get",
+    "plugins": {
+      "proxy-mirror": {
+        "host": "http://127.0.0.1:8081",
+        "sample_ratio": 0.5
+      }
+    },
+    "upstream": {
+      "nodes": {
+        "httpbin.org": 1
+      },
+      "type": "roundrobin"
+    }
+  }'
 ```
 
-:::
-
-Once you have configured the Plugin as shown above, the requests made will be mirrored to the configured host.
+Send Generate a few requests to the route:
 
 ```shell
-curl http://127.0.0.1:9080/hello -i
+curl -i "http://127.0.0.1:9080/get"
 ```
 
-```shell
-HTTP/1.1 200 OK
-...
-hello world
+You should receive `HTTP/1.1 200 OK` responses for all requests.
+
+Navigating back to the NGINX terminal session, you should see a number of access log entries, roughly half the number of requests generated:
+
+```text
+172.17.0.1 - - [29/Jan/2024:23:11:01 +0000] "GET /get HTTP/1.1" 404 153 "-" "curl/7.64.1" "-"
 ```
 
-## Delete Plugin
+This suggests APISIX has mirrored the request to the NGINX server. Here, the HTTP response status is `404` since the sample NGINX server does not implement the route.
 
-To remove 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.
+### Configure Mirroring Timeouts
 
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1 \
-  -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "uri": "/hello",
-    "plugins": {},
-    "upstream": {
-        "type": "roundrobin",
-        "nodes": {
-            "127.0.0.1:1999": 1
-        }
-    }
-}'
+The following example demonstrates how you can update the default connect, read, and send timeouts for the plugin. This could be useful when mirroring traffic to a very slow backend service.

Review Comment:
   ```suggestion
   The following example demonstrates how you can update the default connect, read, and send timeouts for the Plugin. This could be useful when mirroring traffic to a very slow backend service.
   ```



##########
docs/en/latest/plugins/proxy-mirror.md:
##########
@@ -25,47 +26,48 @@ description: This document describes the information about the Apache APISIX pro
 #
 -->
 
-## Description
-
-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.
+<head>
+  <link rel="canonical" href="https://docs.api7.ai/hub/proxy-mirror" />
+</head>
 
-:::note
+## Description
 
-The response returned by the mirror request is ignored.
+The `proxy-mirror` Plugin duplicates ingress traffic to APISIX and forwards them to a designated upstream, without interrupting the regular services. You can configure the Plugin to mirror all traffic or only a portion. The mechanism benefits a few use cases, including troubleshooting, security inspection, analytics, and more.
 
-:::
+Note that APISIX ignores any response from the Upstream host receiving mirrored traffic.
 
 ## Attributes
 
 | Name         | Type   | Required | Default | Valid values | Description                                                                                                               |
 |--------------|--------|----------|---------|--------------|---------------------------------------------------------------------------------------------------------------------------|
-| host         | string | True     |         |              | Address of the mirror service. It needs to contain the scheme (`http(s)` or `grpc(s)`) but without the path. For example, `http://127.0.0.1:9797`. |
-| path         | string | False    |         |              | Path of the mirror request. If unspecified, current path will be used. If it is for mirroring grpc traffic, this option is no longer applicable.                                                   |
-| path_concat_mode | string | False   |   replace     | ["replace", "prefix"]       | If the path of a mirror request is specified, set the concatenation mode of request paths. The `replace` mode will directly use `path` as the path of the mirror request. The `prefix` mode will use the `path` + `source request URI` as the path to the mirror request. If it is for mirroring grpc traffic, this option is no longer applicable too. |
-| sample_ratio | number | False    | 1       | [0.00001, 1] | Ratio of the requests that will be mirrored.                                                                              |
+| host         | string | True     |         |              | Address of the host to forward the mirrored traffic to. The address should contain the scheme but without the path, such as `http://127.0.0.1:8081`.  |
+| path         | string | False    |         |              | Path of the host to forward the mirrored traffic to. If unspecified, default to the current URI path of the route. Not applicable if the Plugin is mirroring gRPC traffic.    |
+| path_concat_mode | string | False   |   replace     | ["replace", "prefix"]       | Concatenation mode when `path` is specified. When set to `replace`, the configured `path` would be directly used as the path of the host to forward the mirrored traffic to. When set to `prefix`, the path to forward to would be the configured `path`, appended by the requested URI path of the route. Not applicable if the Plugin is mirroring gRPC traffic.  |

Review Comment:
   ```suggestion
   | path_concat_mode | string | False   |   replace     | ["replace", "prefix"]       | Concatenation mode when `path` is specified. When set to `replace`, the configured `path` would be directly used as the path of the host to forward the mirrored traffic to. When set to `prefix`, the path to forward to would be the configured `path`, appended by the requested URI path of the Route. Not applicable if the Plugin is mirroring gRPC traffic.  |
   ```



##########
docs/en/latest/plugins/proxy-mirror.md:
##########
@@ -74,85 +76,70 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
 
 :::
 
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1  \
-  -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "plugins": {
-        "proxy-mirror": {
-           "host": "http://127.0.0.1:9797"
-        }
-    },
-    "upstream": {
-        "nodes": {
-            "127.0.0.1:1999": 1
-        },
-        "type": "roundrobin"
-    },
-    "uri": "/hello"
-}'
-```
-
-### Specify the timeout for mirror subrequests
+### Mirror Partial Traffic
 
-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.
+The following example demonstrates how you can configure `proxy-mirror` to mirror 50% of the traffic to a Route and forward them to another Upstream service.
 
-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.
+Start a sample NGINX server for receiving mirrored traffic:
 
-| 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. |
-
-```yaml
-plugin_attr:
-  proxy-mirror:
-    timeout:
-      connect: 2000ms
-      read: 2000ms
-      send: 2000ms
+```shell
+docker run -p 8081:80 --name nginx nginx
 ```
 
-## Example usage
-
-:::tip
+You should see NGINX access log and error log on the terminal session.
 
-For testing you can create a test server by running:
+Open a new terminal session and create a Route with `proxy-mirror` to mirror 50% of the traffic:
 
 ```shell
-python -m http.server 9797
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "traffic-mirror-route",
+    "uri": "/get",
+    "plugins": {
+      "proxy-mirror": {
+        "host": "http://127.0.0.1:8081",
+        "sample_ratio": 0.5
+      }
+    },
+    "upstream": {
+      "nodes": {
+        "httpbin.org": 1
+      },
+      "type": "roundrobin"
+    }
+  }'
 ```
 
-:::
-
-Once you have configured the Plugin as shown above, the requests made will be mirrored to the configured host.
+Send Generate a few requests to the route:

Review Comment:
   ```suggestion
   Send Generate a few requests to the Route:
   ```



##########
docs/en/latest/plugins/proxy-mirror.md:
##########
@@ -25,47 +26,48 @@ description: This document describes the information about the Apache APISIX pro
 #
 -->
 
-## Description
-
-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.
+<head>
+  <link rel="canonical" href="https://docs.api7.ai/hub/proxy-mirror" />
+</head>
 
-:::note
+## Description
 
-The response returned by the mirror request is ignored.
+The `proxy-mirror` Plugin duplicates ingress traffic to APISIX and forwards them to a designated upstream, without interrupting the regular services. You can configure the Plugin to mirror all traffic or only a portion. The mechanism benefits a few use cases, including troubleshooting, security inspection, analytics, and more.
 
-:::
+Note that APISIX ignores any response from the Upstream host receiving mirrored traffic.
 
 ## Attributes
 
 | Name         | Type   | Required | Default | Valid values | Description                                                                                                               |
 |--------------|--------|----------|---------|--------------|---------------------------------------------------------------------------------------------------------------------------|
-| host         | string | True     |         |              | Address of the mirror service. It needs to contain the scheme (`http(s)` or `grpc(s)`) but without the path. For example, `http://127.0.0.1:9797`. |
-| path         | string | False    |         |              | Path of the mirror request. If unspecified, current path will be used. If it is for mirroring grpc traffic, this option is no longer applicable.                                                   |
-| path_concat_mode | string | False   |   replace     | ["replace", "prefix"]       | If the path of a mirror request is specified, set the concatenation mode of request paths. The `replace` mode will directly use `path` as the path of the mirror request. The `prefix` mode will use the `path` + `source request URI` as the path to the mirror request. If it is for mirroring grpc traffic, this option is no longer applicable too. |
-| sample_ratio | number | False    | 1       | [0.00001, 1] | Ratio of the requests that will be mirrored.                                                                              |
+| host         | string | True     |         |              | Address of the host to forward the mirrored traffic to. The address should contain the scheme but without the path, such as `http://127.0.0.1:8081`.  |
+| path         | string | False    |         |              | Path of the host to forward the mirrored traffic to. If unspecified, default to the current URI path of the route. Not applicable if the Plugin is mirroring gRPC traffic.    |

Review Comment:
   ```suggestion
   | path         | string | False    |         |              | Path of the host to forward the mirrored traffic to. If unspecified, default to the current URI path of the Route. Not applicable if the Plugin is mirroring gRPC traffic.    |
   ```



##########
docs/en/latest/plugins/proxy-mirror.md:
##########
@@ -74,85 +76,70 @@ admin_key=$(yq '.deployment.admin.admin_key[0].key' conf/config.yaml | sed 's/"/
 
 :::
 
-```shell
-curl http://127.0.0.1:9180/apisix/admin/routes/1  \
-  -H "X-API-KEY: $admin_key" -X PUT -d '
-{
-    "plugins": {
-        "proxy-mirror": {
-           "host": "http://127.0.0.1:9797"
-        }
-    },
-    "upstream": {
-        "nodes": {
-            "127.0.0.1:1999": 1
-        },
-        "type": "roundrobin"
-    },
-    "uri": "/hello"
-}'
-```
-
-### Specify the timeout for mirror subrequests
+### Mirror Partial Traffic
 
-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.
+The following example demonstrates how you can configure `proxy-mirror` to mirror 50% of the traffic to a Route and forward them to another Upstream service.
 
-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.
+Start a sample NGINX server for receiving mirrored traffic:
 
-| 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. |
-
-```yaml
-plugin_attr:
-  proxy-mirror:
-    timeout:
-      connect: 2000ms
-      read: 2000ms
-      send: 2000ms
+```shell
+docker run -p 8081:80 --name nginx nginx
 ```
 
-## Example usage
-
-:::tip
+You should see NGINX access log and error log on the terminal session.
 
-For testing you can create a test server by running:
+Open a new terminal session and create a Route with `proxy-mirror` to mirror 50% of the traffic:
 
 ```shell
-python -m http.server 9797
+curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
+  -H "X-API-KEY: ${admin_key}" \
+  -d '{
+    "id": "traffic-mirror-route",
+    "uri": "/get",
+    "plugins": {
+      "proxy-mirror": {
+        "host": "http://127.0.0.1:8081",
+        "sample_ratio": 0.5
+      }
+    },
+    "upstream": {
+      "nodes": {
+        "httpbin.org": 1
+      },
+      "type": "roundrobin"
+    }
+  }'
 ```
 
-:::
-
-Once you have configured the Plugin as shown above, the requests made will be mirrored to the configured host.
+Send Generate a few requests to the route:
 
 ```shell
-curl http://127.0.0.1:9080/hello -i
+curl -i "http://127.0.0.1:9080/get"
 ```
 
-```shell
-HTTP/1.1 200 OK
-...
-hello world
+You should receive `HTTP/1.1 200 OK` responses for all requests.
+
+Navigating back to the NGINX terminal session, you should see a number of access log entries, roughly half the number of requests generated:
+
+```text
+172.17.0.1 - - [29/Jan/2024:23:11:01 +0000] "GET /get HTTP/1.1" 404 153 "-" "curl/7.64.1" "-"
 ```
 
-## Delete Plugin
+This suggests APISIX has mirrored the request to the NGINX server. Here, the HTTP response status is `404` since the sample NGINX server does not implement the route.

Review Comment:
   ```suggestion
   This suggests APISIX has mirrored the request to the NGINX server. Here, the HTTP response status is `404` since the sample NGINX server does not implement the Route.
   ```



-- 
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: notifications-unsubscribe@apisix.apache.org

For queries about this service, please contact Infrastructure at:
users@infra.apache.org