This documentation is for Dovecot v2.x, see wiki1 for v1.x documentation.


Dovecot v2.1+ supports gathering statistics (CPU, disk usage, etc.) from mail processes (IMAP, POP3, LMTP, etc.) to the stats process. The stats process can later be queried what's going on in the system. With imap_stats plugin you can get per-command level statistics for IMAP commands.

There are different "zoom levels" you can look at the statistics:

Basic Configuration

mail_plugins = $mail_plugins stats
protocol imap {
  mail_plugins = $mail_plugins imap_stats
plugin {
  # how often to session statistics (must be set)
  stats_refresh = 30 secs
  # track per-IMAP command statistics (optional)
  stats_track_cmds = yes

You'll also need to give enough permissions for mail processes to be able to write to stats-mail fifo. For example if you use a single "vmail" user for mail access:

service stats {
  fifo_listener stats-mail {
    user = vmail
    mode = 0600

Memory usage configuration

The stats process attempts to keep memory usage below a specified amount. This value is only approximate because of extra overhead caused by malloc() itself.

stats_memory_limit = 16 M

Once the memory limit is reached, oldest statistics are freed from memory. Different statistics levels have different timeout limits, which are configured in:

stats_command_min_time = 1 mins
stats_domain_min_time = 12 hours
stats_ip_min_time = 12 hours
stats_session_min_time = 15 mins
stats_user_min_time = 1 hours

So for example the above means:

The stats process attempts to honor these min_time-settings, but if memory is tight it can go below these values to honor the stats_memory_limit setting.

Statistics gathered

Statistics gathered internally by the stats process:

Statistics gathered using the getrusage() system call:

The disk_input and disk_output attempt to count the actual read/write bytes to physical disk, so e.g. reads from OS's cache aren't counted. Note that not all operating systems and filesystem support this, instead they simply show these values always as 0.

Statistics gathered from /proc/self/io output (Linux-only):

Note that the above numbers are not only about disk I/O, but also about network I/O, Dovecot's IPC and every other kind of reads/writes as well.

Statistics gathered by Dovecot's lib-storage internally:

Note that statistics are collected only on backends so stats service doesn't do anything on directors and proxies.

doveadm stats


doveadm stats top [<sort field>]

The top command gives a very simple "top"-like view of connected sessions. The optional sort field is one of:

This "top" isn't very good, but a much better one can be found as a Perl script:, which also requires and


doveadm stats dump <level> [<filter>]

The dump command shows a raw output of the statistics. The level parameter is one of the levels listed at the top of this page (e.g. "session"). The filter can contain zero of more filters:

If nothing matches the filter, the output is a single empty line. Otherwise it begins with a header line followed by data lines. Each line has a list of fields separated by TABs. The header describes what the data fields are. The list of fields depends on what level you're listing. Some of the fields are:

Stats protocol

You can connect to stats process via $base_dir/stats UNIX socket, or you can simply add more UNIX/TCP listeners to the stats service, e.g.:

service stats {
  inet_listener {
    address =
    port = 24242

The protocol is almost entirely identical to doveadm stats dump command's parameters and output. The only difference is that you prefix your request with "EXPORT<tab>". For example:


The output will be identical to doveadm stats dump session connected command.

Carbon support

Since v2.2.27, you can configure dovecot to send statistics periodically in carbon format. To do this, configure

stats_carbon_server=ip:port # default port 2003
stats_carbon_name=hostname # do not use dots
stats_carbon_interval=30s # default is 30 seconds

service stats {
  # this is needed if you want stats to be sent when no one is connected

this will send all available global statistics in carbon format.

Statistics (last edited 2016-11-29 21:02:49 by AkiTuomi)