banshee/services-collection/services/nginx/https/stub-status

nginx status

Returns the connections of an nginx server (active, reading, writing, waiting), its requests per second, and the connections it had to drop, read from its stub_status page over HTTP. Three watches are offered, each one set on the probe.

Versions

Generic: the page of the module ngx_http_stub_status_module has kept its form since nginx 1.x. nginx Plus and its API are not read here.

How it works

One GET to the address of the status page; nothing else is sent. The page answers, in plain text:

Active connections: 291
server accepts handled requests
 16630948 16630948 31070465
Reading: 6 Writing: 179 Waiting: 106

connections is Active connections, the waiting ones included; reading, writing and waiting split them.
requests is the rate of the requests counter between this run and the previous one, per second. At the first run there is no rate yet: the run is skipped, and the values come at the next.
dropped is accepts minus handled: the connections nginx accepted and closed at once because worker_connections was reached. It only grows until nginx restarts; "Connections dropped" raises when it grows.
A server that refuses the connection, or does not answer in the delay of protocol:http:timeout, is critical: "nginx down". A code 401, 403 or 404 on the page stops the collector misconfigured; any other code but 200 unreachable. A page that is not a stub_status page stops it misconfigured.

Prerequisites

nginx built with ngx_http_stub_status_module (nginx -V lists --with-http_stub_status_module; the Debian, Ubuntu, RHEL and official nginx.org packages have it).
A location that serves it, open to the poller's address only, for instance in the server block of a site:

location = /nginx_status {
    stub_status;
    allow 192.0.2.10;
    deny all;
}

192.0.2.10 stands for the poller's address. Reload nginx (nginx -t && systemctl reload nginx).

Its full address in the variable nginx:url, reachable from the poller.
An account in protocol:http:user and protocol:http:password only when the location asks for one (auth_basic); it goes to https:// only.

Variables

Name	Label	Says	Default
`nginx:url`	Status page address	the address of the `stub_status` page	—

Outputs

Name	Label	Unit	Per instance
`connections`	Active connections	—	no
`reading`	Connections reading a request	—	no
`writing`	Connections writing a response	—	no
`waiting`	Idle connections waiting	—	no
`requests`	Requests	requests/s	no
`dropped`	Connections dropped since start	—	no

Watches

Name	Title	Kind	Defaults	Checked by default
`dropped`	Connections dropped	increase, on `dropped`	warning beyond 0 in 1 h	yes
`busy`	Many active connections	above a threshold, on `connections`	no threshold: set one on the probe	no
`requests-unusual`	Unusual request rate	off its habit, on `requests`	normal sensitivity	no

"Unusual request rate" needs the history of the measure: until the poller has learnt it, the watch says it is learning and raises nothing.

Limits

The page counts the whole nginx server, every site together: no figure per site.
A restart of nginx sets its counters back to zero: the request rate is skipped for one run.
Not checked against an nginx: the form of the page is the one the documentation of ngx_http_stub_status_module gives (nginx.org).