messages.md

Messages

While formatters are crucial to contextualizing alerts, it doesn't matter much if the alerts are never sent. This is where messages come in to play.

nagios-herald provides a base Message class (Message::Base) from which all Message subclasses inherit. Message::Base knows that all messages have content and recipients; it's the job of the Message subclasses to define additional behavior (such as how to send a message).

Three message types are defined in nagios-herald: Email, Pager, and IRC. The IRC class must be subclassed by a custom message class so that the send function can be implemented. Feel free to cook up any new message types (i.e. CarrierPigeon, SmokeSignal) as you see fit.

Getting Content into Messages

Content generated by formatters is assigned to a message in Executor via the following code:

formatter.generate_message_content
message.content = formatter.content

Writing and Using Custom Message Classes

You may write your own message classes and use them with nagios-herald. These message classes can live in any location. A custom message class should subclass Message::Base.

Custom Message Class Command Configuration

To use a custom message class, you must add a stanza to commands.cfg that defineds a command that uses that message class. Commands for custom messages must provide a message-type that matches your message class name as well as a message-dir that specifies the directory in which your custom message class is stored.

# notify by carrier pigeon
define command {
    command_name    notify-host-by-pigeon
    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-dir=/usr/local/nagios-herald-messages/ --message-type=pigeon --formatter=$_HOSTMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
}

define command {
    command_name    notify-service-by-pigeon
    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-dir=/usr/local/nagios-herald-messages/ --message-type=pigeon --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
}

Using Custom Message Class Commands

To use your custom message class, you can specify the command_name that uses your message class as a host or service notification command for a contact. As you can specify multiple notification commands for a single contact, you may specify a custom message command along with the command for a provided message to send multiple kinds of messages:

define contact {
        ...
        service_notification_commands   notify-service-by-email,notify-service-by-carrier-pigeon
}

The formatter specified using message_formatter_name in the host or service will be used for all message types.

If your custom message type is different enough from the other message types that use a certain formatter, it may be necessary to use a new key in the content hash to add content specific to that message type. Content should be added to the content hash in the formatter; the send function of the custom message class should then use that content to construct and send the message.

As an example example, the CarrierPigeon message class may send text contained in content[:handwritten]. A formatter that is used with the CarrierPigeon class should implement a method that adds content to handwritten sections just as the add_html() method adds content to html sections. The formatter should add content that should be delivered by carrier pigeon to the handwritten hash and still add content to be delivered in an HTML email to the html hash using the add_html() method.

Finally, it should be noted that you can add custom object variables for individual contacts that can later be accessed by a custom message class using the get_nagios_var() library function:

define contact {
        ...
        service_notification_commands   notify-service-by-irc-channel
        _irc_channel                    performance
}

Naming Convention

• File names MUST be lower-cased and underscored.
• Class names MUST be CamelCased.
• A message-type specified on the command line (or in a command definition) should match a snake_cased message class name with the exception that a class name that is all upper case should be written as one word. ** The message-type for a class named CarrierPigeon is carrier_pigeon ** The message-type for a class named IRC is irc ** The message-type for a class named InternalIrc is internal_irc ** The message-type for a class named InternalIRC is internal_i_r_c