Live Activity Monitoring

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 R14 - 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).

  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. Starting from R16, the status and upstream_conf modules will be removed and completely superseded with the api module.

Prerequisites

• NGINX Plus R13 and later for NGINX Plus REST API and the Dashboard
• Data for statistics (see Gathering Data to Appear in Statistics)

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 HTTP and TCP server to appear in statistics, specify the status_zone directive. 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 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 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
  

Configuring the API

To enable the API:

• In the http context, specify a server block that will be responsible for the API:

  http {
      server {
          # your api configuration will be here
      }
  }
  

• Create a location for API requests and specify the api directive in this location:

  http {
      # ...
      server {
          listen 192.168.1.23;
          # ...
          location /api {
              api;
              # ...
          }
      }
  }
  

• In order to make changes with the API, such as resetting statistics counters, managing upstream servers on-the-fly or key-value storage, managing upstream servers from the Dashboard, enable the read-write mode for the API by specifying the write=on parameter for the api directive:

  http {
      # ...
      server {
          listen 192.168.1.23;
          # ...
          location /api {
              api write=on;
              # ...
          }
      }
  }
  

• It is recommended restricting access to this location, for example, allow access only from local networks with allow and deny directives:

  http {
      # ...
      server {
          listen 192.168.1.23;
          # ...
          location /api {
              api write=on;
              allow 192.168.1.0/24;
              deny  all;
          }
      }
  }
  

• When the API is enabled in the write mode, it is recommended restricting access to PATCH, POST, and DELETE methods to particular users. This can be done by implementing HTTP basic authentication:

  http {
      ...
      server {
          listen 192.168.1.23;
          # ...
          location /api {
              limit_except GET {
                  auth_basic "NGINX Plus API";
                  auth_basic_user_file /path/to/passwd/file;
              }
              api   write=on;
              allow 192.168.1.0/24;
              deny  all;
          }
      }
  }
  

• 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 /api {
              limit_except GET {
                  auth_basic "NGINX Plus API";
                  auth_basic_user_file /path/to/passwd/file;
              }
              api   write=on;
              allow 192.168.1.0/24;
              deny  all;
          }
          location = /dashboard.html {
              root   /usr/share/nginx/html;
          }
      }
  }
  

• Enable the Swagger UI by creating a location for it, for example, /swagger-ui. By default Swagger 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 /api {
              limit_except GET {
                  auth_basic "NGINX Plus API";
                  auth_basic_user_file /path/to/passwd/file;
              }
              api   write=on;
              allow 192.168.1.0/24;
              deny  all;
          }
          location = /dashboard.html {
              root   /usr/share/nginx/html;
          }
          location /swagger-ui {
              root   /usr/share/nginx/html;
          }
      }
  }
  

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.

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. Upstream servers can be added with POST requests and modified with PATCH requests. See Managing Upstream Servers with the API for more information.

The requests are sent in the JSON format that allows you to connect the stats to monitoring tools or dashboards that support JSON.

curl -s 'https://demo.nginx.com/api/3/' | json_pp

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

curl -s 'https://demo.nginx.com/api/3/nginx' | json_pp

    {
       "version" : "1.13.10",
       "build" : "nginx-plus-r15",
       "generation" : 13,
       "timestamp" : "2018-04-19T11:49:40.211Z",
       "pid" : 578,
       "ppid" : 90931,
       "address" : "206.251.255.64",
       "load_timestamp" : "2018-04-14T10:00:00.358Z"
    }

curl -s 'https://demo.nginx.com/api/3/nginx?fields=version,build' | json_pp

{
   "version" : "1.13.10",
   "build" : "nginx-plus-r15"
}

curl -X DELETE -s 'http://192.168.1.23/api/3/processes'

curl -X DELETE  -s 'http://192.168.1.23/api/3/connections'

Managing Upstream Servers with the API

The NGINX Plus REST API supports POST and PATCH HTTP methods to dynamically add a server to the upstream group or modify server parameters.

To dynamically change the configuration of an upstream group, send an HTTP request with the appropriate API method. The following examples use the curl command, but any mechanism for making HTTP requests is supported. All request bodies and responses are in JSON format.

The URI specifies the following information in this order:

• The hostname or IP address of the node that handles the request (in the following examples, 192.168.1.23)
• The location where the api directive appears (api)
• The API version (3)
• The name of the upstream group, complete its place in the NGINX Plus configuration hierarchy represented as a slash-separated path (http/upstreams/appservers)

For example, to add a new server to the appservers upstream group, send the following curl command:

curl -X POST -d '{ \
   "server": "10.0.0.1:8089", \
   "weight": 4, \
   "max_conns": 0, \
   "max_fails": 0, \
   "fail_timeout": "10s", \
   "slow_start": "10s", \
   "backup": true, \
   "down": true \
 }' -s 'http://192.168.1.23/api/3/http/upstreams/appservers/servers'

To remove a server from the upstream group:

curl -X DELETE -s 'http://192.168.1.23/api/3/http/upstreams/appservers/servers/0'

To set the down parameter for the first server in the group (with ID 0):

curl -X PATCH -d '{ "down": true }' -s 'http://192.168.1.23/api/3/http/upstreams/appservers/servers/0'

curl -s 'http://demo.nginx.com/api/3/'
curl -s 'http://demo.nginx.com/api/3/nginx?fields=version,build'
curl -s 'http://demo.nginx.com/api/3/http/caches/http_cache'
curl -s 'http://demo.nginx.com/api/3/http/upstreams/'
curl -s 'http://demo.nginx.com/api/3/http/upstreams/demo-backend'
curl -s 'http://demo.nginx.com/api/3/http/upstreams/demo-backend/servers/0'

Monitoring NGINX with Amplify

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

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.

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