This article describes how to configure and use runtime monitoring services in NGINX Plus: the interactive Dashboard, NGINX Plus REST API, and NGINX Amplify.

In This Section

About Live Activity Monitoring

NGINX Plus provides various monitoring tools for your server infrastructure:

  • the interactive Dashboard page available since NGINX Plus R9 – a real-time live activity monitoring interface that shows key load and performance metrics of your server infrastructure.
  • NGINX REST API available since NGINX Plus R13 – an interface that can obtain extended status information, reset statistics, manage upstream servers on-the-fly, and manage key-value store. With the API you can connect NGINX Plus status information with third-party tools that support the JSON interface, for example, NewRelic or your own dashboard.
  • NGINX Amplify – a SAAS tool for comprehensive monitoring of your server infrastructure including NGINX Plus (status metrics, log files, processes state);
    system metrics (CPU and memory usage), operating system metadata (uptime, hostname).

Prerequisites

  • NGINX Plus Release R13 and later for NGINX Plus REST API
  • NGINX Plus Release R14 for the Dashboard

Gathering Data to Appear in Statistics

In order to collect data from virtual servers, upstream server groups, or cache zones, you will need to enable shared memory zones for the objects you want to collect data for. A shared memory zone stores configuration and runtime state information referenced by NGINX worker processes.

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

    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 cache appear in statistics, make sure that caching is enabled in your configuration. A shared memory zone for caching is specified in the proxy_cache_path, fastcgi_cache_path, scgi_cache_path, or uwsgi_cache_path directive in the keys_zone parameter. See NGINX Content Caching for more information:

    http {
        ...
        proxy_cache_path /data/nginx/cache keys_zone=one:10m;
    }
  • To make health checks appear in statistics, make sure that health checks are enabled with the health_check directive and the server group resides in the shared memory. See HTTP Health Checks and TCP Health Checks for more information:

    server {
        ...
        status_zone status_page;
        location / {
            proxy_pass http://backend;
            health_check;
        }
    }
  • When finished, save and exit configuration file.
  • Test the configuration and reload NGINX Plus:
    $ sudo nginx -t && sudo nginx -s reload

Using the Dashboard

NGINX Plus Dashboard provides a real-time live activity monitoring interface that shows key load and performance metrics of your server infrastructure.

Enabling the Dashboard

Note: Prior to NGINX Plus R14 gathering statistics and management of upstream servers in the Dashboard was performed with the status and upstream_conf modules. Now the extended status and upstream_conf modules are superseded by the api module.

To enable the Dashboard, make the following changes in the NGINX configuration file:

  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 for the Dashboard page with the listen directive, for example, 192.168.1.23. If NGINX listens on multiple IPs, you can restrict the Dashboard page to a single IP only:

    http {
        server {
        listen 192.168.1.23;
        ...
        }
    }
  3. Enable access to status information, on-the-fly configuration of upstream servers and key-value pairs management by specifying a location for API calls and the api directive in this location:

    server {
        listen 192.168.1.23;
        ...
        location /api {
            api;
        }
    }
  4. Limit access to your statistics to admin networks with allow and deny directives:

    http {
        server {
            listen 192.168.1.23;
    
            location /api {
                api;
                allow 192.168.1.0/32;
                deny  all;
            }
        }
    }
  5. Enable the dashboard by specifying the /dashboard.html location. By default the Dashboard is located in the root directory (for example, /usr/share/nginx/html) specified by the root directive:

    http {
        server {
            listen 192.168.1.23;
            ...
    
            location = /dashboard.html {
                root   /usr/share/nginx/html;
                ...
            }
        }
    }

Accessing the Dashboard

In the address bar of your browser, type-in the address that corresponds to your Dashboard page (in our example http://192.168.1.23/dashboard.html). This will display the Dashboard page (dashboard.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/dashboard.html:

live status

Live load-balancing status from NGINX Plus

Tabs Overview

All information in NGINX Plus Dashboard is represented in tabs.

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.

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 REST API

With NGINX Plus, statistics of your server infrastructure can be managed with the REST API interface. The API is based on standard HTTP requests: statistics can be obtained with GET requests and reset with DELETE requests. The requests are sent in the JSON format that allows you to connect the stats to monitoring tools or dashboards that support JSON.

Note: Prior to NGINX Plus R13 gathering statistics was performed with the status module. Starting from NGINX Plus R13, the extended status and upstream_conf modules are superseded by the api module.

Configuring the API

To enable the API:

  1. In the NGINX configuration file, create a location for API requests and specify the api directive in this location:

    server {
        ...
        location /api {
            api;
        }
    }
  2. It is recommended to restrict access to this location, for example, allow access only from local networks:

    server {
        ...
        location /api {
            api;
            allow 192.168.1.0/32;
            deny  all;
        }
    }
  3. In order to make changes with the API, such as resetting statistics counters, managing upstream servers on-the-fly or key-value storage enable the read-write mode for the API by specifying the write=on parameter for the api directive:

    server {
        ...
        location /api {
            api write=on;
            allow 192.168.1.0/32;
            deny  all;
        }
    }

Getting statistics with the API

The status information of any element can be accessed with a slash-separated URL. The URL may look as follows:

https://demo.nginx.com/api/2/http/caches/http_cache?fields=expired,bypass

where:

  • /api is the location you have configured in the NGINX configuration file for the API
  • /2 is the API version, the current API version is 2
  • /http/caches/http_cache is the path to the resource
  • ?fields=expired,bypass is an optional argument that specifies which fields of the requested object will be output

The requested information is returned in the JSON data format.

To get the list of all available rootpoints, send the GET request with the curl command in terminal:

$ curl https://demo.nginx.com/api/2/ | json_pp

The JSON data returned:

[
   "nginx",
   "processes",
   "connections",
   "ssl",
   "slabs",
   "http",
   "stream"
]

To get the statistics for a particular endpoint, for example, obtain general information about NGINX, send the following GET request:

$ curl https://demo.nginx.com/api/2/nginx | json_pp

The JSON data returned:

{
   "version" : "1.13.7",
   "build" : "nginx-plus-r14",
   "generation" : 5,
   "timestamp" : "2017-12-12T13:20:36.686Z",
   "pid" : 74395,
   "ppid" : 22711,
   "address" : "206.251.255.64",
   "load_timestamp" : "2017-12-09T10:00:00.405Z"
}

You can specify which fields of the requested object will be output with the optional fields argument in the request line. For example, to display only NGINX Plus version and build, specify the command:

$ curl https://demo.nginx.com/api/2/nginx?fields=version,build | json_pp

The JSON data returned:

{
   "version" : "1.13.7",
   "build" : "nginx-plus-r14"
}

For a complete list of available endpoints and supported methods see NGINX API module reference documentation.

Resetting the statistics

Resetting the statistics is performed by sending an API command with the DELETE method to a target endpoint. Make sure that your API is configured in the read-write mode.

You can reset the following types of statistics:

  • abnormally terminated and respawned child processes:

    curl -X DELETE "http://demo.nginx.com/api/2/processes"
  • accepted and dropped client connections:

    curl -X DELETE "http://demo.nginx.com/api/2/connections"
  • SSL handshakes and session reuses:

    $ curl -X DELETE "http://demo.nginx.com/api/2/ssl
  • the reqs and fails metrics for each memory slot, for example, memory slot one:

    $ curl -X DELETE "http://demo.nginx.com/api/2/slabs/one"
  • total client HTTP requests:

    $ curl -X DELETE "http://demo.nginx.com/api/2/http/requests"
  • accepted and discarded requests, responses, received and sent bytes in a particular HTTP server zone, for example, zone named server_zone:

    $ curl -X DELETE "http://demo.nginx.com/api/2/http/server_zones/server_zone"
  • cache hits and cache misses in a particular cache zone, for example, cache_zone :

    $ curl -X DELETE "http://demo.nginx.com/api/2/http/caches/cache_zone"
  • statistics for a particular http upstream server in an http upstream server group, for example, server1, as well as queue statistics:

    $ curl -X DELETE "http://demo.nginx.com/api/2/http/upstreams/server1"
  • accepted and discarded connections, sessions, received and sent bytes in a particular stream server zone, for example, zone named server_zone

    $ curl -X DELETE "http://demo.nginx.com/api/2/stream/server_zones/server_zone"
  • statistics for a particular stream upstream server in a stream upstream server group, for example, server1:

    $ curl -X DELETE "http://demo.nginx.com/api/2/stream/upstreams/server1"

Enabling the Swagger UI

NGINX Plus contains an integrated Swagger UI page that allows you to explore the REST API documentation and send API commands with the graphical user interface.

To turn on the Swagger UI:

  1. Specify the API location with restricted access control.
  2. Create a location for Swagger UI, for example, /swagger-ui. By default the UI is located in the root directory specified by the root directive, for example, /usr/share/nginx/html:

    http {
        server {
            listen 192.168.1.23;
    
            location /swagger-ui {
                root   /usr/share/nginx/html;
            }
        }
    }

    Using the Swagger UI

    To access the Swagger UI page:

    1. In the address bar of your browser, type-in the address of Swagger UI, in our example the address is http://192.168.1.23/swagger-ui/:

      Swagger UI

    2. If you have configured the HTTPS protocol for the Swagger UI page, you will need to choose the “HTTPS” scheme in the “Schemes” menu.
    3. Click on the operation you want to fulfil.
    4. Click “Try it out”.
    5. Fill in the obligatory fields, if required. Generally, the required field is the name of the shared memory zone.
    6. As an option you can display only particular fields. In the “Fields” line specify the fields you want to be displayed separated by commas. If no fields are specified, then all fields are displayed.

    7. Click “Execute”. The result and the corresponding HTTP error code will be displayed below the “Execute” command.

    API Live Examples

    NGINX provides live examples of JSON data and Swagger UI on a demo website.

    Live example of JSON data: demo.nginx.com/api/2/

    You can send an API command with curl or with a browser:

    https://demo.nginx.com/api/2/
    https://demo.nginx.com/api/2/nginx?fields=version,build
    https://demo.nginx.com/api/2/http/caches/http_cache
    https://demo.nginx.com/api/2/http/upstreams
    https://demo.nginx.com/api/2/http/upstreams/demo-backend
    https://demo.nginx.com/api/2/http/upstreams/demo-backend/servers/0

    The Swagger UI demo page: https://demo.nginx.com/swagger-ui/

    Swagger UI

    Swagger UI from NGINX Plus

    Live examples operate in the read-only mode, resetting the statistics via the DELETE method and creating/modifying upstream servers with the POST/PATCH methods are not available. Also note that as the demo API is served over the HTTPS protocol, it is required to choose the “HTTPS” scheme in the “Schemes” menu on the Swagger UI demo page.

    Monitoring NGINX with Amplify

    Amplify is a monitoring tool that can be used to obtain additional insights into nginx performance.

    Amplify is developed and maintained by Nginx, Inc.

    With Amplify it is possible to collect and aggregate metrics across nginx servers, and present a coherent set of visualizations of the key performance data, such as active connections or requests per second. It is also easy to quickly check for any performance degradations, traffic anomalies. With Amplify static analyzer it’s possible to also get a deeper insight into the nginx configuration in general.

    NGINX Amplify

    In order to use Amplify, a small Python-based agent software (Amplify Agent) should be installed.

    For more information about Amplify, please check the official documentation here.