GreenArrow Documentation

Delivery Attempt Log

Overview

GreenArrow can be configured to log delivery attempts to a logfile. There are a number of configuration options available, including whether to enable this logging and what format to log the data in.

Alternatives

There are two alternative ways to monitor delivery attempts:

  1. Use hvmail_report to request data for a particular time period.

  2. Use the Event Notification System’s delivery_attempt event type.

Configuration

Delivery attempt logging is disabled by default. To enable it, and optionally adjust other settings, edit the /var/hvmail/control/delivery_attempt_logfile.json configuration file.

This file is written in JSON. You can verify that there are no syntax errors in your edits by running:

hvmail_logwriter --check-config-file

The configuration file is automatically re-read every few seconds, so no services need to be restarted to apply changes.

Here are the default settings:

{
  "enabled": false,
  "filename": "",
  "filename_append_date": false,
  "format": "json",
  "include_status": {
    "success":         true,
    "deferral":        true,
    "failure":         true,
    "failure_toolong": true,
    "connmaxout":      false
  },
  "include_first_attempt_regardless_of_status": true,
  "include_local_channel": true
}

Here’s the meaning of each setting:

  • enabled - if true, then delivery attempt logging is enabled.

  • filename - the filename to write to. This is required if enabled is true. The file will be opened for appending by the root user.

  • filename_append_date - if true, then a period and the date in YYYY-MM-DD format will be appended to the filename. For example /tmp/file becomes /tmp/file.2017-03-21. When the first delivery attempt is logged for the next day, it will be written to /tmp/file.2017-03-22.

  • format - the format of logfile data to write. Options are:

  • include_status - a JSON object containing a series of boolean keys that specify which types of delivery attempts should be logged. With the default settings, each message will either have a single success, failure or failure_toolong log entry.

  • include_first_attempt_regardless_of_status - if true then the first delivery attempt for a message (where is_retry is 0) should always have a log entry created regardless of the status. This is useful because the first delivery informs that a new message has been created.

  • include_local_channel - if true then delivery attempts to local domain names (incoming email domains) will have events created. If false, they will be excluded. Most of the deliveries to local domains are bounce messages received through SMTP and internally created bounce messages.

Here’s an example log entry that uses json formatting:

{"timestamp":1490664014.03312,"channel":"remote","status":"success","is_retry":0,"msguid":"1490664013.97131392","recipient":"[email protected]","sender":"[email protected]","mtaid":"","sendid":"","listid":"","injected_time":1490664013,"message":"207.99.125.72 accepted message./Remote host said: 250 ok 1490664014 qp 25510/","outmtaid":38,"sendsliceid":"","throttleid":null,"clicktrackingid":""}

The definition of each of the keys in the above example can be found in the Delivery Event Processed Logfile Format documentation.

Log Rotation

GreenArrow does not rotate delivery attempt logs. If you enable delivery attempt logging, then you must set up your own log file rotation system in order to avoid running out of disk space.

The logfile is re-opened for appending every few seconds, so no services need to be restarted for the logfile to be re-created after being moved or deleted.

 hvmail_report Command
Delivery Event Processed Logfile Format