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

Example metrics accessing authentication, mail access and delivery metrics:

metric auth_failures {
  exporter = log-export
  filter = event=auth_request_finished AND NOT success=yes
}
metric auth_successes {
  filter = event=auth_request_finished AND success=yes
}
metric auths {
  filter = event=auth_request_finished
}

metric login_aborted {
  filter = event=login_aborted
  group_by = reason
}

metric mail_user_session_finished {
   filter = event=mail_user_session_finished
   fields = rss utime
}

These metrics must be configured exactly as below for cluster to work correctly:

metric lmtp_rcpt_finished_failure {
  filter = event=smtp_server_transaction_rcpt_finished AND category=lmtp AND NOT error="" AND NOT enhanced_code=5.*
  group_by = dest_host
}
metric lmtp_rcpt_finished_success {
  filter = event=smtp_server_transaction_rcpt_finished AND category=lmtp AND error=""
  group_by = dest_host
}
metric proxy_session_failure {
  filter = event=proxy_session_finished AND error_code=* AND NOT error_code=proxy_dest_auth_temp_failed AND NOT error_code=proxy_dest_redirected
  group_by = dest_host
}
metric proxy_session_success {
  filter = event=proxy_session_established
  group_by = dest_host
}

See:

• auth_request_finished,
• login_aborted and
• mail_user_session_finished.

Dovecot Backend

Generic authentication metrics

metric auths {
  filter = event=auth_request_finished
}

See also:

• auth_request_finished.

Mail access and delivery metrics

metric imap_commands {
  filter = event=imap_command_finished AND (tagged_reply_state=OK OR tagged_reply_state=NO)
  group_by = cmd_name
}
metric imap_commands_bad {
  exporter = log-export
  filter = event=imap_command_finished AND tagged_reply_state=BAD
  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 mail_deliveries {
  filter = event=mail_delivery_finished
}
metric mail_sends {
  filter = event=smtp_submit_finished
}
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,
• mail_delivery_finished,
• push_notification_finished,
• sieve_action_finished,
• smtp_server_command_finished,
• smtp_server_command_finished and
• smtp_submit_finished.

Email IO metrics

metric mail_read {
  filter = event=http_request_finished AND category=storage AND method=get AND file_type=mail
  fields = net_in_bytes
}
metric mail_write {
  filter = event=http_request_finished AND category=storage AND method=put AND file_type=mail
  fields = net_out_bytes
}
metric mail_delete {
  filter = event=http_request_finished AND category=storage AND method=delete AND file_type=mail
}

See also:

• http_request_finished.

FTS index IO/CPU metrics

metric fts_read {
  filter = event=http_request_finished AND category=storage AND method=get AND file_type=fts
  fields = net_in_bytes
}
metric fts_write {
  filter = event=http_request_finished AND category=storage AND method=put AND file_type=fts
  fields = net_out_bytes
}
metric fts_delete {
  filter = event=http_request_finished AND category=storage AND method=delete AND file_type=fts
}
metric indexer_worker_indexing_finished {
  # v2.3.15+
  filter = event=indexer_worker_indexing_finished
  fields = user_cpu_usecs
}

See also:

• http_request_finished and
• indexer_worker_indexing_finished.

Index IO metrics

metric metacache_user_refresh_finished_refreshed_changed {
  filter = event=metacache_user_refresh_finished AND metacache_status=refreshed_changed
}
metric metacache_user_refresh_finished_refreshed_unchanged {
  filter = event=metacache_user_refresh_finished AND metacache_status=refreshed_unchanged
}
metric metacache_mailbox_refresh_finished_refreshed_changed {
  filter = event=metacache_mailbox_refresh_finished AND metacache_status=refreshed_changed
}
metric metacache_mailbox_refresh_finished_refreshed_unchanged {
  filter = event=metacache_mailbox_refresh_finished AND metacache_status=refreshed_unchanged
}

metric metacache_user_bundle_upload_finished {
  filter = event=metacache_user_bundle_upload_finished
  fields = bundle_size
  group_by = bundle_type
}
metric metacache_mailbox_bundle_upload_finished {
  filter = event=metacache_mailbox_bundle_upload_finished
  fields = bundle_size
  group_by = bundle_type
}

# If you see these metrics grow much higher than usual, metacache may be too small
metric metacache_user_clean_finished {
  filter = event=metacache_user_clean_finished AND error=""
  group_by = min_priority
}

metric obox_mailbox_rescan_finished {
  filter = event=obox_mailbox_rescan_finished
}
metric obox_mailbox_rebuild_finished {
  filter = event=obox_mailbox_rebuild_finished
}

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.

Cluster specific events

User group moving metrics

metric cluster_group_move_finished {
   filter = event=cluster_user_group_move_finished AND error=""
   group_by = group_name
}
metric cluster_group_move_failed {
   filter = event=cluster_user_group_move_finished AND NOT error=""
   group_by = group_name
}

See also:

• cluster_user_group_move_finished.

User moving metrics

metric cluster_user_move_finished {
   filter = event=cluster_user_move_finished AND error=""
   group_by = dest_host
}
metric cluster_user_move_failed {
   filter = event=cluster_user_move_finished AND NOT error=""
   group_by = dest_host
}

See also:

• cluster_user_move_finished.