Webmetrics API plug-in for Nagios

Nagios is a great program that allows you to check uptime and performance metrics from multiple services in your network.  Webmetrics has been asked by many customers to create a plug-in for Nagios to display the Webmetrics service data.  This allows you to have a single location to monitor both the internal and external performance of your network and applications. The Professional Services team at Webmetrics has done just that and this article will give you the basic info on how to setup the plug-in for both the free and paid versions of Nagios.  I hope you find this example and prototype useful.

The Webmetrics API plug-in for Nagios is a Perl script that will access the realtime.getdata API from Webmetrics.  The script requires 3 parameters be passed to it; the API Key, Username, and Service ID.  The API Key can be found by logging into your Webmetrics account and then clicking on “My Account” in the top right hand corner.  You will then see an API tab.  This API Key should be kept secret as it will allow full access to your account.  The Service ID is able to be found by clicking on any service in your account.  The URL in the address bar will show account=XXXXXX.  These numbers are your Service ID.

Here are some examples of the integration with  Nagios XI:

Service in OK status:

To see a service in Warning or Error status please click on the following links:
Warning
Error

Service Performance Metrics:

Webmetrics Graph:

Below are some examples of the integration with Nagios:

There are 5 possible outputs from this script.

1. OK status showing the load time as well as the time the sample was taken.   Exit code = 0.
2. Warning status showing the time the sample was taken.  Exit code = 1.
3. Error status showing the time the sample was taken.  Exit code = 2.
4. Unknown sample status is shown for any unexpected results.  Exit code = 3.
5. Error message returned from the Webmetrics API.  Exit code = 3.

You will need to download the Nagios Perl script located at: http://download.webmetrics.com/nagios/nagios.pl.  The following Perl modules are also needed to ensure the script works properly:

LWP::Simple
LWP::UserAgent
HTTP::Request
HTTP::Response
XML::Simple
Getopt::Long
Digest::SHA1 qw(sha1_base64)
DateTime
DateTime::Format::Strptime

Once this is done, ensure you can run the Perl script without any errors:

/usr/bin/perl /usr/local/Nagios/libexec/nagios.pl –api_key=1234567890abcdefg –username=sample –serviceID=123456.  After running the command, you should see output like the following:

“SiteMonitor Load Time = 1.24, Sample Taken At: 15:37:46.01 US/Pacific | load_time=1.24”

If you see this type of output, the script is ready to be inputted as a plug-in into Nagios.

Setup Nagios XI:

First, log into the web interface.  Click Configure -> Enter Nagios Core Configuration Manager -> Enter Credentials -> Click the arrow for Commands -> Click Commands -> Click Add New.  You can give your command any name, but for the purposes of this article, we will call it Webmetrics-API.  For the Command Line option, you will want to give the full path to Perl and the full path to the Perl Script.  In this example, I used: /usr/bin/perl /usr/local/nagios/libexec/nagios.pl -api_key $ARG1$ -username $ARG2$ -serviceID $ARG3$.  Click Save.  Then click Apply Configuration.  Then under Monitoring, click Hosts -> Add New.  Provide a Host Name, an Address (127.0.0.1), and a Description.  Click on the Check Settings tab and fill out all fields with a *.  Click Save.  Under Monitoring, click Services -> Add New.  Type in the Webmetrics Service Name as the Config Name.  Select the Host Name that you just created in the previous step and provide a Service Description.  Under Check command, choose Webmetrics-API.  Under $ARG1$ enter the API Key.  Under $ARG2$ enter the Webmetrics Username.  Under $ARG3$ enter the Service ID.  Click on the Check Settings tab and fill out all items with a *.  Click Save.  Repeat this step for all services that you want to monitor.  Click Apply Configuration.

Now that the host and services are setup, click on the Views tab and then Service Detail.  Note: It may take a couple of minutes for the services to show up.

Setup Nagios:

The free version of Nagios is a little more complex to setup as you have to manually edit the configuration files on the server that you have it on.  If you are running the free version, I’m going to assume that you are aware of how to edit the configuration files and how to verify the configuration file has no errors, and how to restart the service.  If you are unaware, please refer to the Nagios help documentation.  You will need to create a Host Name, Service Name, and a Check Command for the Webmetrics API.  I wasn’t able to find a way to utilize the $ARG#$ variables, so I just created a check command for each service name and that worked as expected.  The command will be the same command that you tried earlier to verify the Perl script was working as expected.  Just change the Service ID for each service you want to monitor.

Advertisement