DOVEADM-STATS(1)

💅 DOVEADM-STATS(1) — the doveadm-stats page, bestie edition

okay so hi. you're looking at the manual page for doveadm-stats from Dovecot, and honestly? it's giving "tiny page, big power." it's short, it's cute, it does exactly what it says on the tin. let's get into it 🎀

---

✨ NAME ✨

doveadm-stats — Inspect or reset stats. that's it. that's the whole vibe. 👑

---

🌸 SYNOPSIS 🌸

doveadm [GLOBAL OPTIONS] stats add [ --description <string> ] [
--exporter <name> ] [ --exporter-include <fields> ] [ --fields <fields>
] [--group_by <fields> ] name <filter>

doveadm [GLOBAL OPTIONS] stats dump [ -s <stats socket path> ] [ -r ] [
-f <fields> ]

doveadm [GLOBAL OPTIONS] stats top [-s <stats socket path>] [-b] [sort
<field>]

doveadm [GLOBAL OPTIONS] stats remove [ <name> ]

doveadm [GLOBAL OPTIONS] stats reopen

---

🦋 DESCRIPTION 🦋

Commands to inspect and edit Dovecot stats/metrics generation. look at her. she's the stats control room. 👀✨

---

💖 GLOBAL OPTIONS 💖

these are the global doveadm(1) options, so they work for everybody in the doveadm friend group, not just stats:

• -D — Enables verbosity and debug messages. basically: "tell me EVERYTHING." 🗣️
• -O — Do not read any config file, just use defaults. The dovecot_storage_version setting defaults to the latest version, but can be overridden with -o. no cap, this one just ignores your config entirely. 🙈
• -k — Preserve entire environment for doveadm, not just import_environment setting. keep the whole env, don't be picky about it. 💅
• -v — Enables verbosity, including progress counter. yay, numbers going up. 📈
• -i instance-name — If using multiple Dovecot instances, choose the config file based on this instance name. See instance_name setting for more information. it's giving "which twin are you." 👯
• -c config-file — Read configuration from the given config-file. By default it first reads config socket, and then falls back to /etc/dovecot/dovecot.conf. You can also point this to config socket of some instance running compatible version. so many options, so little time. 🫶
• -o setting=value — Overrides the configuration setting from /etc/dovecot/dovecot.conf and from the userdb with the given value. In order to override multiple settings, the -o option may be specified multiple times. stack 'em like bracelets. 🌈

---

🔥 COMMANDS 🔥

🌟 stats add

doveadm [GLOBAL OPTIONS] stats add [ --description <string> ] [
--exporter <name> ] [ --exporter-include <fields> ] [ --fields <fields>
] [--group_by <fields> ] name <filter>

doveadm stats add is used to add metrics to statistics. new metric just dropped. ✨

💜 OPTIONS

• --description string — Human-readable description of the metric. This is included in the HELP text sent to OpenMetrics. be nice, someone's gonna read it. 🎀
• --exporter name — Export events matching the filter with this event exporter. If empty, the events are used only for statistics, and no exporting is done. lowkey "leave blank and she minds her business." 🧚
• --exporter-include fields — Specifies which parts of the event are exported to the serialized event. The fields are space-separated. space-separated!! not comma!! iykyk. 🫶
• --fields fields — A list of fields included in the metric. All events have a default duration field that does not need to be listed explicitly. so don't list duration, she's already there, she's an icon. 👑
• --group-by fields — Creates a new group_by for dynamically generating sub-metrics based on the specified field's values. sub-metrics. sub-metrics everywhere. 🦋

🍓 ARGUMENTS

• name — Metric name. just the name. call her by her name. 💅
• filter — Filter options:
  • user=<wildcard> — Match user.
  • domain=<wildcard> — Match DNS domain name.
  • session=<str> — Match session identifier.
  • ip=<ip>[/<mask>] — Match local or remote IP.
  • since=<timestamp> — Match session start time.
  • connected — Show only connected sessions.

---

🌈 stats dump

doveadm [GLOBAL OPTIONS] stats dump [ -s <stats socket path> ] [ -r ] [
-f <fields> ]

doveadm stats dump is used to output statistics. dump it, queen. 📤

💀 OPTIONS

• -f — TODO. yes bestie, the manpage literally just says TODO. we don't know. nobody knows. it remains a mystery. 😭
• -r — Resets statistics after dumping. dump AND reset, a double feature. 🔥
• -s socketpath — Stats socket path. tell her where the socket lives. 🏠

---

🎀 stats remove

doveadm [GLOBAL OPTIONS] stats remove [ <name> ]

doveadm stats remove is used to remove metrics from statistics. bye bestie 👋 (affectionate) (necessary)

💜 ARGUMENTS

• name — The metric name to remove. that's the one getting yeeted. 🚀

---

⭐ stats reopen

doveadm [GLOBAL OPTIONS] stats reopen

doveadm stats reopen is used to reopen any file exporter files. sometimes you just gotta close the door and open it again, spiritually. 🚪✨

---

😭 REPORTING BUGS 😭

Report bugs, including doveconf -n output, to the Dovecot Mailing List ⟨dovecot@dovecot.org⟩. Information about reporting bugs is available at: ⟨https://dovecot.org/bugreport.html⟩

fr fr include the doveconf -n output, they're gonna ask for it anyway. save yourself the round trip. 🫶

---

👀 SEE ALSO 👀

• doveadm(1)

---

and that's the whole page, bestie. this was DOVEADM-STATS(1) from the Dovecot manual, source/version f979264, dated April 2026. go forth and inspect some stats. slay. 💅✨🦋