promstatsd - Cyrus IMAP documentation

       The Cyrus Team

       1993–2025, The Cyrus Team

3.10.2                                            Jun 27, 2025                                     PROMSTATSD(8)

promstatsd is the Cyrus Prometheus statistics collating daemon.

       When  the  prometheus_enabledimapd.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 -ffrequency 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.

       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 {
              promstatsdcmd="promstatsd"
          }

       Toensureacleanstatisticalstateatstartup,promstatsdmustberunfromtheSTARTsectionofcyrus.conf(5)asperthesecondsynopsis,likeso:START{statscleanupcmd="promstatsd-c"}

       promstatsd - Cyrus IMAP documentation

       Cyrus Prometheus statistics collating daemon

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

       -D     Run the external debugger specified in the debug_commandimapd.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.

       -ffrequency
              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.

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

promstatsd [ -Cconfig-file ] [ -v ] [ -ffrequency ] [ -d ]

          promstatsd [ -Cconfig-file ] [ -v ] -cpromstatsd [ -Cconfig-file ] [ -v ] -1