Monitoring
**********

Cyrus IMAP supports monitoring using Prometheus.

To use this functionality, Cyrus IMAP must have been built with the "
--enable-http" configure option enabled.


Setup
=====

   * Set the *prometheus_enabled* setting in imapd.conf(5) to "yes"

   * Add the *prometheus* module to your *httpmodules* in
     imapd.conf(5)

   * Set the *prometheus_need_auth*, *prometheus_service_update_freq*,
     *prometheus_master_update_freq*, *prometheus_usage_update_freq*,
     and *prometheus_stats_dir* settings in imapd.conf(5) to taste

   * Add a job to run promstatsd(8) to the DAEMON section of
     cyrus.conf(5) (the actual daemon process)

   * Add a job to run "promstatsd -c" to the START section of
     cyrus.conf(5) (this cleans up the stats files from the previous
     run)

   * Configure your Prometheus server to scrape
     http://yourserver.example.com/metrics


Configuration options
=====================

      "prometheus_enabled:" 0

         Whether tracking of metrics for Prometheus is enabled.

      "prometheus_need_auth:" admin

         Authentication level required to fetch Prometheus metrics.

         Allowed values: *none*, *user*, *admin*

      "prometheus_service_update_freq:" 10s

         Frequency in at which promstatsd should re-collate its
         service statistics report.  The minimum value is 1 second.

         If no unit is specified, seconds is assumed.

      "prometheus_master_update_freq:" <none>

         Frequency in at which master should re-collate its statistics
         report. If not set, *prometheus_service_update_freq* is used.

         If no unit is specified, seconds is assumed.

      "prometheus_usage_update_freq:" <none>

         Frequency in at which promstatsd should re-collate its usage
         statistics report.  Note that this report is relatively
         expensive to produce.  If not set, usage statistics are not
         reported.

         Best to make this a multiple of
         *prometheus_service_update_freq*.

         If no unit is specified, seconds is assumed.

      "prometheus_stats_dir:" <none>

         Directory to use for gathering prometheus statistics.  If
         specified, must be an absolute path.  If not specified, the
         default path $configdirectory/stats/ will be used.  It may be
         advantageous to locate this directory on ephemeral storage.

Back to Administrator Guide
