Nginx

NGINX is a high-performance web server, reverse proxy, and load balancer known for its ability to handle thousands of concurrent connections efficiently with minimal resource usage. Its widespread adoption makes it a cornerstone of modern web infrastructure.

Monitoring NGINX's performance metrics is essential for maintaining reliable web services. Through metrics like connection states, request rates, response codes, and upstream response times, operators can quickly identify issues, optimize performance, and ensure high availability of their web services.

Prerequisites

1 MW Host Agent

Middleware Host Agent (MW Agent) v1.6.1+ must be installed on your local machine. To install the MW Agent, see our Installation Guide.

2 Expose Nginx Metrics

To collect metrics from NGINX, your server must expose a local status endpoint which requires the NGINX binary to be compiled with the status module enabled. This module is crucial for the monitoring solution to scrape and report NGINX metrics.

There are two module which can expose these metrics.

Nginx Status Stub

This collects very basic level metrics and mostly enabled by default in your nginx installation. To check if it is available try the following command:

1nginx -V 2>&1 | grep -o http_stub_status_module

This should output

1http_stub_status_module

Most standard NGINX distributions include this module by default, but if you're using a custom build, you'll need to compile it from source.

DEB

RPM

DEB: Compatible with Debian or Debian-based operating systems. For AWS instances this includes Ubuntu and Debian.

1# Install build dependencies
2sudo apt-get install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev
3
4# Download and extract nginx
5wget http://nginx.org/download/nginx-1.24.0.tar.gz
6tar -zxvf nginx-1.24.0.tar.gz
7cd nginx-1.24.0
8
9# Configure with status module
10./configure --with-http_stub_status_module
11
12# Compile and install
13make
14sudo make install

RPM: Compatible with Red Hat Package Manager and operating systems like Red Hat or CentOS. Use this for AWS instances using Amazon Linux.

1# Install build dependencies
2sudo dnf groupinstall 'Development Tools'
3sudo dnf install pcre pcre-devel zlib zlib-devel openssl openssl-devel
4
5# Download and extract nginx
6wget http://nginx.org/download/nginx-1.24.0.tar.gz
7tar -zxvf nginx-1.24.0.tar.gz
8cd nginx-1.24.0
9
10# Configure with status module
11./configure --with-http_stub_status_module
12
13# Compile and install
14make
15sudo make install

To enable stub status monitoring, add this to your NGINX configuration. This is generally at /etc/nginx/nginx.conf

1location /nginx_status {
2    stub_status on;
3    access_log off;
4    # Restrict access as needed
5    allow 127.0.0.1;
6    deny all;
7}

Nginx virtual host traffic status module

To check if VTS module is installed:

1nginx -V 2>&1 | grep -o nginx-module-vts

This should output:

1nginx-module-vts

If the module isn't present, you have to install manually:

DEB

RPM

Docker

DEB: Compatible with Debian or Debian-based operating systems. For AWS instances this includes Ubuntu and Debian.

To install manually first check nginx version.

1nginx -V

This outputs:

1nginx version: nginx/1.24.0 (Ubuntu)  ### HERE IS YOUR NGINX VERSION 
2built with OpenSSL 3.0.2 15 Mar 2022
3TLS SNI support enabled
4configure arguments: --with-cc-opt='-g -O2 -ffile-prefix-map=/build/nginx-dSlJVq/nginx-1.18.0=. -flto=auto -ffat-lto-objects -flto=auto -ffat-lto-objects -fstack-protector-strong -Wformat -Werror=format-security -fPIC -Wdate-time -D_FORTIFY_SOURCE=2' --with-ld-opt='-Wl,-Bsymbolic-functions -flto=auto -ffat-lto-objects -flto=auto -Wl,-z,relro -Wl,-z,now -fPIC' --prefix=/usr/share/nginx --conf-path=/etc/nginx/nginx.conf --http-log-path=/var/log/nginx/access.log --error-log-path=/var/log/nginx/error.log --lock-path=/var/lock/nginx.lock --pid-path=/run/nginx.pid --modules-path=/usr/lib/nginx/modules --http-client-body-temp-path=/var/lib/nginx/body --http-fastcgi-temp-path=/var/lib/nginx/fastcgi --http-proxy-temp-path=/var/lib/nginx/proxy --http-scgi-temp-path=/var/lib/nginx/scgi --http-uwsgi-temp-path=/var/lib/nginx/uwsgi --with-compat --with-debug --with-pcre-jit --with-http_ssl_module --with-http_stub_status_module --with-http_realip_module --with-http_auth_request_module --with-http_v2_module --with-http_dav_module --with-http_slice_module --with-threads --add-dynamic-module=/build/nginx-dSlJVq/nginx-1.18.0/debian/modules/http-geoip2 --with-http_addition_module --with-http_gunzip_module --with-http_gzip_static_module --with-http_sub_module

Before we download and install nginx from source, we need to remove the current installation

1sudo apt remove nginx

Check if nginx is removed:

1# This should output:
2# bash: command not found: nginx
3nginx -V

Now we need to download Nginx source, depending on our Nginx version.

1# First, ensure you have the necessary tools to build Nginx:
2sudo apt update
3sudo apt install build-essential libpcre3 libpcre3-dev zlib1g zlib1g-dev libssl-dev wget

Clone the VTS module repository:

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

Download Nginx Source Code

1wget http://nginx.org/download/nginx-1.24.0.tar.gz
2tar -xzvf nginx-1.24.0.tar.gz
3cd nginx-1.24.0

Run the configure script, including the path to the VTS module:

1./configure --prefix=/usr/local/nginx \
2            --add-module=../nginx-module-vts \
3            --with-http_ssl_module \
4            --with-http_stub_status_module \
5            --with-http_v2_module \
6            --with-stream

Build and install Nginx with the VTS module:

1make
2sudo make install

Verify Installation:

1# This should output:
2# nginx-module-vts
3/usr/local/nginx/sbin/nginx -V  2>&1 | grep -o nginx-module-vts

Add nginx to PATH. Open your .bashrc and add the following line.

1export PATH=$PATH:/usr/local/nginx/sbin

Source the .bashrc file

1source .bashrc

RPM: Compatible with Red Hat Package Manager and operating systems like Red Hat, CentOS or Fedora. Use this for AWS instances using Amazon Linux.

First, remove any pre-installed version of Nginx:

1sudo yum remove nginx -y

Check if Nginx is removed:

1nginx -V
2# Expected output: bash: command not found: nginx

Update your system and install necessary build tools:

1sudo yum update -y
2sudo yum groupinstall "Development Tools" -y
3sudo yum install pcre pcre-devel zlib zlib-devel openssl openssl-devel wget -y

Clone the VTS module repository:

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

Visit nginx.org/download to find the version of Nginx that matches your needs. For example:

1wget http://nginx.org/download/nginx-1.24.0.tar.gz
2tar -xzvf nginx-1.24.0.tar.gz
3cd nginx-1.24.0

Run the configure script with the necessary flags and modules:

1./configure --prefix=/usr/local/nginx \
2            --add-module=../nginx-module-vts \
3            --with-http_ssl_module \
4            --with-http_stub_status_module \
5            --with-http_v2_module \
6            --with-stream

Build and install Nginx:

1make
2sudo make install

Check if Nginx is installed with the VTS module:

1/usr/local/nginx/sbin/nginx -V 2>&1 | grep -o nginx-module-vts
2# Expected output: nginx-module-vts

Add nginx to PATH. Open your .bashrc and add the following line.

1export PATH=$PATH:/usr/local/nginx/sbin

Source the .bashrc file

1source .bashrc

Dockerfile: If you want to run Nginx inside a docker container.

1FROM nginx:1.22.1
2
3ENV NGINX_VERSION="1.22.1"
4ENV NGINX_VTS_VERSION="0.2.2"
5
6# Install build dependencies and add nginx source repository
7RUN apt-get update \
8    && apt-get install -y gnupg2 \
9    && curl -s http://nginx.org/packages/keys/nginx_signing.key | apt-key add - \
10    && echo "deb-src http://nginx.org/packages/debian/ bullseye nginx" >> /etc/apt/sources.list
11
12# Download nginx source and install build dependencies
13RUN apt-get update \
14    && apt-get install -y dpkg-dev curl \
15    && mkdir -p /opt/rebuildnginx \
16    && chmod 0777 /opt/rebuildnginx \
17    && cd /opt/rebuildnginx \
18    && su --preserve-environment -s /bin/bash -c "apt-get source nginx=${NGINX_VERSION}" _apt \
19    && apt-get build-dep -y nginx=${NGINX_VERSION}
20
21# Download and integrate VTS module
22RUN cd /opt \
23    && curl -sL https://github.com/vozlt/nginx-module-vts/archive/v${NGINX_VTS_VERSION}.tar.gz | tar -xz \
24    && sed -i -r -e "s/\.\/configure(.*)/.\/configure\1 --add-module=\/opt\/nginx-module-vts-${NGINX_VTS_VERSION}/" \
25       /opt/rebuildnginx/nginx-${NGINX_VERSION}/debian/rules \
26    && cd /opt/rebuildnginx/nginx-${NGINX_VERSION} \
27    && dpkg-buildpackage -b \
28    && cd /opt/rebuildnginx \
29    && dpkg --install nginx_${NGINX_VERSION}-1~bullseye_amd64.deb
30
31# Cleanup
32RUN apt-get remove --purge -y dpkg-dev curl \
33    && apt-get -y --purge autoremove \
34    && rm -rf /var/lib/apt/lists/* \
35    && rm -rf /opt/rebuildnginx \
36    && rm -rf /opt/nginx-module-vts-${NGINX_VTS_VERSION}
37
38CMD ["nginx", "-g", "daemon off;"]

To enable vts, add this to your NGINX configuration. This is generally at /etc/nginx/nginx.conf

1location /status {
2            vhost_traffic_status_display;
3            vhost_traffic_status_display_format html;
4            access_log off;
5            # Restrict access as needed
6            allow 127.0.0.1;
7            deny all;
8        }

This will expose nginx metrics.

3 Access Integrations

To configure the integration of your Nginx Web Server with our platform.

Enter Server Details:

Endpoint: Provide the endpoint URL of the server status for the http status stub. This is generally <SERVER-URL>:<NGINX-PORT>/nginx_status
VTS Endpoint: Provide the endpoint URL of the server status for the VTS Endpoint . This is generally <SERVER-URL>:<NGINX-PORT>/status/format/json
Collection Interval: Specify the interval at which telemetry data is collected.

Metrics collected

Metrics

Metric	Description	Unit	Type
`nginx.requests`	Total number of requests made to the server since it started	requests	cumulative (int)
`nginx.connections_accepted`	The total number of accepted client connections	connections	cumulative (int)
`nginx.connections_handled`	The total number of handled connections	connections	cumulative (int)
`nginx.connections_current`	The current number of nginx connections by state	connections	cumulative (int)
`nginx.load_timestamp`	Time of the last reload of configuration (time since Epoch)	ms	gauge (int)
`nginx.upstream.peers.response_time`	The average time to receive the last byte of data from this server	ms	gauge (int)
`nginx.net.reading`	Current number of connections where NGINX is reading the request header	connections	gauge (int)
`nginx.net.writing`	Current number of connections where NGINX is writing the response back to the client	connections	gauge (int)
`nginx.net.waiting`	Current number of connections where NGINX is waiting for a response	connections	gauge (int)
`nginx.server_zone.responses.1xx`	The number of responses with 1xx status code	responses	gauge (int)
`nginx.server_zone.responses.2xx`	The number of responses with 2xx status code	responses	gauge (int)
`nginx.server_zone.responses.3xx`	The number of responses with 3xx status code	responses	gauge (int)
`nginx.server_zone.responses.4xx`	The number of responses with 4xx status code	responses	gauge (int)
`nginx.server_zone.responses.5xx`	The number of responses with 5xx status code	responses	gauge (int)
`nginx.server_zone.received`	Bytes received by server zones	By	cumulative (int)
`nginx.server_zone.sent`	Bytes sent by server zones	By	cumulative (int)
`nginx.upstream.peers.requests`	Number of requests made to upstream servers	requests	cumulative (int)
`nginx.upstream.peers.received`	Bytes received from upstream servers	By	cumulative (int)
`nginx.upstream.peers.sent`	Bytes sent from upstream servers	By	cumulative (int)
`nginx.upstream.peers.responses.1xx`	Number of responses from upstream with 1xx status codes	responses	cumulative (int)
`nginx.upstream.peers.responses.2xx`	Number of responses from upstream with 2xx status codes	responses	cumulative (int)
`nginx.upstream.peers.responses.3xx`	Number of responses from upstream with 3xx status codes	responses	cumulative (int)
`nginx.upstream.peers.responses.4xx`	Number of responses from upstream with 4xx status codes	responses	cumulative (int)
`nginx.upstream.peers.responses.5xx`	Number of responses from upstream with 5xx status codes	responses	cumulative (int)
`nginx.upstream.peers.weight`	Weight of upstream server	weight	gauge (double)
`nginx.upstream.peers.backup`	Whether upstream server is a backup server	{state}	gauge (int)
`nginx.upstream.peers.health_checks.last_passed`	Boolean indicating if the last health check request was successful and passed tests	{status}	gauge (int)