Skip to main content
Version: 2.14



The proxy-mirror Plugin can be used to mirror client requests.


The response returned by the mirror request is ignored.


NameTypeRequiredDefaultValid valuesDescription
hoststringTrueAddress of the mirror service. It needs to contain the scheme but without the path. For example,
pathstringFalsePath of the mirror request. If unspecified, current path will be used.
sample_rationumberFalse1[0.00001, 1]Ratio of the requests that will be mirrored.

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.

connect: 2000ms
read: 2000ms
send: 2000ms
connectstring60sConnect timeout to the mirrored Upstream.
readstring60sRead timeout to the mirrored Upstream.
sendstring60sSend timeout to the mirrored Upstream.

Enabling the Plugin#

You can enable the Plugin on a specific Route as shown below:

curl  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
"plugins": {
"proxy-mirror": {
"host": ""
"upstream": {
"nodes": {
"": 1
"type": "roundrobin"
"uri": "/hello"

Example usage#

Once you have configured the Plugin as shown above, the requests made will be mirrored to the configured host.

curl -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

hello world

For testing you can create a test server by running:

python -m http.server 9797

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.

curl  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
"uri": "/hello",
"plugins": {},
"upstream": {
"type": "roundrobin",
"nodes": {
"": 1