The Nginx Virtual Host Traffic Status Module (also known as ngx_http_vhost_traffic_status) is an Nginx extension module used to monitor and report traffic information of virtual hosts (IP addresses, HTTP requests, response times, and more). It provides graphical web interfaces to visually display virtual host traffic information.

The module allows you to view and analyze traffic metrics such as:

  • Overall traffic of each virtual host.
  • Detailed information about each HTTP request sent to each virtual host.
  • Average response time, processing time, and request waiting time.
  • Information about IP addresses that accessed the virtual host.
  • Daily, weekly, monthly, and total statistics.

To use the Nginx Virtual Host Traffic Status module, you need to build Nginx with this module or use Nginx dynamic modules to add it to your virtual hosts. In this guide, I will show you how to add it to an existing Nginx setup.

Step 1: Download the Module

Download the module from the official GitHub page: https://github.com/vozlt/nginx-module-vts or clone it as follows:

cd /tmp
git clone https://github.com/vozlt/nginx-module-vts

Step 2: Build the Module from the Nginx Source

This step is very important. You need to check the version of Nginx you are using before downloading the correct Nginx source to build. If you download the wrong version, the module may fail to load.

Check your Nginx version:

nginx -V

Example output:

nginx version: nginx/1.18.0 (Ubuntu)
built with OpenSSL 1.1.1f  31 Mar 2020
TLS SNI support enabled

Here, the current version is 1.18.0.

Next, download the corresponding Nginx source and build it with the module:

wget http://nginx.org/download/nginx-1.18.0.tar.gz
tar zxvf nginx-1.18.0.tar.gz
cd nginx-1.18.0
./configure --with-compat --add-dynamic-module=/tmp/nginx-module-vts

# build module
make modules

# copy the built module into the nginx modules directory, usually /usr/share/nginx/modules
cp objs/ngx_http_vhost_traffic_status_module.so /usr/share/nginx/modules
chmod 644 /usr/share/nginx/modules/ngx_http_vhost_traffic_status_module.so

Step 3: Use the Module

To use the module, you need to add it to your nginx.conf (this is crucial).

Add the following line at the beginning of /etc/nginx/nginx.conf:

user www-data;
worker_processes auto;
pid /run/nginx.pid;
include /etc/nginx/modules-enabled/*.conf;

# load modules
load_module modules/ngx_http_vhost_traffic_status_module.so;

events {
        worker_connections 768;
        # multi_accept on;
}
...

Then, add a status page to the vhosts you want to monitor. Below is an example of adding it to the default site at /etc/nginx/sites-available/default:

vhost_traffic_status_zone;
...
server {
    listen 80;
    ...
    location /status {
        vhost_traffic_status_display;
        vhost_traffic_status_display_format html;
    }
}

After making these changes, test the configuration before reloading Nginx:

nginx -t

Expected output if correct:

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload Nginx:

nginx -s reload

Bonus: Secure the Status Page with htpasswd

This helps restrict access to the /status page so not everyone can view it.

Create a password file:

htpasswd -c /etc/nginx/.htpasswd yourpassword

Update the vhost configuration as follows:

vhost_traffic_status_zone;
...
server {
    listen 80;
    ...
    location /status {
        auth_basic "Restricted";
        auth_basic_user_file /etc/nginx/.htpasswd;

        vhost_traffic_status_display;
        vhost_traffic_status_display_format html;
    }
}

Finally, access https://yourdomain/status to see the results.