promstatsd

Cyrus Prometheus statistics collating daemon

Synopsis

promstatsd [ -C config-file ] [ -v ] [ -f service-frequency ] [ -d ]

promstatsd [ -C config-file ] [ -v ] -c

promstatsd [ -C config-file ] [ -v ] -1

Description

promstatsd is the Cyrus Prometheus statistics collating daemon.

When the prometheus_enabled 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 httpd(8) at the "/metrics" URL, if "prometheus" has been set in httpmodules in imapd.conf(5).

promstatsd reads its configuration options out of the imapd.conf(5) file unless specified otherwise by -C.

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 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 cyrus.conf(5) (see 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 cyrus.conf(5) (see 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.

Options

-C config-file

Use the specified configuration file config-file rather than the default imapd.conf(5).

-D

Run the external debugger specified in the debug_command imapd.conf(5) option.

-1

Update the report(s) once and exit.

-c

Clean up the stats directory and exit.

-d

Debug mode -- promstatsd will not background itself, for aid in debugging.

-f service-frequency

Update the service report every service-frequency seconds. If not specified, the prometheus_service_update_freq from imapd.conf(5) will be used, which defaults to 10 seconds.

-v

Increase verbosity. Can be specified multiple times.

Examples

To regularly produce a report that Prometheus can consume, promstatsd must be run from the DAEMON section of 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 cyrus.conf(5) as per the second synopsis, like so:

START {
    statscleanup  cmd="promstatsd -c"
}

History

Files