Skip to content

Check mod-qos-stats

Overview

Monitors Apache mod_qos status via the machine-readable status handler. Reports current connection and request limits, active connections, and quality of service metrics for all configured virtual hosts. This check is primarily useful for statistical purposes and visualization over time in Grafana.

Important Notes:

  • Due to the behavior of mod_qos (which adds waiting times in case of overuse rather than rejecting requests), this check always returns OK and does not issue warnings
  • Requires mod_qos to be enabled and a Location configured with SetHandler qos-viewer

Data Collection:

  • Fetches the machine-readable status page from the mod_qos handler (?auto parameter)
  • Parses per-virtual-host connection and request limit entries, including QS_AllConn, QS_LocRequestLimitMatch, QS_LocKBytesPerSecLimitMatch, QS_CondLocRequestLimitMatch, and QS_SrvMaxConn
  • Perfdata metric names are composed of the mod_qos configuration option suffixed by the request pattern (e.g. QS_LocRequestLimitMatch_[^.*$])

Fact Sheet

Fact Value
Check Plugin Download https://github.com/Linuxfabrik/monitoring-plugins/tree/main/check-plugins/mod-qos-stats
Nagios/Icinga Check Name check_mod_qos_stats
Check Interval Recommendation Every minute
Can be called without parameters Yes
Runs on Cross-platform
Compiled for Windows No
Requirements Enable mod_qos and configure a Location for SetHandler qos-viewer

Help

usage: mod-qos-stats [-h] [-V] [--always-ok] [--insecure] [--no-proxy]
                     [--test TEST] [--timeout TIMEOUT] [-u URL]

Monitors Apache mod_qos status via the machine-readable status handler.
Reports current connection and request limits, active connections, and quality
of service metrics. Alerts when connection or request limits are approached.

options:
  -h, --help         show this help message and exit
  -V, --version      show program's version number and exit
  --always-ok        Always returns OK.
  --insecure         This option explicitly allows insecure SSL connections.
  --no-proxy         Do not use a proxy.
  --test TEST        For unit tests. Needs "path-to-stdout-file,path-to-
                     stderr-file,expected-retc".
  --timeout TIMEOUT  Network timeout in seconds. Default: 8 (seconds)
  -u, --url URL      URL of the mod_qos machine-readable status handler.
                     Default: http://localhost/qos-status

Usage Examples

./mod-qos-stats --url http://webserver/qos-status

Output:

Everything is ok.

Type Host              Port Key                                   Configured Current 
---- ----              ---- ---                                   ---------- ------- 
base proxy.example.com 0    QS_AllConn (All)                      None       381     
virt www.example.com   443  QS_LocRequestLimitMatch ([^.*$])      90         3       
virt www.example.com   443  QS_LocKBytesPerSecLimitMatch ([^.*$]) 1250       14      
virt www.example.com   443  QS_CondLocRequestLimitMatch ([^.*$])  1          3       
virt www.example.com   443  QS_SrvMaxConn ([])                    100        0

States

  • Always returns OK.

Perfdata / Metrics

Depends on your mod_qos configuration. The configuration options are suffixed by their specified request pattern (path and query). For example:

Name Type Description
QS_AllConn_All Number Current number of all connections (global).
QS_CondLocRequestLimitMatch_[^.*$] Number Current conditional location request limit match count.
QS_LocKBytesPerSecLimitMatch_[^.*$] KB Current location KBytes per second limit match count.
QS_LocRequestLimitMatch_[^.*$] Number Current location request limit match count.
QS_SrvMaxConn_[] Number Current server max connection count.

Credits, License