Events

List of all events emitted by Dovecot.

These events can be used in Statistics and Event Export.

See Events Design for technical implementation details.

Categories

Category Description
auth  
mailbox  
storage  

Event Listing

Global Fields

ALL events have the following fields:

Field Description
duration Duration of the event (in microseconds)

Event Categories

Authentication Server

These events are generated in authentication process(es) and can be used to track and log individual authentication actions.

auth_request_finished

New in version v2.3.7.

Emitted at end of authentication request. Most useful for tracking status of authentication/login attempts.

Field Description
user Full username
original_username Original username used
translated_username Username after auth_username_translation translations are applied
login_user When doing login using master_user, the user we are logging in as
master_user Master username
error Set when error happens
success yes, when authentication succeeded
transport
Values:
  • insecure
  • trusted
  • TLS
mechanism Name of used mechanism
credentials_scheme Type of credential. Examples: SHA256-CRYPT, PLAIN, …
policy_penalty Time of penalty added by policy server
policy_result
Values:
  • ok
  • delayed
  • refused
auth_passdb_request_started

New in version v2.3.7.

Emitted before processing begins for a passdb block.

Most useful for debugging authentication flow.

Field Description
passdb Driver name
passdb_name passdb { name }, if it is configured. Otherwise, the driver name.
passdb_id

New in version v2.3.9.

ID number of the passdb username

auth_passdb_request_finished

New in version v2.3.7.

Emitted after processing ends for a passdb block.

Most useful for debugging authentication flow.

Field Description
passdb Driver name
passdb_name passdb { name }, if it is configured. Otherwise, the driver name.
user Full username
master_user Master username
username Username without domain
domain Domain (if present)
result
Values:
  • ok
  • password_mismatch
  • user_unknown
  • pass_expired
  • user_disabled
  • scheme_not_available
  • internal_failure
  • next
passdb_id

New in version v2.3.9.

ID number of the passdb username

auth_userdb_request_started

New in version v2.3.7.

Emitted before processing begins for a userdb block.

Most useful for debugging authentication flow.

Field Description
userdb Driver name
userdb_name userdb { name }, if it is configured. Otherwise, the driver name.
userdb_id

New in version v2.3.9.

ID number of the userdb username

auth_userdb_request_finished

New in version v2.3.7.

Emitted after processing ends for a userdb block.

Most useful for debugging authentication flow.

Field Description
userdb Driver name
userdb_name userdb { name }, if it is configured. Otherwise, the driver name.
user Full username
master_user Master username
username Username without domain
domain Domain (if present)
result
Values:
  • ok
  • user_unknown
  • internal_failure
userdb_id

New in version v2.3.9.

ID number of the userdb username

auth_policy_request_finished

New in version v2.3.7.

Emitted after processing ends for an auth policy request.

Most useful for debugging authentication flow.

Field Description
mode
Values:
  • allow
  • report
policy_response Value returned from policy server (number) Otherwise, the driver name.

Authentication Client

These events are generated by authentication clients (lib-auth).

auth_client_request_started

New in version v2.3.7.

Field Description
id Event ID
auth_client_request_continue

New in version v2.3.7.

Field Description
id Event ID
auth_client_request_finished

New in version v2.3.7.

Field Description
id Event ID
error Error reason
auth_client_request_challenged

New in version v2.3.7.

Field Description
id Event ID
auth_client_userdb_lookup_started

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
auth_client_userdb_lookup_finished

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
error Error, if it occurred
auth_client_passdb_lookup_started

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
auth_client_passdb_lookup_finished

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
error Error, if it occurred
auth_client_userdb_list_started

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
auth_client_userdb_list_finished

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
error Error, if it occurred
auth_client_cache_flush_started

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
auth_client_cache_flush_finished

New in version v2.3.7.

Field Description
service Name of service. Examples: smtp, imap, lmtp, …
local_ip Local IP address
local_port Local port
remote_ip Remote IP address
remote_port Remote port
user Full username
error Error, if it occurred

Connection

These events apply only for connections using the connection API.

Note

Not all connections currently use this API, so these events work for some types of connections, but not for others.

client_connection_connected

Emitted when a client connection is established.

Field Description
client_ip Source IP address
client_port Source port
ip Target IP address
port Target port
client_connection_disconnected

Emitted when a client connection is terminated.

Field Description
client_ip Source IP address
client_port Source port
ip Target IP address
port Target port
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes
reason Disconnection reason
server_connection_connected

Emitted when a server connection is established.

Field Description
client_ip Source IP address
client_port Source port
ip Target IP address
port Target port
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes
server_connection_disconnected

Emitted when a server connection is terminated.

Field Description
client_ip Source IP address
client_port Source port
ip Target IP address
port Target port
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes
reason Disconnection reason

HTTP

These events are emitted by Dovecot’s internal HTTP library.

http_request_finished

Emitted when an HTTP request is complete.

This event is useful to track and monitor external services.

Field Description
status_code HTTP result status code (integer)
attempts Amount of individual HTTP request attempts (number (of retries after failures + 1)
redirects Number of redirects done while processing request
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes
http_request_redirected

Intermediate event emitted when an HTTP request is being redirected.

The http_request_finished event is still sent at the end of the request.

Field Description
status_code HTTP result status code (integer)
attempts Amount of individual HTTP request attempts (number (of retries after failures + 1)
redirects Number of redirects done while processing request
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes
http_request_retried

Intermediate event emitted when an HTTP request is being retried.

The http_request_finished event is still sent at the end of the request.

Field Description
status_code HTTP result status code (integer)
attempts Amount of individual HTTP request attempts (number (of retries after failures + 1)
redirects Number of redirects done while processing request
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes

IMAP

imap_command_finished

Event emitted when an IMAP command is completed.

This event is useful to track individual command usage, debug specific sessions, and/or detect broken clients.

Note

This event is currently not sent for pre-login IMAP commands.

Field Description
tag IMAP command tag
name IMAP command name (e.g. FETCH)
args IMAP command’s full parameters
human_args IMAP command’s full parameters, as human-readable output
tagged_reply_state
Values:
  • OK
  • NO
  • BAD
tagged_reply Full tagged reply (e.g. OK SELECT finished.)
last_run_time Timestamp when the command was running last time. (Command may be followed by internal “mailbox sync” that can take some time to complete)
running_usecs How many usecs this command has spent running
lock_wait_usecs How many usecs this command has spent waiting for locks
bytes_in Amount of data read, in bytes
bytes_out Amount of data written, in bytes

Mail Delivery

Events emitted on mail delivery.

mail_delivery_started

New in version 2.3.8.

Event emitted when message delivery is started.

This event is useful for debugging mail delivery flow.

Field Description
message_id Message-ID header value (truncated to 200 bytes)
message_subject Subject header value, in UTF-8 (truncated to 80 bytes)
message_from Email address in the From header (e.g. user@example.com)
message_size Size of the message, in bytes
message_vsize Size of the message with CRLF linefeeds, in bytes
rcpt_to The envelope recipient for the message
rcpt_param_notify The value of the NOTIFY parameter from the LMTP RCPT command
rcpt_param_orcpt The value of the ORCPT parameter from the LMTP RCPT command
rcpt_param_orcpt_type The address type, typically rfc822, of the ORCPT parameter for the LMTP RCPT command
mail_delivery_finished

New in version 2.3.8.

Event emitted when message delivery is completed.

This event is useful for logging and tracking mail deliveries.

Field Description
message_id Message-ID header value (truncated to 200 bytes)
message_subject Subject header value, in UTF-8 (truncated to 80 bytes)
message_from Email address in the From header (e.g. user@example.com)
message_size Size of the message, in bytes
message_vsize Size of the message with CRLF linefeeds, in bytes
rcpt_to The envelope recipient for the message
rcpt_param_notify The value of the NOTIFY parameter from the LMTP RCPT command
rcpt_param_orcpt The value of the ORCPT parameter from the LMTP RCPT command
rcpt_param_orcpt_type The address type, typically rfc822, of the ORCPT parameter for the LMTP RCPT command

DNS

Events emitted from Dovecot’s internal DNS client.

dns_worker_request_started
Field Description
No event specific fields defined
dns_request_started
Field Description
No event specific fields defined
dns_worker_request_finished
Field Description
error Human readable error
error_code Error code usable with net_gethosterror()
dns_request_finished
Field Description
error Human readable error
error_code Error code usable with net_gethosterror()

SQL

Events emitted by Dovecot’s internal SQL library.

Note

This includes queries sent to Cassandra.

sql_query_finished
Field Description
error Human readable error
error_code Error code (if available)
query_first_word First word of the query (e.g. SELECT)
sql_transaction_finished
Field Description
error Human readable error
error_code Error code (if available)
sql_connection_finished
Field Description
No event specific fields defined