Recommended Metrics

This page lists recommended metrics that allow inspecting dovecot's behavior in the most general situations. More specialized situations might require further refinements or additional statistics. For an overview of how to gather statistics see Statistics. A list of all available events and their fields can be found here.

The following examples use the custom log-export exporter.

event_exporter log-export {
  format = json
  format_args = time-rfc3339
  transport = log
}

Dovecot Proxy

@metric_defaults = proxy contains:

auth_successes

Number of successful authentications. See auth_request_finished.

auth_failures

Number of unsuccessful authentications. See auth_request_finished. It may be useful to export these events into log:

metric auth_failures {
  exporter = log-export
}

login_aborted

Number of aborted logins, grouped by reason. See login_aborted.

Dovecot Backend

Generic authentication metrics

@metric_defaults = backend contains:

auth_successes

Number of successful authentications. See auth_request_finished.

auth_failures

Number of unsuccessful authentications. See auth_request_finished. These are not usually expected to happen in backends. It may be useful to export these events into log:

metric auth_failures {
  exporter = log-export
}

Basic mail access and delivery metrics

@metric_defaults = backend contains:

imap_commands

Number of IMAP commands, grouped by OK/NO/BAD tagged reply. See imap_command_finished.

mail_deliveries

Number of mails delivered. See mail_delivery_finished.

mail_submissions

Number of mails submitted for outside delivery (e.g. rejects, vacations). See smtp_submit_finished.

mail_user_session_finished

Number of mail sessions, including their RSS memory usage and user space CPU usage at the time when the session was finished. See mail_user_session_finished.

Email IO metrics

@metric_defaults = backend contains:

mail_read

Number of email GET requests to HTTP-based object storage. See http_request_finished.

mail_write

Number of email PUT requests to HTTP-based object storage. See http_request_finished.

mail_delete

Number of email DELETE requests to HTTP-based object storage. See http_request_finished.

FTS index IO/CPU metrics

fts_read

Number of FTS object GET requests to HTTP-based object storage, including size of the objects. See http_request_finished.

fts_write

Number of FTS object PUT requests to HTTP-based object storage, including size of the objects. See http_request_finished.

fts_delete

Number of FTS object DELETE requests to HTTP-based object storage. This is normally very close to fts_write. See http_request_finished.

indexer_worker_indexing_finished

Number of FTS indexing sessions, including the user space CPU usage. See indexer_worker_indexing_finished.

Index IO metrics

@metric_defaults = backend contains:

metacache_user_refresh_finished_refreshed_changed

Number of mail sessions where user's metacache was refreshed by listing index objects in storage, and new changes were found. See metacache_user_refresh_finished.

metacache_user_refresh_finished_refreshed_unchanged

Number of mail sessions where user's metacache was refreshed by listing index objects in storage, and metacache was already up-to-date. See metacache_user_refresh_finished.

metacache_mailbox_refresh_finished_refreshed_changed

Number of mailbox accesses where metacache was refreshed by listing index objects in storage, and new changes were found. See metacache_mailbox_refresh_finished.

metacache_mailbox_refresh_finished_refreshed_unchanged

Number of mailbox accesses where metacache was refreshed by listing index objects in storage, and metacache was already up-to-date. See metacache_mailbox_refresh_finished.

metacache_user_bundle_upload_finished

Number of user index bundle uploads and the bundle sizes, grouped by bundle type. See metacache_user_bundle_upload_finished.

metacache_mailbox_bundle_upload_finished

Number of mailbox index bundle uploads and the bundle sizes, grouped by bundle type. See metacache_user_bundle_upload_finished.

metacache_user_clean_finished

Number of metacache cleans, grouped by min_priority. If you see these metrics grow much higher than usual, metacache may be too small. See metacache_user_clean_finished.

obox_mailbox_rescan_finished

Number of mailbox accesses resulting in listing mail objects in storage. See obox_mailbox_rescan_finished.

obox_mailbox_rebuild_finished

Number of mailbox accesses resulting in rebuilding the mailbox index, including listing mail objects in storage. See obox_mailbox_rebuild_finished.

Cluster specific events

@metric_defaults = backend contains:

cluster_user_batch_move_finished

Number of user batch moves (to another backend) successfully finished. See cluster_user_batch_move_finished.

cluster_user_move_finished

Number of user moves (to another group/site) successfully finished. See cluster_user_move_finished.

cluster_user_move_failed

Number of user moves failed. See cluster_user_move_finished.

Detailed mail access and delivery metrics

metric imap_commands {
  filter = event=imap_command_finished
  group_by tagged_reply_state {
  }
  group_by cmd_name {
  }
}
metric imap_commands_slow {
  # In some installations there may be too many slow commands to be worth logging these
  exporter = log-export
  filter = event=imap_command_finished AND (NOT cmd_name=IDLE) AND duration > 1min
}
metric lmtp_commands {
  filter = event=smtp_server_command_finished AND protocol=lmtp
  group_by cmd_name {
  }
}
metric push_notifications {
  filter = event=push_notification_finished
}
metric sieve_actions {
  filter = event=sieve_action_finished
  group_by action_name {
  }
}
metric smtp_commands {
  filter = event=smtp_server_command_finished AND protocol=smtp
  group_by cmd_name {
  }
}
metric unknown_commands {
  exporter = log-export
  filter = (event=imap_command_finished OR event=smtp_server_command_finished) AND cmd_name=unknown
}

See also:

• imap_command_finished,
• push_notification_finished,
• sieve_action_finished,
• smtp_server_command_finished,
• smtp_server_command_finished and

Events to catch bugs/problems

INFO

The following events are usually logged as errors/warnings in any case, thus the log-export will likely cause duplicate logging. However, they may be easier to parse and may provide additional details.

metric fs_dictmap_dict_write_uncertain {
  filter = event=fs_dictmap_dict_write_uncertain AND (NOT cleanup=failed)
  exporter = log-export
}
metric fs_dictmap_dict_write_uncertain_failed {
  filter = event=fs_dictmap_dict_write_uncertain AND cleanup=failed
  exporter = log-export
}
metric fs_dictmap_object_lost {
  filter = event=fs_dictmap_object_lost
  exporter = log-export
  # Note: file_type=fts is only in v2.3.15+
  group_by file_type {
  }
}
metric fs_dictmap_max_bucket_changed_iter {
  filter = event=fs_dictmap_max_bucket_changed AND reason=iter
  exporter = log-export
}
metric fts_dovecot_too_many_triplets {
  # v2.3.15+
  filter = event=fts_dovecot_too_many_triplets
  exporter = log-export
}
metric mail_cache_new_field_indexed {
  # Helps to find out if mail clients start fetching a new header
  filter = event=mail_cache_decision_changed AND reason=add
  # If growth is detected, export the events to find out what header is added:
  #exporter = log-export
}
metric metacache_pull_finished {
    exporter = log-export
    filter = event=metacache_pull_finished and error=""
    group_by type {
    }
}
metric metacache_pull_finished_failure {
   exporter = log-export
   filter = event=metacache_pull_finished and not error=""
   group_by type {
   }
}

See also:

• fs_dictmap_dict_write_uncertain,
• fs_dictmap_max_bucket_changed,
• fs_dictmap_object_lost,
• fts_dovecot_too_many_triplets,
• mail_cache_decision_changed and
• metacache_pull_finished.