You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardexpand all lines: docs/en/latest/plugins/proxy-mirror.md
+73-86
Original file line number
Diff line number
Diff line change
@@ -4,8 +4,9 @@ keywords:
4
4
- Apache APISIX
5
5
- API Gateway
6
6
- Proxy Mirror
7
-
description: This document describes the information about the Apache APISIX proxy-mirror Plugin, you can use it to mirror the client requests.
7
+
description: The proxy-mirror Plugin duplicates ingress traffic to APISIX and forwards them to a designated Upstream without interrupting the regular services.
8
8
---
9
+
9
10
<!--
10
11
#
11
12
# Licensed to the Apache Software Foundation (ASF) under one or more
@@ -25,47 +26,48 @@ description: This document describes the information about the Apache APISIX pro
25
26
#
26
27
-->
27
28
28
-
## Description
29
-
30
-
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.
The response returned by the mirror request is ignored.
35
+
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.
35
36
36
-
:::
37
+
Note that APISIX ignores any response from the Upstream host receiving mirrored traffic.
37
38
38
39
## Attributes
39
40
40
41
| 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`.|
43
-
| 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. |
44
-
| 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.|
45
-
| sample_ratio | number | False | 1 |[0.00001, 1]| Ratio of the requests that will be mirrored. |
43
+
| 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`. |
44
+
| 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.|
45
+
| 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. |
46
+
| sample_ratio | number | False | 1 |[0.00001, 1]|Ratio of the requests that will be mirrored. By default, all traffic are mirrored.|
46
47
47
-
You can customize the proxy timeouts for the mirrored sub-requests by configuring the `plugin_attr` key in your configuration file (`conf/config.yaml`). This can be used for mirroring traffic to a slow backend.
48
+
## Static Configurations
48
49
49
-
```yaml title="conf/config.yaml"
50
+
By default, timeout values for the Plugin are pre-configured in the [default configuration](https://github.com/apache/apisix/blob/master/apisix/cli/config.lua).
51
+
52
+
To customize these values, add the corresponding configurations to `config.yaml`. For example:
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.
81
+
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.
99
82
100
-
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.
83
+
Start a sample NGINX server for receiving mirrored traffic:
101
84
102
-
| Name | Type | Default | Description |
103
-
| --- | --- | --- | --- |
104
-
| connect | string | 60s | Connection timeout for mirror request to upstream. |
105
-
| 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. |
106
-
| 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. |
107
-
108
-
```yaml
109
-
plugin_attr:
110
-
proxy-mirror:
111
-
timeout:
112
-
connect: 2000ms
113
-
read: 2000ms
114
-
send: 2000ms
85
+
```shell
86
+
docker run -p 8081:80 --name nginx nginx
115
87
```
116
88
117
-
## Example usage
118
-
119
-
:::tip
89
+
You should see NGINX access log and error log on the terminal session.
120
90
121
-
For testing you can create a test server by running:
91
+
Open a new terminal session and create a Route with `proxy-mirror` to mirror 50% of the traffic:
122
92
123
93
```shell
124
-
python -m http.server 9797
94
+
curl "http://127.0.0.1:9180/apisix/admin/routes" -X PUT \
95
+
-H "X-API-KEY: ${admin_key}" \
96
+
-d '{
97
+
"id": "traffic-mirror-route",
98
+
"uri": "/get",
99
+
"plugins": {
100
+
"proxy-mirror": {
101
+
"host": "http://127.0.0.1:8081",
102
+
"sample_ratio": 0.5
103
+
}
104
+
},
105
+
"upstream": {
106
+
"nodes": {
107
+
"httpbin.org": 1
108
+
},
109
+
"type": "roundrobin"
110
+
}
111
+
}'
125
112
```
126
113
127
-
:::
128
-
129
-
Once you have configured the Plugin as shown above, the requests made will be mirrored to the configured host.
114
+
Send Generate a few requests to the Route:
130
115
131
116
```shell
132
-
curl http://127.0.0.1:9080/hello -i
117
+
curl -i "http://127.0.0.1:9080/get"
133
118
```
134
119
135
-
```shell
136
-
HTTP/1.1 200 OK
137
-
...
138
-
hello world
120
+
You should receive `HTTP/1.1 200 OK` responses for all requests.
121
+
122
+
Navigating back to the NGINX terminal session, you should see a number of access log entries, roughly half the number of requests generated:
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.
142
129
143
-
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.
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.
133
+
134
+
As the request mirroring was implemented as sub-requests, excessive delays in the sub-requests could lead to the blocking of the original requests. By default, the connect, read, and send timeouts are set to 60 seconds. To update these values, you can configure them in the `plugin_attr` section of the configuration file as such:
0 commit comments