Several doc updates and clean up.

docs/config.md

@@ -1,15 +1,20 @@
 # Configuration
 
 ``nagios-herald`` supports a YAML-based configuration file.  The configuration file is named
-``config.yml`` and lives in the ``etc/`` directory of this project. This project provides an [example](/etc/config.yml.example) configuration file that you can use to get started.
+``config.yml`` and lives in the ``etc/`` directory of this project. This project provides
+an [example](/etc/config.yml.example) configuration file that you can use to get started.
 
 ## Command Line Options
 
-``nagios-herald`` provides several command line options, some of which can override values in the configuration file.  During runtime, ``nagios-herald`` merges the configuration and command line options into a single hash available through the code.  Command line options always override configuration file values, when this is a conflict.
+``nagios-herald`` provides several command line options, some of which can override values
+in the configuration file.  During runtime, ``nagios-herald`` merges the configuration
+and command line options into a single hash available through the code.
+Command line options **always override configuration file values, when there is a conflict**.
 
 ## Accessing Configuration Values
 
-All configuration file values and command line options are available in a single, globally available hash named ``Config.config``.  See below for an example configuration file.
+All configuration file values and command line options are available in a single, globally
+available hash named ``Config.config``.  See below for an example configuration file.
 
 ```
 # define the FQDN of servers we call on to provide context in notifications
@@ -20,6 +25,8 @@ splunk:
   url: https://splunk.example.com:8089/services/search/jobs
   username: splunkuser
   password: splunkpass
+logfile: /tmp/nagios-herald.log
+formatter_dir: /usr/local/nagios-herald-formatters
 ```
 
 To access the value for the Ganglia server URI, one would write code similar to the below:

docs/formatters.md

@@ -114,21 +114,21 @@ To learn more, see the [helpers](/docs/helpers.md) page.
 
 **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 ``notify-by-handler``.
+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**
 
-### ``notify-by-handler``
+### ``nagios-herald``
 
-``notify-by-handler`` can be called manually from the command line to test new formatters:
+``nagios-herald`` can be called manually from the command line to test new formatters:
 
 ```
-./bin/notify-by-handler --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
+./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 ``notify-by-handler --help``.
+For a full listing of available options, run ``nagios-herald --help``.
 
 ### A Note About Nagios Data
 
@@ -150,7 +150,7 @@ One can generate environment files for testing by using the [dump_nagios_env.sh]
 **NOTE**: ``--no-send`` forces ``nagios-herald`` to output content to the terminal.
 
 ```
-./bin/notify-by-handler --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
+./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 **
 ------------------

docs/nagios-config.md

@@ -3,7 +3,7 @@
 ## Notification Command Configuration
 
 Nagios needs to be instructed to use ``nagios-herald`` for notifications. The main notification program in
-``nagios-herald`` is called ``notify-by-handler``.
+``nagios-herald`` is called ``nagios-herald``.
 
 To configure Nagios to generate alerts via ``nagios-herald``, update the relevant stanza(s) in ``commands.cfg``.
 The below example assumes ``nagios-herald`` is installed in ``/usr/local/bin``.
@@ -12,40 +12,48 @@ The below example assumes ``nagios-herald`` is installed in ``/usr/local/bin``.
 # email
 define command {
     command_name    notify-host-by-email
-    command_line    /usr/local/nagios-herald/bin/notify-by-handler --message-type email --formatter=$_HOSTMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
+    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-type email --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-email
-    command_line    /usr/local/nagios-herald/bin/notify-by-handler --message-type email --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
+    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-type email --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
 }
 
 # pager
 define command {
     command_name    notify-host-by-pager
-    command_line    /usr/local/nagios-herald/bin/notify-by-handler --message-type pager --formatter=$_HOSTMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
+    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-type pager --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-pager
-    command_line    /usr/local/nagios-herald/bin/notify-by-handler --message-type pager --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
+    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-type pager --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
 }
 
 # IRC (optional)
 define command {
     command_name    notify-service-by-irc
-    command_line    /usr/local/nagios-herald/bin/notify-by-handler --message-type irc --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
+    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-type irc --formatter=$_SERVICEMESSAGE_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-irc
-    command_line    /usr/local/nagios-herald/bin/notify-by-handler --message-type irc --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
+    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-type irc --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com
 }
 ```
 
 **NOTE**: ``$_HOSTMESSAGE_FORMATTER_NAME$`` and ``$_SERVICEMESSAGE_FORMATTER_NAME$`` are Nagios macros, generated
 from a custom variable in a relevant service check definition.
 
+### Tracing Errors
+If ``nagios-herald`` is failing to notify, you can turn up the logging via the ``--trace`` option to gather
+more information, like so:
+
+```
+    command_line    /usr/local/nagios-herald/bin/nagios-herald --message-type email --formatter=$_SERVICEMESSAGE_FORMATTER_NAME$ --nagios-cgi-url=http://nagios.example.com/nagios/cgi-bin/cmd.cgi --reply-to=nagios@example.com --trace
+```
+
 ## Service Configuration
 
 To apply a formatter to a service check, add the ``_message_formatter_name`` custom variable in the relevant stanza in ``services.cfg``:

docs/tools.md

@@ -1,7 +1,7 @@
 # Tools
 
 This project comes with a few tools you can use that mimic the behavior of helpers and formatters.  These are
-really useful for testing functionality outside of ``notify-by-handler``.
+really useful for testing functionality outside of ``nagios-herald``.
 
 The following tools reside under the ``bin/`` directory.