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–2025, The Cyrus Team

3.10.2                                            Jun 27, 2025                                     PROMSTATSD(8)