headers

Specify a list of message headers to include in the logs. The default is empty.

Warning

While logging headers directly is convenient and easy to express in the logging configuration, it comes with additional runtime CPU and IO overhead: every discrete event that is logged will result in the message contents being loaded from spool (if they are not already loaded), the message headers being parsed, and the selected headers decoded to be logged.

If your system has CPU and IO to spare, this is a non-issue, but if you are pushing your system to its limits, and especially if you have a large scheduled queue with lots of throttled or otherwise delayed messages, these overheads can dominate the system and harm overall throughput.

We recommend instead using msg:import_x_headers() during message reception to cache a copy of the headers that you desire to log into your message metadata, then listing those metadata fields in your logger meta list instead of using headers. This will dramatically reduce the IO and CPU overheads around logging.

kumo.configure_local_logs {
  -- You can log headers like this, but it is not recommended!
  -- You generally should prefer to log `meta` instead.
  headers = { 'Subject' },
}

Please consider using meta rather than headers!

Since: Version 2023.12.28-63cde9c7

The functionality described in this outlined box requires version 2023.12.28-63cde9c7 of KumoMTA, or a more recent version.

---

Header names can now use simple wildcard suffixes; if the last character of the header name is * then it will match any string with that prefix. For example "X-*" will match any header names that start with "X-".