history-elastic

A plugin for logging to Elasticsearch with predefined fields.

Prerequisites

This plugin uses http-bulk queues. All exported functions uses "elastic" as default queue ID.

Installation

Follow the instructions in our manual to add our package repository and then run the below command.

Ubuntu

apt-get install halon-extras-history-elastic

RHEL

yum install halon-extras-history-elastic

Configuration

Telemetry

If configured, telemetry data will be shared with Halon's data collection endpoint (as seen in the log_telemetry function). This is optional and disabled by default.

How to enable

# smtpd-app.yaml
plugins:
  - id: "telemetry"
    config:
      jwt: "..." # Your JWT provided by Halon
      sourcename: "" # Source name provided by Halon

Without Elasticsearch

Telemetry can also be enabled when not using Elasticsearch by calling the log_telemetry function manually.

import { generate_delivery_attempt, log_telemetry } from "extras://history-elastic";

$doc = generate_delivery_attempt(["arguments" => $arguments, "message" => $message]);
log_telemetry($doc, ["arguments" => $arguments, "message" => $message], ["sampling" => 0.05]); // 5% of all traffic

Exported functions for delivery attempts

Implement the HSL code to the Post-delivery script hook.

log_delivery_attempt($args [, $opts])

Params

• args array - Log data
• opts array - Options array

Returns

• boolean - Whether it was successfully queued to http-bulk

The following options are available in the args array.

• arguments array - Use the predefined context variable $arguments
• message array - Use the predefined context variable $message
• class string - Bounce category (optional)
• custom array - Used for additional logging (optional)

The following options are available in the optional opts array.

• indexname string - Elasticsearch index pattern
• id string - The http-bulk ID
• redact boolean - Redacts the local-part of the email address for both sender and recipient (Default is false)
• telemetry array - Telemetry settings

The following options are available in the optional telemetry array inside opts.

• sampling number The sampling percentage as a decimal number between 0 and 1. This setting does nothing if telemetry has not been manually enabled.

import { log_delivery_attempt } from "extras://history-elastic";

log_delivery_attempt([
    "arguments" => $arguments,
    "message" => $message
]);

Exported functions for transactions

The following code is only examples and needs to be added before calling the built-in message actions (e.g. defer, reject, and queue). The action and reason array keys needs to be changed to reflect what happened with the message.

Implement the HSL code to the RCPT TO, EOD and Post-delivery script hook.

log_rcptto($args [, $opts])

Params

• args array - Log data
• opts array - Options array

Returns

• boolean - Whether it was successfully queued to http-bulk

The following options are available in the args array.

• action string - Message action
• reason string - The reason for the specific action
• custom array - Used for additional logging (optional)
• arguments array - Use the predefined context variable $arguments
• connection array - Use the predefined context variable $connection
• transaction array - Use the predefined context variable $transaction

The following options are available in the optional opts array.

• indexname string - Elasticsearch index pattern
• indexrotate string - Elasticsearch index date rotation
• id string - The http-bulk ID

import { log_rcptto } from "extras://history-elastic";

log_rcptto([
    "action" => "REJECT",
    "reason" => "Message was rejected",
    "arguments" => $arguments,
    "connection" => $connection,
    "transaction" => $transaction
]);

---

log_eod($args [, $opts])

Params

• args array - Log data
• opts array - Options array

Returns

• boolean - Whether it was successfully queued to http-bulk

The following options are available in the args array.

• action string - Message action
• reason string - The reason for the specific action
• recipient array - The recipient (https://docs.halon.io/hsl/eod.html#recipient)
• queueid number - Queue ID
• metadata array - Metadata
• custom array - Used for additional logging
• arguments array - Use the predefined context variable $arguments
• connection array - Use the predefined context variable $connection
• transaction array - Use the predefined context variable $transaction

The following options are available in the optional opts array.

• indexname string - Elasticsearch index pattern
• indexrotate string - Elasticsearch index date rotation
• id string - The http-bulk ID

import { log_eod } from "extras://history-elastic";

log_eod([
    "action" => "QUEUE",
    "reason" => "",
    "recipient" => $recipient,
    "queueid" => 1,
    "arguments" => $arguments,
    "connection" => $connection,
    "transaction" => $transaction
]);

---

log_predelivery($args [, $opts])

Use this function if it is necessary to add custom fields before the delivery attempt.

Params

• args array - Log data
• opts array - Options array

Returns

• boolean - Whether it was successfully queued to http-bulk

The following options are available in the args array.

• message array - Use the predefined context variable $message
• custom array - Used for additional logging

The following options are available in the optional opts array.

• indexname string - Elasticsearch index pattern
• indexrotate string - Elasticsearch index date rotation
• id string - The http-bulk ID

import { log_predelivery } from "extras://history-elastic";

log_predelivery([
    "custom" => [
        "hello" => "world"
    ],
    "message" => $message
]);

---

log_postdelivery($args [, $opts])

Params

• args array - Log data
• opts array - Options array

Returns

• boolean - Whether it was successfully queued to http-bulk

The following options are available in the args array.

• arguments array - Use the predefined context variable $arguments
• message array - Use the predefined context variable $message
• custom array - Used for additional logging

The following options are available in the optional opts array.

• indexname string - Elasticsearch index pattern
• indexrotate string - Elasticsearch index date rotation
• id string - The http-bulk ID

import { log_postdelivery } from "extras://history-elastic";

log_postdelivery([
    "arguments" => $arguments,
    "message" => $message
]);