mirror of
https://github.com/mailscope/kumomta.git
synced 2026-08-24 13:18:18 +00:00
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.
35 lines
2.4 KiB
Markdown
35 lines
2.4 KiB
Markdown
---
|
|
tags:
|
|
- meta
|
|
---
|
|
|
|
# Predefined Metadata
|
|
|
|
KumoMTA provides the ability to set and retrieve metadata at both the connection and message level.
|
|
|
|
By leveraging metadata, information can be made available to policy running at different phases in the life of a message, where the [connection metadata](./connectionmeta.md) is used for data that is shared in common with all messages injected over a given connection, and the [message metadata](./message/set_meta.md) is for all data related to a given individual message.
|
|
|
|
There are get and set functions available for both connection and message metadata, and when a message is received **all connection metadata is also copied into the message metadata**, meaning that for retrieving connection metadata the user can opt to only access message metadata for any value that doesn't change over the life of the connection.
|
|
|
|
The following metadata values are predefined by KumoMTA and are available to retrieve:
|
|
|
|
<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](kumo/start_esmtp_listener/hostname.md)|{{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||
|
|
|Connection|`ehlo_domain`|the domain name that was passed in from the sender via the SMTP EHLO or HELO|{{since('2024.11.08-d383b033', inline=True)}}|
|
|
|Message|`queue`|specify the name of the queue to which the message will be queued. Must be a string value.||
|
|
|Message|`tenant`|specify the name/identifier of the tenant, if any. Must be a string value.||
|
|
|Message|`campaign`|specify the name/identifier of the campaign. Must be a string value.||
|
|
|Message|`routing_domain`|Overrides the domain of the recipient domain for routing purposes.|{{since('2023.08.22-4d895015', inline=True)}}|
|