How to Mirror Traffic with Nginx: Install, Configure, and Use ngx_http_mirror_module

1. Why Mirror Production Traffic

Copying production traffic to a pre‑release or test environment helps verify functionality and performance with real requests, avoids creating synthetic data, does not impact live users, differs from gray releases, aids troubleshooting, and serves as a testing method after service refactoring.

2. Installing Nginx

Create a yum repository file /etc/yum.repos.d/nginx.repo with the following content:

[nginx-stable]
name=nginx stable repo
baseurl=http://nginx.org/packages/centos/$releasever/$basearch/
gpgcheck=1
enabled=1
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

[nginx-mainline]
name=nginx mainline repo
baseurl=http://nginx.org/packages/mainline/centos/$releasever/$basearch/
gpgcheck=1
enabled=0
gpgkey=https://nginx.org/keys/nginx_signing.key
module_hotfixes=true

Install Nginx: yum install nginx -y The default configuration file is nginx.conf, typically located in /usr/local/nginx/conf, /etc/nginx, or /usr/local/etc/nginx. Start Nginx with:

# Start Nginx
nginx
# Fast shutdown
nginx -s stop
# Graceful shutdown
nginx -s quit
# Reload configuration
nginx -s reload
# Reopen log files
nginx -s reopen
# List processes
ps -ax | grep nginx

Alternative stop command:

kill -s QUIT 3997

3. ngx_http_mirror_module Overview

The ngx_http_mirror_module (available since Nginx 1.13.4) creates background sub‑requests that duplicate the original request; responses from these sub‑requests are ignored. It effectively creates a “mirror” of all incoming traffic for later analysis or replay.

4. Basic Mirror Configuration Example

location / {
    mirror /mirror;
    proxy_pass http://backend;
}

location = /mirror {
    internal;
    proxy_pass http://test_backend$request_uri;
}

If the request body should be mirrored, enable it before creating the sub‑request:

location / {
    mirror /mirror;
    mirror_request_body off;
    proxy_pass http://backend;
}

location = /mirror {
    internal;
    proxy_pass http://log_backend;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
    proxy_set_header X-Original-URI $request_uri;
}

5. Building Nginx with the Mirror Module

If the pre‑built package lacks the module, compile Nginx from source:

# Download source from http://nginx.org/en/download.html
./configure \
    --sbin-path=/usr/local/nginx/nginx \
    --conf-path=/usr/local/nginx/nginx.conf \
    --pid-path=/usr/local/nginx/nginx.pid \
    --with-http_ssl_module \
    --without-http_limit_req_module \
    --without-http_mirror_module \
    --with-pcre=../pcre-8.43 \
    --with-zlib=../zlib-1.2.11 \
    --add-module=/path/to/ngx_devel_kit \
    --add-module=/path/to/lua-nginx-module
make && make install

6. Full Example Configuration with Mirroring

upstream api.abc.com {
    server 127.0.0.1:8080;
}
upstream tapi.abc.com {
    server 127.0.0.1:8081;
}
server {
    listen 80;
    location /api {
        proxy_pass http://api.cjs.com;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        # Traffic mirroring
        mirror /newapi;
        mirror /mirror2;
        mirror /mirror3;
        mirror_request_body on;
    }
    location /tapi {
        proxy_pass http://tapi.cjs.com$request_uri;
        proxy_pass_request_body on;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

7. Useful Commands

# Show Nginx process runtime
ps -eo pid,user,lstart,etime,cmd | grep nginx
# Count established connections
netstat -an | grep ESTABLISHED | wc -l
# Count connections on port 80
netstat -an | grep ":80" | wc -l

8. Documentation Links

Nginx Documentation

ngx_http_mirror_module

Beginner's Guide

Core Module – location

Configure Options