Skip to content

Commit

Permalink
docs: improve proxy-mirror plugin docs (#11912)
Browse files Browse the repository at this point in the history
  • Loading branch information
@kayx23
kayx23 authored Mar 4, 2025
1 parent 63a5348 commit 1460edd
Show file tree
Hide file tree
Showing 2 changed files with 149 additions and 162 deletions.
159 changes: 73 additions & 86 deletions docs/en/latest/plugins/proxy-mirror.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,8 +4,9 @@ keywords:
- Apache APISIX
- API Gateway
- Proxy Mirror
description: This document describes the information about the Apache APISIX proxy-mirror Plugin, you can use it to mirror the client requests.
description: The proxy-mirror Plugin duplicates ingress traffic to APISIX and forwards them to a designated Upstream without interrupting the regular services.
---

<!--
#
# Licensed to the Apache Software Foundation (ASF) under one or more
Expand All @@ -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. |
| sample_ratio | number | False | 1 | [0.00001, 1] | Ratio of the requests that will be mirrored. By default, all traffic are 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.
## Static Configurations

```yaml title="conf/config.yaml"
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).

To customize these values, add the corresponding configurations to `config.yaml`. For example:

```yaml
plugin_attr:
proxy-mirror:
timeout:
connect: 2000ms
read: 2000ms
send: 2000ms
connect: 60s
read: 60s
send: 60s
```
| Name | Type | Default | Description |
|---------|--------|---------|-------------------------------------------|
| connect | string | 60s | Connect timeout to the mirrored Upstream. |
| read | string | 60s | Read timeout to the mirrored Upstream. |
| send | string | 60s | Send timeout to the mirrored Upstream. |
Reload APISIX for changes to take effect.
## Enable Plugin
## Examples
You can enable the Plugin on a specific Route as shown below:
The examples below demonstrate how to configure `proxy-mirror` for different scenarios.

:::note

You can fetch the `admin_key` from `config.yaml` and save to an environment variable with the following command:

```bash
Expand All @@ -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.

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:

```yaml title="conf/config.yaml"
plugin_attr:
proxy-mirror:
timeout:
connect: 2000ms
read: 2000ms
send: 2000ms
```

Reload APISIX for changes to take effect.
Loading

0 comments on commit 1460edd

Please sign in to comment.