**promstatsd**
**************

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),