Wez Furlong
b8310da8be
TL;DR: you can easily halve your system performance by logging headers vs. logging meta. This is one of those things that is easy to overlook or forget, but: whenever you need to operate on the message data, rather than its metadata, the aggregate cost is high. In this case, we were recently troubleshooting a system where the CPU was bogged down and we traced it to the logging configuration: a number of message headers were being logged in a configuration that made heavy use of throttles and limits in its traffic shaping, and thus had a large number of Delayed and TransientFailure events being written to the logs. When logging headers, each one of those events requires loading the message from the spool and parsing out the headers. When the average message size is ~100KB this imposes a notable overhead on the CPU and IO utilization of the system. What we recommend instead of logging headers directly is capturing the information that you want to log into the message metadata at the time that the message is received. The message meta is usually already loaded, but is also typically much smaller and easier to decode than the full message content in the cases where it is not loaded. As a result, it is much cheaper to log meta than to log headers. This commit adds some warnings and cross links to help folks be aware of this, and to generally navigate related meta and logging topics more easily via tags.
2.5 KiB
tags
| tags | |
|---|---|
|
Connection Metadata Object
{{since('2023.08.22-4d895015')}}
This object represents a collection of metadata keys and values that are associated with an established incoming SMTP connection.
KumoMTA populates a small number of predefined fields (see below), and allows your policy scripts the ability to read those values as well as write (and read!) additional values as needed by the local policy. For instance, you may decide to compute a value after EHLO has been processed by smtp_server_ehlo and access that value in a later SMTP event handler.
Prior to calling smtp_server_message_received, KumoMTA will copy the values from the connection metadata and use those to populate the message metadata.
The get_meta and set_meta methods shown below are used to read and write
metadata values.
Predefined Connection Metadata Values
The following values are predefined by KumoMTA:
<style> table tbody tr td:nth-of-type(2) { white-space: nowrap; } </style>| Scope | Name | Purpose | Since |
|---|---|---|---|
| Connection | reception_protocol |
indicates the reception protocol, such as ESMTP |
{{since('2023.08.22-4d895015', inline=True)}} |
| Connection | received_via |
indicates the IP:port of the KumoMTA listener that is handling this session | {{since('2023.08.22-4d895015', inline=True)}} |
| Connection | received_from |
indicates the IP:port of the sending or peer machine in this session | {{since('2023.08.22-4d895015', inline=True)}} |
| Connection | hostname |
A copy of the effective value of the hostname set by kumo.start_esmtp_listener | {{since('2023.11.28-b5252a41', inline=True)}} |
| Connection | authn_id |
the authentication id if the message was received via authenticated SMTP | |
| Connection | authz_id |
the authorization id if the message was received via authenticated SMTP |
!!! Note Additional metadata is available at the Message scope, for a full list of all available metadata, see the Predefined Metadata page.
Available Methods
conn_meta:get_meta(name)
Returns the value associated with name, or nil if no such value has been defined.
Values may be predefined by KumoMTA or may be set by policy scripts using conn_meta:set_meta().
conn_meta:set_meta(name, value)
Sets the value associated with name to value. Value must be serializable as JSON; it can be simple strings or numbers, but may also be an array or object value.