banshee/services-collection/services/apache/https/server-status

Apache status

Returns the busy and idle workers of an Apache httpd server, the share of its scoreboard busy, and its requests per second, read from its server-status page in machine-readable form (?auto) over HTTP. Three watches are offered, each one set on the probe.

Versions

Apache httpd 2.4, with mod_status; the machine-readable form has kept its keys since 2.2. Generic: no folder of version.

How it works

One GET to the address of the status page, ?auto added when the address carries no query; nothing else is sent. The page answers one Key: value line per figure:

Total Accesses: 131
Total kBytes: 296
BusyWorkers: 1
IdleWorkers: 74
Scoreboard: ______W_____________________________________________________________________..........

busy and idle are BusyWorkers and IdleWorkers.
busy-percent is BusyWorkers against the length of Scoreboard, one character per worker slot the server may run (ServerLimit × ThreadsPerChild under the event and worker MPMs, ServerLimit under prefork). At 100 %, a new request waits for a worker.
requests is the rate of Total Accesses 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.
A server that refuses the connection, or does not answer in the delay of protocol:http:timeout, is critical: "Apache down". A code 401, 403 or 404 stops the collector misconfigured; any other code but 200 unreachable. A page without BusyWorkers, IdleWorkers and Scoreboard stops it misconfigured, as does a page without Total Accesses (ExtendedStatus Off).

Prerequisites

mod_status loaded (a2enmod status on Debian and Ubuntu, loaded by default on RHEL), with ExtendedStatus On, the default since Apache 2.3.6.
A location that serves the page, open to the poller's address only:

<Location "/server-status">
    SetHandler server-status
    Require ip 192.0.2.10
</Location>

192.0.2.10 stands for the poller's address. Reload Apache (apachectl configtest && systemctl reload apache2, or httpd on RHEL).

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

Variables

Name	Label	Says	Default
`apache:url`	Status page address	the address of the `server-status` page; the collector adds `?auto`	—

Outputs

Name	Label	Unit	Per instance
`busy`	Busy workers	—	no
`idle`	Idle workers	—	no
`busy-percent`	Scoreboard busy	%	no
`requests`	Requests	requests/s	no

Watches

Name	Title	Kind	Defaults	Checked by default
`saturation`	Workers saturated	above a threshold, on `busy-percent`	warning above 80 %, critical above 95 %, for 3 runs	yes
`no-idle`	No idle worker	below a threshold, on `idle`	warning below 1, for 3 runs	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 scoreboard counts the slots the server may ever run, which can exceed MaxRequestWorkers: when it does, the server is full before busy-percent reaches 100 %, and the thresholds are lowered on the probe.
The page counts the whole server, every virtual host together.
A restart of Apache sets Total Accesses back to zero: the request rate is skipped for one run.
An address that already carries a query is used as is: it must then ask for auto itself.
Not checked against an Apache: the keys are those the documentation of mod_status gives (httpd.apache.org).