Inspect Dovecot metrics safely with doveadm stats

You will finish with a small, repeatable workflow for reading Dovecot statistics and managing a temporary metric with doveadm stats. The examples use Dovecot 2.3.21 from the installed dovecot-core package. Allow about fifteen minutes, plus time to obtain access to the Dovecot statistics socket if your account cannot read it.

This guide assumes a running Dovecot installation and a shell on the server. Reading the socket is normally an administrator task on a packaged installation. Commands that add or remove metrics change the running statistics configuration; use an account authorised to administer Dovecot and record what you changed.

1. Check the installed command

Start with read-only checks. They do not change Dovecot or its counters:

$ command -v doveadm
/usr/bin/doveadm
$ dovecot --version
2.3.21 (47349e2482)
$ dpkg-query -W -f='${Package} ${Version}\n' dovecot-core
dovecot-core 1:2.3.21+dfsg1-2ubuntu6.5

Keep the version beside any operational notes. Dovecot statistics commands have changed across major releases, and a manpage from another machine can describe a different interface. On this installation, the command's usage lists add, dump and remove. The installed manpage also documents top and reset, but they are not shown by this binary's usage output. Treat the binary and its local package as the final authority if they disagree.

Checkpoint: if command -v finds a different path, stop and inspect that installation before copying any examples into automation.

2. Test access to the statistics socket

Ask for a dump without changing anything:

$ doveadm stats dump

A working installation returns statistics data. The exact columns depend on the configured metrics and Dovecot version. On a machine where the invoking account cannot connect, the useful failure looks like this:

Error: net_connect_unix(/run/dovecot/stats-writer) failed: Permission denied

That is an access problem, not proof that statistics are empty or disabled. Do not work around it by making the socket world-readable. Ask the Dovecot administrator which account or group is intended to run doveadm, then retry under that account. You can inspect the socket's ownership without changing it:

$ stat -c '%A %U %G %n' /run/dovecot/stats-writer

The -s option selects a different statistics socket path when the server deliberately exposes one:

$ doveadm stats dump -s /path/to/stats.socket

Replace the placeholder with a path from your Dovecot configuration. Do not guess a socket or create one in a shared directory.

3. Read a filtered dump

The dump command can report a metric type and an optional filter. The documented types are command, session, user, domain, ip and global. Filters include a wildcard user, domain, session identifier, IP address, session start time, or the literal connected:

$ doveadm stats dump user '[email protected]'
$ doveadm stats dump session connected
$ doveadm stats dump ip 'ip=192.0.2.10/32'

These are examples of argument shape, not a claim that those records exist on your server. Quote filters so the shell does not reinterpret wildcard characters or other punctuation. If your installed binary rejects a type or filter, read its local manpage and command usage again, then check the Dovecot version before changing configuration.

To use a custom socket, put -s before the type and filter. The command writes its report to standard output, so redirect it only after choosing a new destination:

$ doveadm stats dump -s /path/to/stats.socket global > /tmp/dovecot-stats.txt
$ test -s /tmp/dovecot-stats.txt && echo 'stats dump is non-empty'
stats dump is non-empty

The temporary file may contain user, session or network identifiers. Protect it according to your local handling rules and remove it when it is no longer needed. Do not publish a raw dump in a bug report without checking for sensitive data.

4. Add a temporary metric

stats add creates a metric in the running statistics process. The change is not a permanent configuration edit: the Dovecot documentation says dynamically added metrics do not survive a configuration reload. Still, it affects monitoring and can add work, so use a narrowly scoped name and filter.

$ sudo doveadm stats add \
    --description 'IMAP SELECT commands' \
    --fields 'bytes_in bytes_out' \
    imap_select \
    'event=imap_command_finished AND cmd_name=SELECT'

sudo is only an example of privilege elevation. Use your site's approved administrator method. The metric name and filter are examples from Dovecot's statistics model; check the events and fields available in your release before relying on the result. The manpage also documents --exporter, --exporter-include and --group_by for exporting or grouping metric data. Add those options only when you have a defined consumer and have verified the installed command's spelling.

Checkpoint: immediately verify that the metric is visible in a dump or in the monitoring output that consumes it. If it is not present, check the command's exit status, the event name, and whether matching traffic has occurred.

5. Remove the temporary metric

Removing a metric changes the running statistics definition. Before doing it, save the exact name from your change record. This is the recovery path for the example above:

$ sudo doveadm stats remove imap_select

There is no general undo history in the command. Recovery means running the original stats add command again, with the same description, fields, exporter options and filter. Keep that command in the change record until the metric is no longer needed. If the metric was created by a configuration or deployment process, restore it through that process instead of making an untracked manual edit.

6. Treat resets as a deliberate operation

Resetting statistics destroys the baseline used by comparisons and alerts. The installed manpage describes doveadm stats reset, and the Dovecot 2.3 documentation also describes reset-after-dump behaviour in the statistics interface. Do not run a reset during an investigation merely to make the next output look tidy:

$ sudo doveadm stats reset

First capture the current dump, record the reason and obtain the normal change approval for your service. If the command is unavailable on your installed 2.3.21 binary, do not substitute an undocumented variant. Check the local command usage and package documentation, then use the supported operation for that build. A reset cannot restore the lost counters; recovery is limited to waiting for new measurements.

Common traps

• A permission error on stats-writer is an account or socket-path issue. It is not fixed by changing filters.
• doveadm stats is version-sensitive. Compare dovecot --version, the local manpage and the binary's usage before using a copied command.
• Shell redirection creates or truncates the destination before the command finishes. Use a new file such as /tmp/dovecot-stats.txt, and check its contents before replacing a report.
• Metric additions are runtime changes and may disappear after reload. Record them in the system that owns your configuration if they must return.
• Statistics output can contain identifiers. Treat saved dumps as operational data, not harmless command output.