PROMSTATSD(8)

💖 PROMSTATSD(8) 💖

okay bestie, welcome to the promstatsd(8) page from the Cyrus IMAP manual — she's the Cyrus Prometheus statistics collating daemon and she is thriving. 🫶

---

✨ NAME ✨

promstatsd — Cyrus IMAP documentation

Cyrus Prometheus statistics collating daemon 💅

---

🌸 SYNOPSIS 🌸

promstatsd [ -C config-file ] [ -v ] [ -f service-frequency ] [ -d ]

promstatsd [ -C config-file ] [ -v ] -c

promstatsd [ -C config-file ] [ -v ] -1

---

🦋 DESCRIPTION 🦋

promstatsd is the Cyrus Prometheus statistics collating daemon. that's her whole job and she eats every time. 🔥

when the prometheus_enabled setting in imapd.conf(5) is true, all the various Cyrus service processes start counting statistics as they run. promstatsd swoops in and collates all those stats into a text-based report that Prometheus can ingest. it's giving matchmaker but for numbers. ✨

the report promstatsd produces gets served by httpd(8) at the "/metrics" URL — but ONLY if "prometheus" has been set in httpmodules in imapd.conf(5). no config, no metrics, iykyk. 🙈

promstatsd reads her configuration options out of the imapd.conf(5) file, unless you say otherwise with -C.

first synopsis — promstatsd runs as a daemon, updating the service report and (optionally) the usage report at the frequencies set by the prometheus_service_update_freq and prometheus_usage_update_freq options in imapd.conf(5). those default to 10s and disabled, respectively. the optional -f service-frequency argument can override prometheus_service_update_freq. this invocation should be run from the DAEMON section of cyrus.conf(5) (see Examples below 👇).

second synopsis — promstatsd cleans up ALL the statistics files and then exits. 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 👇) so she can clean up after the previous run, before any new service processes get started. no cap, it's mandatory. 💀

third synopsis — promstatsd immediately updates the report(s) once, then exits. this is safe to use while another promstatsd process is running in daemon form. it's the move when you need the report updated right now for some reason and you cannot wait for the daemon's next update. main character urgency. 👑

---

💅 OPTIONS 💅

• -C config-file — use the specified configuration file config-file instead of the default imapd.conf(5).
• -D — run the external debugger specified in the debug_command option of imapd.conf(5).
• -1 — update the report(s) once and exit.
• -c — clean up the stats directory and exit.
• -d — debug mode — promstatsd will not background herself, for aid in debugging.
• -f service-frequency — update the service report every service-frequency seconds. if you don't specify it, the prometheus_service_update_freq from imapd.conf(5) gets used, and that defaults to 10 seconds.
• -v — increase verbosity. can be specified multiple times. stack 'em. 📚

---

🎀 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 make sure the statistical state is clean 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 📜

literally nothing here bestie, it's just vibes and empty space. 🌈

📁 FILES 📁

also empty. the void said hi. 🦋

👀 SEE ALSO 👀

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

---

💜 AUTHOR 💜

The Cyrus Team 👑

---

🍓 COPYRIGHT 🍓

1993–2026, The Cyrus Team

---

and that's the whole page, bestie — no crumbs left. 🌸✨

version 3.12.4, dated Sep 09, 2026 — mwah, slay, periodt. 💅🎀🫶