.. cyrusman:: promstatsd(8)
Cyrus Prometheus statistics collating daemon
promstatsd [ -C config-file ] [ -v ] [ -f service-frequency ] [ -d ] promstatsd [ -C config-file ] [ -v ] -c promstatsd [ -C config-file ] [ -v ] -1
promstatsd is the Cyrus Prometheus statistics collating daemon.
When the prometheus_enabled :cyrusman:`imapd.conf(5)` setting is true, various Cyrus service processes will count statistics as they run. promstatsd collates these statistics into a text-based report that Prometheus can ingest.
The report produced by promstatsd is served by :cyrusman:`httpd(8)` at the "/metrics" URL, if "prometheus" has been set in httpmodules in :cyrusman:`imapd.conf(5)`.
promstatsd |default-conf-text|
In the first synopsis, promstatsd will run as a daemon, updating the service and (optionally) usage reports at the frequencies set by the prometheus_service_update_freq and prometheus_usage_update_freq :cyrusman:`imapd.conf(5)` options, which default to 10s and disabled, respectively. The optional -f service-frequency argument can be used to override prometheus_service_update_freq. This invocation should be run from the DAEMON section of :cyrusman:`cyrus.conf(5)` (see :ref:`promstatsd-examples` below).
In the second synopsis, promstatsd will clean up all statistics files and exit. The statistics Cyrus maintains are only valid while Cyrus is running, so this invocation must be run from the START section of :cyrusman:`cyrus.conf(5)` (see :ref:`promstatsd-examples` below) to clean up after the previous run, before new service processes are started.
In the third synopsis, promstatsd will immediately update the report(s) once, and then exit. This can be safely used while another promstatsd process runs in daemon form. It is useful if you need to update the report now for some reason, rather than waiting for the daemon's next update.
.. program:: promstatsd
.. option:: -C config-file
|cli-dash-c-text|
.. option:: -D
Run the external debugger specified in the **debug_command**
:cyrusman:`imapd.conf(5)` option.
.. option:: -1
Update the report(s) once and exit.
.. option:: -c
Clean up the stats directory and exit.
.. option:: -d
Debug mode -- **promstatsd** will not background itself, for aid in
debugging.
.. option:: -f service-frequency
Update the service report every *service-frequency* seconds. If not
specified, the **prometheus_service_update_freq** from
:cyrusman:`imapd.conf(5)` will be used, which defaults to 10 seconds.
.. option:: -v
Increase verbosity. Can be specified multiple times.
To regularly produce a report that Prometheus can consume, promstatsd must be run from the DAEMON section of :cyrusman:`cyrus.conf(5)` as per the first synopsis, like so:
DAEMON {
promstatsd cmd="promstatsd"
}
To ensure a clean statistical state at startup, promstatsd must be run from the START section of :cyrusman:`cyrus.conf(5)` as per the second synopsis, like so:
START {
statscleanup cmd="promstatsd -c"
}
:cyrusman:`imapd.conf(5)`, :cyrusman:`cyrus.conf(5)`, :cyrusman:`httpd(8)`,