formatters.md

Formatters

Adding context to alerts is done by the formatters. Formatters generate all the content that may be used by one or more message types. For example, text returned by a Nagios check can be highlighted to grab the operator's attention. Helper functions can be called to generate additional content such as image attachments or search results.

All content generated by a formatter is stored in a hash (a class instance variable in the formatter object). The hash looks similar to the following:

@content = {
  :attachments => [],
  :html => {
    :additonal_info => "",
    :additional_details => "" 
  },
  :subject => "",
  :text => {
    :additonal_info => "",
    :additional_details => ""
  }
}

NOTE: The subkeys under the :html and :text keys are generated by formatter methods of the same name.

Formatter Methods

The base formatter (Formatter::Base) defines a set of core formatting methods useful for generating content. These methods can be overridden in subclassed formatters to do anything. The only limit is your imagination.

ack_info
additional_details
additional_info
alert_ack_url
host_info
notes
notification_info
recipients_email_link
short_ack_info
short_state_detail
state_info

Formatter::Base also includes basic methods that are used to store or manipulate content in the @content hash:

add_attachments - Add an attachment path to be referenced in an Email message.
add_html - Concatenate HTML for the given section.
add_text - Concatenate text for the given section.
line_break - Generate a line break for both text and HTML content.

See below for an example of content generated using some of the above methods.

Writing the Formatter

To write a formatter, create a new formatter class (i.e. check_disk.rb) and inherit from NagiosHerald::Formatter.

module NagiosHerald
  module Formatter
    class CheckDisk < NagiosHerald::Formatter
      include NagiosHerald::Logging

      def additional_details
      section = __method__  # this defines the section key in the formatter's content hash
      add_text(section, "nagios-herald makes alerting more bearable.")
      add_html(section, "<b>nagios-herald</b> makes alerting more bearable.<br>")
      end

    end
  end
end

Naming Convention

• Built-in formatters live in lib/nagios-herald/formatters/.
• Custom formatters (those you'll write) can live in any location.
• Specify the location of your custom formatters via the --formatter-dir option on the command line or the formatter_dir variable in the configuration file.
• The file names MUST lower-cased and underscored.
• The class names MUST be CamelCased.

For example, our CheckDisk formatter class would reside in a file named check_disk.rb.

This is necessary as nagios-herald preloads all known formatters when it starts so that it can dynamically instantiate the appropriate formatter it needs when it's ready.

Overriding Methods

Any of the core formatting methods can be overridden in your subclass. It's recommended that the helper methods (i.e. add_(attachment|html|text) not be overridden.

An example of an overridden additional_info method could be:

def additional_info
  section = __method__  # this defines the section key in the formatter's content hash
  hostname  = get_nagios_var("NAGIOS_HOSTNAME")
  add_text(section, "#{hostname} blew up!")
  add_html(section, "#{hostname} <b>blew</b> up!")
end

Helpers

Helpers are libraries available to all formatters that can be used to supplement the content they generate. For example, a helper can pull in external information (such as a graph) that is relevant to a service that Nagios is alerting on.

To learn more, see the helpers page.

Testing Your Formatter

PLEASE TEST YOUR FORMATTER. NOT DOING SO INCREASES THE POSSIBILITY THAT A NEW FORMATTER WILL PREVENT DELIVERY OF CRITICAL ALERTS.

There are two ways that formatters can be tested: unit tests and manually running nagios-herald.

Unit Tests

THIS IS A WORK IN PROGRESS. BETTER TESTING IS ON THE ROADMAP

nagios-herald

nagios-herald can be called manually from the command line to test new formatters:

./bin/nagios-herald --env-file ../test/env_files/check_mem.vars --formatter=check_mem -r ops@example.com -y nagios@example.com --message-type email -u http://nagios.example.com --trace

For a full listing of available options, run nagios-herald --help.

A Note About Nagios Data

Nagios stores important information in environment variables. The formatter methods can retrieve that information by using the get_nagios_var() method. For reference, see an example environment file.

NOTE: Do not directly call ENV['YOUR_VAR'] in your Ruby code as it will be harder to test.

Testing the Formatter with Offline Data

Because Nagios stores information in environment variables that are generated during runtime, nagios-herald provides a few example environment files that can be used for testing. Files in test/env_files/ can be specified via the --env-file argument to mimic an alerting event. During normal operation nagios-herald grabs the information it needs from Nagios' environment variables.

One can generate environment files for testing by using the dump_nagios_env.sh tool.

NOTE: --no-send forces nagios-herald to output content to the terminal.

./bin/nagios-herald --no-send --env-file ../test/env_files/check_disk.vars --formatter=check_disk -r ops@example.com -y nagios@example.com --message-type email -u http://nagios.example.com --trace
------------------
Subject : ** PROBLEM Service ALERT: web.example.com/Disk Space is CRITICAL **
------------------
Host: web.example.com
Service: Disk Space

State is now: CRITICAL for 0d 0h 5m 12s (was CRITICAL) after 3 / 3 checks

Additional info:
 DISK CRITICAL - free space: / 7002 MB (82% inode 60%): /data 16273093 MB (99% inode 99%):

Additional Details:
Filesystem            Size  Used Avail Use% Mounted on
/dev/sda               40G   33G  7.2G  82% /
tmpfs                 2.5G   83M  2.4G   4% /dev/shm
/dev/sdb               16G   16G  158M  99% /data

Sent to ops-engineer
Notification sent at: Thu May 16 21:06:38 UTC 2013 (notification number 1)

Acknowledge this alert: http://nagios.example.com/nagios/cgi-bin/cmd.cgi?cmd_typ=34&host=web.example.com&service=Disk%20Space%0A%3Cbr%3E

------------------