This article describes how to configure and use runtime monitoring services in NGINX Plus: the interactive Dashboard (/status.html) and RESTful JSON interface (/status).

In This Section

About Live Activity Monitoring

NGINX Plus provides a real-time live activity monitoring interface that shows key load and performance metrics of your server infrastructure. These metrics can be viewed in the Dashboard or can be represented as a RESTful JSON interface and connected to third-party monitoring tools. Both options are provided by default in NGINX Plus.

The metrics include data from HTTP and TCP upstream servers as well as other data including:

  • NGINX version, uptime, and identification information
  • Total connections and requests
  • Request and response counts for each status_zone
  • Request and response counts per server in each upstream group of servers, plus health check and uptime statistics
  • Statistics per server, including its current state and total values (total failures, etc.)
  • Instrumentation for each named cache zone

The complete list of metrics is available here.

The statistics can be viewed from the status.html, or the Dashboard page provided in the NGINX Plus package. The page polls status information and displays it in a dashboard:


live activity monitor

Live load-balancing status from NGINX Plus


Prerequisites

  • NGINX Plus Release 9 and later
  • Configured HTTP and/or TCP upstream groups, health checks, cache zones, etc.

Configuring NGINX Plus

First, you will need to enable collecting statistics in the NGINX Plus configuration file. Then you can configure server zones, health checks, cache, and other data to appear in statistics.

Enabling Live Activity Monitoring

To enable the Dashboard and the JSON interface, open the NGINX configuration file and perform the following steps:

  1. In the http context, specify a server block that will be responsible for gathering stats:

    http {
        server {
        # your status configuration will be here
        }
    }
  2. Specify the IP address and/or port, on which the status page will be enabled, with the listen directive, for example, 8080. If NGINX listens on multiple IPs, you can restrict the status page to a single IP only:

    http {
        server {
        listen 192.168.1.23:8080;
        ...
        }
    }
  3. Specify the location that checks the exact match of the URI with /status and contains the status directive:

    http {
        server {
            listen 192.168.1.23:8080;
            ...
    
            location /status {
                status;
                ...
            }
        }
    }
  4. Specify one more location that will enable the dashboard: /status.html. The dashboard is by default located in the root directory (for example, /usr/share/nginx/html) specified by the root directive:

    http {
        server {
            listen 192.168.1.23:8080;
            root   /usr/share/nginx/html;
    
            location /status {
                status;
                ...
            }
    
            location = /status.html {
            }
        }
    }
  5. Restrict access to your statistics with allow and deny directives, for example, you can limit access to admin networks only:

    http {
        server {
            listen 192.168.1.23:8080;
            root   /usr/share/nginx/html;
    
            location /status {
                status;
                allow 192.168.1.0/32;
                deny  all;
            }
    
            location = /status.html {
            }
        }
    }

Adding More Data to Statistics

You can gather statistics from almost all your NGINX infrastructure, including separate virtual servers, upstream server groups, cache zones. In this case, you will need to perform some extra setup steps. For example, gathering stats from virtual servers and upstream groups will require shared memory zones that store configuration and runtime state information referenced by NGINX worker processes:

  • To make HTTP and TCP server to appear in statistics, specify the status_zone directive. The same zone name can be specified in multiple server blocks, so that the statistics for these servers will be aggregated together in the Dashboard:

    server {
        ...
        status_zone status_page;
        location / {
            proxy_pass http://backend;
        }
    }
  • To make an upstream server group to appear in statistics, specify the zone directive per each upstream block:

    upstream backend {
        zone   backend 64k;
        server backend1.example.com;
        server backend2.example.com;
    }
  • To make health checks appear in statistics, make sure that health checks are configured. See HTTP Health Checks and TCP Health Checks for more information:

    server {
        ...
        status_zone status_page;
        location / {
            proxy_pass http://backend;
            health_check;
        }
    }
  • To make cache appear in statistics, make sure that caching is enabled in your configuration. See NGINX Content Caching for more information:

    http {
        ...
        proxy_cache_path /data/nginx/cache keys_zone=one:10m;
    }
  • For possibility to add a new upstream server or modify existing upstream server directly from the Dashboard, enable the upstream_conf handler inside a separate location:

    server {
        ...
        location /upstream_conf {
            upstream_conf;
            allow 192.168.1.0/32;
            deny all;
        }
    }
  • When finished, save and exit configuration file.
  • Test the configuration and reload NGINX Plus:
    sudo nginx -t && sudo nginx -s reload

Using the Dashboard

The NGINX Plus Dashboard provides an at-a-glance summary of the health of the system and the traffic going through it. The Dashboard is driven by a RESTful API that polls the Extended Status handler and retrieves JSON data to display.

Accessing the Dashboard

If you have configured everything as described earler, type http://192.168.1.23/status.html in a browser. This will display the Dashboard page (status.html) located at /usr/share/nginx/html (as specified in the root directive).

There is also a live demo page from NGINX available at demo.nginx.com/status.html:

live activity monitor

Live load-balancing status from NGINX Plus

Tabs Overview

All information in NGINX Plus Dashboard is represented in tabs.

The Dashboard tab provides the overview of system health and the traffic going through it. From there you can get more detailed information about servers, upstreams, caches.

The row of tabs at the top of the window on the NGINX Plus dashboard make it easy to drill down to more detailed information about server zones, upstream groups, or the cache

The Server Zones tab gives detailed statistics on the frontend performance. Statistics are shown per each server in the http context. For NGINX Plus to collect information for each server, you must include the status_zone directive in each server configuration block.

The 'Server zones' tab in the NGINX Plus live activity monitoring dashboard displays information about NGINX Plus' interaction with clients

The Upstreams tab provides information about each upstream group for HTTP and HTTPS traffic. TCP and UDP upstream groups appear on the TCP/UDP Upstreams tab. For NGINX Plus to collect information for an upstream group, you must include the zone directive in the upstream configuration block.

The Upstreams tab on the NGINX Plus live activity monitoring dashboard provides information about the servers in each uptream group for HTTP/HTTPS traffic

The Caches tab provides statistics about the caches configured in NGINX Plus. For NGINX Plus to collect information for an upstream group, you must configure cache.

The 'Caches' tab in the NGINX Plus live activity monitoring dashboard provides information about cache readiness, fullness, and hit ratio

Managing Upstream Servers from the Dashboard

You can add new or modify and remove upstream servers directly from the Dashboard interface. Note that you must previously enable the upstream_conf handler in your NGINX Plus configuration. In the Upstreams or TCP/UDP Upstreams tab, click the pencil icon next to the server name and choose between Edit selected and Add server buttons:

In editing mode on the 'Upstreams' tab in the NGINX Plus live activity monitoring dashboard, you can add, remove, or modify servers

To add an upstream server, click Add server:

The 'Add server' interface for adding servers to an upstream group in the NGINX Plus live activity monitoring dashboard

To remove or modify an upstream server, click the box to the left of each server’s name, then click Edit selected:

The 'Edit selected' interface for modifying or removing servers in an upstream group in the NGINX Plus live activity monitoring dashboard

When finished, click the Save button to save the changes.

Using the JSON Data

By default NGINX Plus provides status information in the JSON format. This enables you to connect these stats to other dashboards and monitoring tools, such as New Relic or DataDog. You can also explore this data using your web browser – a JSON pretty-printer extension such as JSONView (for Chrome or Firefox).

The status information of any element in the JSON document can be accessed with a slash-separated URL. If you request /status (or whichever URI matches the location directive), NGINX Plus returns a JSON document containing the current activity data.

Here are live examples of JSON data, also available at: demo.nginx.com/status/

http://demo.nginx.com/status/
http://demo.nginx.com/status/nginx_version
http://demo.nginx.com/status/caches/http_cache
http://demo.nginx.com/status/upstreams
http://demo.nginx.com/status/upstreams/demo-backend
http://demo.nginx.com/status/upstreams/demo-backend/peers/0
http://demo.nginx.com/status/upstreams/demo-backend/peers/0/weight

To learn more about NGINX Plus, please visit the Products page.

For more information about getting real-time stats for your NGINX Plus installation, see Live Activity Monitoring of NGINX Plus in 3 Simple Steps.