Skip to content

Check nginx-status

Overview

This check provides global nginx basic status information from the stub_status module.

For this check to work, enable the stub_status module:

# /etc/nginx/nginx.conf
server {
    location /server-status {
        stub_status;
        allow 127.0.0.1;    # only allow requests from localhost
        deny all;           # deny all other hosts   
    }
}

Due to the fact that the stub_status \<https://github.com/nginx/nginx/blob/master/src/http/modules/ngx_http_stub_status_module.c> module increments each counter at the exact moment a new request "object" is created, even before any request header (including the URI) is parsed, there is unfortunately no way to tell Nginx not to count requests for a given URI. In other words: It is not possible to get stats only for a specific server block.

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/nginx-status
Check Interval Recommendation Once a minute
Can be called without parameters Yes
Compiled for Windows No
Requirements Enable stub_status
Perfdata compatible with Prometheus Yes

Help

usage: nginx-status [-h] [-V] [--always-ok] [-c CRIT] [--insecure]
                    [--no-proxy] [--timeout TIMEOUT] [-u URL] [-w WARN]
                    [--test TEST]

This check provides NGINX basic status information.

options:
  -h, --help           show this help message and exit
  -V, --version        show program's version number and exit
  --always-ok          Always returns OK.
  -c, --critical CRIT  Set the CRIT threshold for the number of active
                       connections. Default: >= 486
  --insecure           This option explicitly allows to perform "insecure" SSL
                       connections. Default: False
  --no-proxy           Do not use a proxy. Default: False
  --timeout TIMEOUT    Network timeout in seconds. Default: 8 (seconds)
  -u, --url URL        NGINX Server Status URL. Default:
                       http://localhost/server-status
  -w, --warning WARN   Set the WARN threshold for the number of active
                       connections. Default: >= 460
  --test TEST          For unit tests. Needs "path-to-stdout-file,path-to-
                       stderr-file,expected-retc".

Usage Examples

./nginx-status --url http://nginx/server-status --warning 460 --critical 486

Output:

1 active concurrent conn; 3 accepted conns, 3 handled conns, 3 reqs; 1.0 req per conn; currently 0 receiving reqs, 1 sending response, 0 keep-alive conns

States

  • WARN if the number of total handled connections is not equal to the number of total handled requests.
  • WARN or CRIT if the active connections are above the specified thresholds.

Perfdata / Metrics

Name Type Description
nginx_connections_accepted Continous Counter The total number of accepted client connections.
nginx_connections_active None The current number of active client connections including Waiting connections. One user can have several concurrent connections to a server.
nginx_connections_handled Continous Counter The total number of handled connections. Generally both values are the same unless some resource limits have been reached (for example, the worker_connections limit).
nginx_connections_reading None The current number of connections where nginx is reading the request header.
nginx_connections_waiting None The current number of idle client connections waiting for a request. This number depends on the keepalive_timeout.
nginx_connections_writing None The current number of connections where nginx is writing the response back to the client.
nginx_http_requests_total Continous Counter The total number of client requests.
nginx_requests_per_connection None The number of handled requests per connection.

Credits, License