Configure Proxy Mirror

Learn how to duplicate and send a percentage of real production traffic to a secondary service for testing and verification.

The proxy-mirror plugin allows you to mirror real requests from your production environment to a separate service for testing or analysis. The response from the mirrored service is ignored, ensuring no impact on the original request's performance or outcome.

Prerequisites

An API7 Enterprise instance is running.
A Gateway Group is created and a Gateway instance is running.
A token from the Dashboard.

Configure Traffic Mirroring

The following configuration mirrors all incoming requests to a secondary service running at http://test-server:8080.

curl -k "https://localhost:7443/apisix/admin/services/proxy-mirror-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "proxy-mirror-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/proxy-mirror-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "proxy-mirror-route",
    "methods": ["GET"],
    "paths": ["/anything/mirror"],
    "service_id": "proxy-mirror-service",
    "plugins": {
      "proxy-mirror": {
        "host": "http://test-server:8080",
        "path": "/mirror-receiver",
        "sample_ratio": 1
      }
    }
  }'

adc.yaml

services:
  - name: proxy-mirror-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: proxy-mirror-route
        uris:
          - /anything/mirror
        methods:
          - GET
        plugins:
          proxy-mirror:
            host: "http://test-server:8080"
            path: "/mirror-receiver"
            sample_ratio: 1

adc sync -f adc.yaml

Configure Sampled Traffic Mirroring

To mirror only a small percentage of your traffic, you can adjust the sample_ratio field.

curl -k "https://localhost:7443/apisix/admin/services/sampled-proxy-mirror-service?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sampled-proxy-mirror-service",
    "upstream": {
      "type": "roundrobin",
      "scheme": "http",
      "nodes": [
        {
          "host": "httpbin.org",
          "port": 80,
          "weight": 100
        }
      ]
    }
  }'

curl -k "https://localhost:7443/apisix/admin/routes/sampled-proxy-mirror-route?gateway_group_id={gateway_group_id}" -X PUT \
  -H "X-API-KEY: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "sampled-proxy-mirror-route",
    "methods": ["GET"],
    "paths": ["/anything/mirror-sampled"],
    "service_id": "sampled-proxy-mirror-service",
    "plugins": {
      "proxy-mirror": {
        "host": "http://test-server:8080",
        "sample_ratio": 0.1
      }
    }
  }'

adc.yaml

services:
  - name: sampled-proxy-mirror-service
    upstream:
      nodes:
        - host: httpbin.org
          port: 80
          weight: 1
    routes:
      - name: sampled-proxy-mirror-route
        uris:
          - /anything/mirror-sampled
        methods:
          - GET
        plugins:
          proxy-mirror:
            host: "http://test-server:8080"
            sample_ratio: 0.1

adc sync -f adc.yaml

Validate the Configuration

Send a request to the main service:

curl "http://127.0.0.1:9080/anything/mirror"

Check the logs of your mirrored service (http://test-server:8080) to verify that it received the mirrored request. Since mirroring happens asynchronously, the original client will not experience any delay.

The mirrored target must be reachable from the gateway instances themselves, not just from your local shell or the control plane. In a local Docker setup, exposing the mirror receiver on a host port is often the simplest way to make it reachable.

Next Steps

Configure Proxy Cache — improve performance by caching responses.
Configure Fault Injection — test your application resilience.
Configure Response Rewrite — modify response data before returning to the client.