PROMSTATSD(8)

📦
version 3.12.3 · 4 versions
, in ubuntu stonking

💅 PROMSTATSD — Cyrus IMAP

okay bestie, listen up 💖 this is promstatsd, part of the Cyrus IMAP docs. say it with me: Cyrus Prometheus statistics collating daemon. she's the one who gathers up everybody's little numbers and turns them into a report Prometheus can swallow. icon behaviour, honestly. 👑

✨ SYNOPSIS ✨

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

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

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

three whole moods, bestie. three ways to run her. pick your era. 🌸

🦋 DESCRIPTION 🦋

so promstatsd is the Cyrus Prometheus statistics collating daemon. that's the whole job title. she collates. she stats. she serves. periodt. 💅

here's the tea ☕ — when the prometheus_enabled setting in imapd.conf(5) is true, all the various Cyrus service processes start counting statistics as they run. and then promstatsd scoops all those numbers up and collates them into a text-based report that Prometheus can ingest. no cap, that's literally the pipeline. 🔥

that report she makes? it gets served by httpd(8) at the "/metrics" URL — but only if "prometheus" has been set in httpmodules inside imapd.conf(5). so don't come crying to her if you forgot to set that. 🙈

promstatsd reads her config options out of the imapd.conf(5) file, unless you tell her otherwise with -C. (she's flexible like that. main character energy.)

okay now the three synopsis moods, one by one:

first synopsis — she runs as a daemon, bestie. she'll keep updating the service report and (optionally) the usage report at whatever frequencies are set by the prometheus_service_update_freq and prometheus_usage_update_freq options in imapd.conf(5). those default to 10s and disabled, respectively. and the optional -f service-frequency argument can override prometheus_service_update_freq if you're feeling spicy. 🌶️ this invocation should be run from the DAEMON section of cyrus.conf(5) — there's an example down below if you need it.

second synopsis — she cleans up all the statistics files and dips. ✌️ important lore: 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) (example below 👇) so she can clean up after the previous run — and this has to happen before new service processes are started. order matters, diva. don't skip it.

third synopsis — she immediately updates the report(s) once, and then exits. that's it. one and done. and yes, this can be safely used while another promstatsd process is running in daemon form — no fighting, no drama, they play nice. super useful if you need the report updated right now for some reason instead of sitting around waiting for the daemon's next update. 💅

🎀 OPTIONS 🎀

  • -C config-file — use the specified configuration file config-file instead of the default imapd.conf(5). she's not locked in, she can read a different file. 🫶
  • -D — run the external debugger specified in the debug_command option in imapd.conf(5). for when things are giving "something is wrong" energy. 🔍
  • -1 — update the report(s) once and exit. one single update, then she's gone. ⭐
  • -c — clean up the stats directory and exit. bye bye statistics 🧹✨
  • -d — debug mode. promstatsd will not background itself, which helps with debugging. she stays right there in your face so you can watch her work. 😭
  • -f service-frequency — update the service report every service-frequency seconds. if you don't specify it, the prometheus_service_update_freq value from imapd.conf(5) gets used, and that defaults to 10 seconds. 🍓
  • -v — increase verbosity. and yes, you can specify it multiple times — stack it up, she'll talk more. 💬💬💬

🌈 EXAMPLES 🌈

example one — 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"
}

example two — 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"
}
okay genuinely use both of these. the daemon one keeps the metrics flowing, the cleanup one keeps your stats from being haunted by last run's ghosts. 👻

📜 HISTORY 📜

(nothing documented here, bestie. she contains multitudes but this section is empty. 🫥)

📁 FILES 📁

(also empty. no files listed. yes really. moving on. 💀)

👀 SEE ALSO 👀

go read those, iykyk. 📚

👑 AUTHOR 👑

The Cyrus Team. legends, fr fr. 💜

1993–2026, The Cyrus Team

and that's the whole page, bestie!! 🦋✨ you just read promstatsd from Cyrus IMAP version 3.12.3, dated Jul 15, 2026. go collate those statistics. slay. 💅🎀

📦 where this page comes from