---
name: "cyrus-promstatsd"
section: "8"
platform: "linux"
package: "cyrus-admin"
version: "3.10.2-1+deb13u2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/cyrus-promstatsd"
---

# cyrus-promstatsd(8)

Cyrus IMAP documentation Cyrus Prometheus statistics collating daemon

## 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)](/imapd.conf/5.md)* **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)](/httpd/8.md)* **at** **the "/metrics" URL, if "prometheus" has been set in httpmodules in** *[imapd.conf(5)](/imapd.conf/5.md)***.**

**promstatsd reads its configuration options out of the** *[imapd.conf(5)](/imapd.conf/5.md)* **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)](/imapd.conf/5.md)* **will be used, which defaults to 10 seconds.  This** **invocation should be run from the DAEMON section of** *[cyrus.conf(5)](/cyrus.conf/5.md)* **(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)](/cyrus.conf/5.md)* **(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)](/imapd.conf/5.md)***.**

- **-D**

  **Run the external debugger specified in the debug\_command** *[imapd.conf(5)](/imapd.conf/5.md)* **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)](/imapd.conf/5.md)* **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)](/cyrus.conf/5.md)* **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)](/cyrus.conf/5.md)* **as per the second synopsis,** **like so:**

```
START {
    statscleanup  cmd="promstatsd -c"
}
```

## HISTORY

## FILES

## SEE ALSO

*[imapd.conf(5)](/imapd.conf/5.md)***,** *[cyrus.conf(5)](/cyrus.conf/5.md)***,** *[httpd(8)](/httpd/8.md)***,**

## AUTHOR

**The Cyrus Team**

## COPYRIGHT

**1993–2025, The Cyrus Team**