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