NAME

       promstatsd - Cyrus IMAP documentation

       Cyrus Prometheus statistics collating daemon

SYNOPSIS

          promstatsd [ -C config-file ] [ -v ] [ -f 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 report at the specified frequency.
       If the optional -f frequency argument is not provided, the prometheus_update_freq from imapd.conf(5) will
       be  used,  which  defaults  to  10  seconds.   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 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 once and exit.

       -c     Clean up the stats directory and exit.

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

       -f frequency
              Update  the  report  every  frequency  seconds.  If not specified, the prometheus_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

SEE ALSO

       imapd.conf(5), cyrus.conf(5), httpd(8),

AUTHOR

       The Cyrus Team

COPYRIGHT

       1993–2024, The Cyrus Team