In this article we’ll discuss creating a command line interface to query the Monitis Agents and Monitors you have activated for your systems. We’ll provide the source code for the utility in VBScript and we will also be working on a C# version.  We’ll keep things simple for now and start with VBScript and provide a link to the complete source at the end of this article.

To get started we need to identify what information we want to display from our Monitors, what can be easily supported, and what is not supported.  The main parts are the different types of agents that Monitis offers, which are the Internal,
External, and custom monitors.

In this article we’ll focus on the basic ‘framework’ of the utility that deals with the definition of some classes to make working with the various agents and monitors easier, accepting and processing command-line arguments, and a small function library to keep our main script very clean. We’ll introduce a neat little feature of VBScript showing you how to work with include files.

Let’s take a look at the functionality and output we like to get from Monitis-Top.

Querying Internal Monitors

We want to be able to display the latest performance counters from our internal, external, and custom monitors by entering commands like:

MonitisTop /cmd:listagents /type:internal /monitor:all

Which would return the performance counters for all
supported monitors of the internal agents, or

MonitisTop /cmd:listagents /type:internal /monitor:cpu,memory,drive

This returns the Cpu, Memory, and Drive monitors for the internal agents.

Querying Process Monitors

We can enter query the process monitors that we’ve configured in our Monitis dashboard like so:

MonitisTop /cmd:listagents /type:int  /process:outlook,search

This will return any process monitors containing the phrases ‘outlook’ and ‘search’. MonitisTop will automatically wildcard any processes listed on the command line.

Querying External Monitors

Monitis Top can also be used to query external monitors. You can specify the parameter /type:ext or /type:all, where ext will only return the external monitors and all returns both internal and external monitor results. For example, the command:

MonitisTop /cmd:listagents /type:all /monitor:cpu

will return both the internal CPU monitor result and the external monitors.

The results will show by each location that you have specified for a monitor.

Managing API and Secret Keys

We want similar commands for the external and custom agents.  In addition, it would also be nice if there was some functionality to maintain our APIKeys, so we’ll add a function that allows you to set and display these keys by entering:

MonitisTop /cmd:setkeys  /apikey:<yourapikey> /secretkey:<yoursecretkey>

Similar, you can display the keys with the command:

 MonitisTop /cmd:getkeys

VBScript Include Files

We’ll use VBScript to program the code for MonitisTop  initially. In the next phase of this project we’ll use C#. If you’re not  familiar with the possibility of using include files in VBScript, take a look  at the code snippet below.

Sub Include(strFilename)
	On Error Resume Next
	Dim oFSO, f, s

	Set oFSO = CreateObject("Scripting.FileSystemObject")
	If oFSO.FileExists(strFilename) Then
		Set f = oFSO.OpenTextFile(strFilename)
		s = f.ReadAll
		f.Close
		ExecuteGlobal s
	End If

	Set oFSO = Nothing
	Set f = Nothing
	On Error Goto 0
End Sub

Class Definitions

To make working with the various agents and monitors more manageable, we’ll create a few classes that we use to store the performance counter results we get back from the Monitis server. To start we’ll create a few classes; one for the agents, one for the monitors belonging to an agent, and one for the various metrics and values in a monitor. We want the Agent class to maintain a list of Monitors, and the Monitor class in its turn maintains a list of Metrics.

Class class_Metric
	Public Name
	Public Metric
	Public Result
	Public Suffix
	Public Width

	Private Sub Class_Initialize
		Name = ""
		Metric = ""
		Result = ""
		Suffix = ""
		Width = 0
	End Sub
End Class


Class class_Monitor
	Public Id
	Public Name

	Public MetricList

	Private Sub Class_Initialize
		Id = ""
		Name = ""
		Set MetricList = CreateObject("Scripting.Dictionary")
	End Sub

	Private Sub Class_Terminate
		Set MetricList = Nothing
	End Sub
End Class


Class class_InternalAgent
	Public Id
	Public Name
	Public MonitorList

	Private Sub Class_Initialize
		Set MonitorList = CreateObject("Scripting.Dictionary")
	End Sub

	Private Sub Class_Terminate
		Set MonitorList = Nothing
	End Sub
End Class

In the class_InternalAgent we create a list of monitor objects that is initialized in the constructor of the class. Notice that in VBScript the methods Class_Initialize and Class_Terminate are automatically called if they are defined and these methods compare to your C# constructor and Dispose methods.

Retrieving the Internal Agents

Once we have parsed the list of monitors that we want to show (specified on the command line), we can call the function GetInternalAgents. In the function below aObjHttp, aShowMonitors, and aShowProcesses  are input values, while aObjAgents is an output value. It returns the list of internal agents retrieved from the API.

Function GetInternalAgents(aObjHttp, aObjAgents, aShowMonitors, aShowProcesses)
	Dim objAgents, xmlAgents
	Set objAgents = CreateObject("Scripting.Dictionary")

	'Retrieve the list of agents
	url = "http://www.monitis.com/api?action=agents&apikey=" + apiKey + "&output=xml"
	aObjHttp.open "GET", url, False
	aObjHttp.send

	'Parse response
	Set xmlAgents = CreateObject("Microsoft.XMLDOM")
	xmlAgents.async = False
	xmlAgents.LoadXML(aObjHttp.responseText)
	If xmlAgents.parseError.errorCode <> 0 Then    
		wscript.Echo xmlAgents.parseError.errorCode    
		wscript.Echo xmlAgents.parseError.reason    
		wscript.Echo xmlAgents.parseError.line
	End If  	


	'Retrieve the agent information for each agent
	For Each agent in xmlAgents.documentElement.childnodes

		'Create an InternalAgent Object	
		Set IntAgent = New class_InternalAgent
		IntAgent.Id = agent.selectSingleNode("id").text
		IntAgent.Name = agent.selectSingleNode("key").text

		'Retrieve the agent information 
		url = "http://www.monitis.com/api?action=agentInfo&apikey=" + apiKey + "&output=xml&agentId=" + IntAgent.Id + "&loadTests=true"
		aObjHttp.open "GET", url, False
		aObjHttp.send

		Set xmlAgentInfo = CreateObject("Microsoft.XMLDOM")
		xmlAgentInfo.async = False
		xmlAgentInfo.LoadXML(aObjHttp.responseText)

		For Each info in xmlAgentInfo.documentElement.childnodes

			If aShowProcesses.Count = 0 Then
				GetGlobalMonitors aObjHttp, info.childnodes, IntAgent, aShowMonitors
			Else
				If LCase(info.nodename) = "processes" Then
					GetProcessMonitors aObjHttp, info.childnodes, IntAgent, aShowProcesses
				End If
			End If

		Next

		'Add the agent object to the list of agents
		aObjAgents.Add IntAgent.Id, IntAgent
	Next

End Function

The main part of this function is the creation of the Agent class, retrieving the ‘loadTests’ from the API and cycling through the list of returned Monitors for each Agent.

Because we want to build in support for querying process monitors as well as global drive, memory, and cpu monitors, we’ve included the list ‘aShowProcesses’. This list contains the processes entered on the command line that we want to query. If
this list contains zero elements, the program defaults to collecting and returning the global monitors.

After GetGlobalMonitors (or GetAgentProcessMonitors) have returned, we’ll add the Internal Agent object to aObjAgents; the list of Internal Agents.

In the GetAgentMonitors function we’ll collect all the monitors of an agent and make a call to GetResults to retrieve all the metric
values.

Function GetGlobalMonitors(aObjHttp, oNames, aObjAgent, aShowMonitors)
	Dim oName
  
	For Each oName in oNames

    	If oName.NodeName <> "#text" And oName.NodeName <> "process" And _
		  SupportedMonitors.Exists(LCase(oName.NodeName)) And _
		  aShowMonitors.Exists(LCase(oName.NodeName)) Then
    
    		' Create new monitor object
			Set Monitor = New class_Monitor
			Monitor.Name = GetMonitorName(oName.selectSingleNode("name").text)
		    strMonitorName = LCase(GetMonitorBaseName(Monitor.Name))
			Monitor.Id = UCase(oName.selectSingleNode("id").text)
			Monitor.DisplayName = UCase(Monitor.Name)

			url = "http://www.monitis.com/api?version=2&apikey=" & apikey & "&output=xml&action=top" & strMonitorName & "&limit=50&detailedResults=true"

			aObjHttp.open "GET", url, False
			aObjHttp.send
			Set oRes = CreateObject("Microsoft.XMLDOM")
			oRes.async = False
			oRes.LoadXML(aObjHttp.responseText)

			Set oNode = oRes.selectSingleNode("data/tests")
			If Not oNode Is Nothing Then
				For Each oCell In oNode.childnodes
					GetResult oCell, Monitor, SupportedMonitors(strMonitorName)
				Next
				aObjAgent.MonitorList.Add Monitor.Name, Monitor
			End If
		End If 

	Next  
End Function

In GetGlobalMonitors we create a Monitor object for each required monitor we want to return and call the function GetResult to retrieve the metric values for each monitor.

Function GetProcessMonitors(aObjHttp, oNames, aObjAgent, aShowProcesses)

	url = "http://www.monitis.com/api?version=2&apikey=" & apikey & "&output=xml&action=topProcessByCPUUsage&limit=50&detailedResults=true"

	aObjHttp.open "GET", url, False
	aObjHttp.send
	Set oRes = CreateObject("Microsoft.XMLDOM")
	oRes.async = False
	oRes.LoadXML(aObjHttp.responseText)

	Set oNode = oRes.selectSingleNode("data/tests")
	For Each t In oNode.childnodes

		Set oTest = t.selectSingleNode("testName")
		If Not oTest Is Nothing Then

			If ShowThisProcess(oTest.text, aShowProcesses) Then

				'Create a new monitor object
				Set Monitor = New class_Monitor
				Monitor.Id = t.selectSingleNode("id").text
				Monitor.Name = t.selectSingleNode("testName").text
				Monitor.DisplayName = GetMonitorName(t.selectSingleNode("testName").text)

				'Retrieve the results for this monitor
				GetResult t, Monitor, SupportedMonitors.Item("process")

				'Add the monitor to the list of agents
				aObjAgent.MonitorList.Add Monitor.Id, Monitor

			End If

		End If

	Next

End Function

'-------------------------------------------------------------------

Function ShowThisProcess(aProcess, aShowProcesses)
	ShowThisProcess = False
	For Each sp In aShowProcesses
		If (InStr(LCase(aProcess), LCase(sp)) > 0) Or (sp = "all") Then
			ShowThisProcess = True
		End If
	Next
End Function

'-------------------------------------------------------------------

Function GetResult(aNode, aMonitor, aFields)
	arrValues = Split(aFields, "|")
	For Each value In arrValues 

		'Split each value in the API field name and the suffix string 
		arrDetails = Split(value,",")
		strValue = arrDetails(0)
		strSuffix = arrDetails(1)

		'Retrieve the result for the given counter
		Set t = aNode.selectSingleNode(strValue)
		If Not t Is Nothing Then

			'Create a new metric object
			Set Metric = New class_Metric
			Metric.Name = strValue
			Metric.Result = t.text & strSuffix

			'Add the metric object to the current monitor object
		 	aMonitor.MetricList.Add Metric.Name, Metric
		End If

	Next
End Function

The GetResult function loops through all the result values of a monitor, creates a Metric object for each monitor and adds it to the Monitor object, and finally the function ShowInternalAgents writes all results to the screen.

Sub ShowInternalAgentsMonitors	
	'Write the list of agents to the screen	
	For Each agent In InternalAgents.Items
		WScript.Echo "" 
		WScript.Echo "-------------------------------------------------------------------------------"
		WScript.Echo " AGENT: " & agent.Name
		WScript.Echo "-------------------------------------------------------------------------------"

		strHeader = ""
		strRow = ""

		For Each monitor In agent.MonitorList.Items

			For Each objMetric In Monitor.MetricList.Items
				strHeader = strHeader & format(objMetric.Name, objMetric.Width)
				strRow = strRow & format(objMetric.Result & objMetric.Suffix, 
				objMetric.Width)
			Next

		Next

		WScript.Echo strHeader
		WScript.Echo strRow
	Next
End Sub

The function GetExternalMonitors gathers all the external monitors, the locations, and the monitor results.

Function GetExternalMonitors(aObjHttp, aObjAgents, aShowMonitors)
	Dim objAgents, xmlAgents
	Set objAgents = CreateObject("Scripting.Dictionary")

	'Create the dummy Agent object
	Set Agent = New class_InternalAgent
	Agent.Id = ""
	Agent.Name = "EXTERNAL"

	WScript.Echo "Acquiring external monitors..."

	'Retrieve the list of agents
	url = "http://www.monitis.com/api?apikey=" + apiKey + "&output=xml&version=2&action=tests"
	aObjHttp.open "GET", url, False
	aObjHttp.send

	'Parse response
	Set xmlMonitors = CreateObject("Microsoft.XMLDOM")
	xmlMonitors.async = False
	xmlMonitors.LoadXML(aObjHttp.responseText)
	If xmlMonitors.parseError.errorCode <> 0 Then    
		wscript.Echo xmlMonitors.parseError.errorCode    
		wscript.Echo xmlMonitors.parseError.reason    
		wscript.Echo xmlMonitors.parseError.line
	End If  	


	'Retrieve the agent information for each agent
	For Each mon in xmlMonitors.documentElement.childnodes

		'Create a Monitor Object	
		Set Monitor = New class_Monitor
		Monitor.Id = mon.Attributes.getNamedItem("id").text
		Monitor.Name = mon.text
		Monitor.DisplayName = mon.text

		dt = DateSerial(year(now), month(now), day(now))
		url = "http://www.monitis.com/api?action=testresult&apikey=" + apiKey + "&output=xml&testId=" & Monitor.Id + "&timezone=" & timezone & "&day=" & day(dt) & "&month=" & month(dt) & "&year=" & year(dt)
		aObjHttp.open "GET", url, False
		aObjHttp.send

		Set oRes = CreateObject("Microsoft.XMLDOM")
		oRes.async = False
		oRes.LoadXML(aObjHttp.responseText)

		'Loop throught the locations
		For Each t In oRes.firstchild.childnodes
			If t.nodeName = "location" Then

				Set Metric = New class_Metric
				Metric.Name = t.Attributes.GetNamedItem("name").text

				'Loop through the results for the current location
				For Each cell In t.firstChild.childnodes
					If LCase(cell.nodename) = "cell" Then
						Metric.Result = cell.text	
					End If
				Next

				'Add the Metric object to the Monitor List
				Monitor.MetricList.Add Metric.Name, Metric
			End If
		Next

		'Add the agent object to the list of agents
		Agent.MonitorList.Add Monitor.Id, Monitor
	Next


	aObjAgents.Add Agent.Id, Agent
End Function

The complete code of this article is available for download at GitHub.

In the previous article we’ve shown how easy it is to integrate popular Nagios server monitoring commands, or plugins, with Monitis M3 monitoring framework.

However, given the fact you have a working Nagios configuration, which is vast and complex – I can sympathize with your unwillingness to actually migrate to Monitis.

Porting each and every systems monitoring command manually to M3 can be a tedious task, but this is why we invented programming, didn’t we?

In the following short (but useful) article I’ll outline the design and usage of the “Nagios to M3 converter”.

The voice of reason

Why would you want to port your Nagios configuration and have Monitis handle it?
Monitis is not only a hosted service, but it’ll also let you setup more comprehensive alerts when one of your services is down. This would purely improve your server monitoring in your organization, providing higher availability and less maintenance.

M3 Universal monitoring framework – a short refresh

Monitis Monitor Manager or M3, for those of you who for any awkward reason managed to forget, is a very simple utility that would help you load command output to Monitis.

M3 uses an XML file for configuration, whereas for each command you are required to specify the following:

1. The command to invoke
2. The regular expression that parses your interesting output

Pretty simple indeed. In the last article about M3, I’ve provided a link to a sample M3 configuration for various Nagios commands.

Nagios to M3 converter

Also this time your loyal servant has done most of the work for you, implementing as much as possible for you. Yes, it does make the articles slimmer and your job a lot easier.
The code checkout snippet:

 # mkdir -p /usr/share/monitisexchange && cd /usr/share/monitisexchange # git clone git://github.com/monitisexchange/Monitis-Linux-Scripts.git # cd Monitis-Linux-Scripts/M3 

Prerequisites

The converter requires the perl module Nagios::Object.
The module is used for parsing nagios’ configuration. It can be easily installed via CPAN, or by downloading the module and installing it manually.
Via CPAN, the command would be:

 # perl -MCPAN -e 'install Nagios::Object' 

A simple invocation

OK, it’s checked out, how is it used? – easy:

 # cd /usr/share/monitisexchange # ./NagiosToM3Converter.pl /etc/nagios/conf.d/internet.cfg > m3_nagios_config.xml 

This will dump to STDOUT a M3 formatted XML with the relevant configuration from your nagios configuration. Essentially it’ll just port your nagios configuration to a M3 format.
Then we can invoke M3 with the newly created configuration:

 # ./Example.pl m3_nagios_config.xml 

Easy as, ain’t it?

Design of Nagios to M3 converter

I believe in reusing code snippets if they exist. As mentioned – for the implementation of the NagiosToM3Converter I used the perl module Nagios::Object.
Iterating on the various commands and hosts configured in a nagios configuration is very easy. For each command we encounter, we’ll invoke a callback function.

Throughout the invocation we have a XML context, the one we’ll dump to STDOUT in the end of the execution.

So in order to configure the “check_ping” command, we’ll call “_cb_check_ping”, which would in turn just add the relevant XML elements to our context.

The Nagios to M3 converter is still work in progress. Currently the only commands implemented are check_ping and check_http. However, more commands will be added shortly – and please contribute if you can.
Now that’s all folks, just use it – it’s plain easy!

Liked it? Sign up for Monitis and try it now! Don’t forget to check also monitisexchange – our git-hub open source repository for some more surprises.

Nagios, a systems monitoring software

What’s Nagios? – Nagios is a rather simplistic monitoring software. And I like simple things. Nagios’ responsibility is not necessarily to draw nice graphs for your boss or collect data you may or may not need.

Nagios simply decides whether your system runs properly. And for this question there is a very explicit answer – a YES or a NO. Nagios will alert you if the answer is a NO.

In the following article I’m going to show how easy it is to integrate Nagios with Monitis.

M3 – a Universal monitoring framework for Monitis custom scripts

M3 (Monitis Monitor Manager) design and usage examples were outlined in this previous article – which I suggest reading before proceeding with this one.

I had a claim in the previous article that M3 is fairly versatile and not much longer after comitting M3 came the challenge – integrate M3 with Nagios.

OK, why hosted monitoring?

Yes, it’s a good question, if Nagios gives you the nice functionality, then why export this data to Monitis and start all over again?

Honestly, Monitis‘ hosted monitoring will give you much more than Nagios. In addition to the invaluable alerts, it’ll give your enterprise a much more comprehensive and centralized monitoring solution than Nagios.

Let me please ask you one simple quest -what’s monitoring your nagios server? – I’m sorry to hear it is a single point of failure. Please consider Monitis then.

Not only that by using cloud-based monitoring you can (and should) eliminate the need for another dedicated monitoring server in your business, Monitis, being a hosted service rather than a piece of software is much more tolerant to network or server failures. The headache of taking care for a rock solid monitoring solution is ours – we’ll do it for you – and we love it.

Slight code changes to M3 framework

M3 was designed to collect data counters from various applications using regular expressions and parse the desired data.

However, with Nagios, it is less about collecting “89MB” or “29 r/s”. With Nagios it’s more about deciding whether the desired check is OK or not. 2.0

For example, lets have a look at the infamous check_ssh plugins. It’ll simply check if SSH is reachable on a host – usually used to make sure a host is alive. Upon success we’ll have:

 SSH OK - OpenSSH_5.6 (protocol) 

And on failure:

 Connection refused 

Or:

 CRITICAL - Socket timeout after 10 seconds 

From our point of view, only if we had “SSH OK” then the test succeeded, upon any other case we consider the test as a failure.

In Monitis API we can define a boolean variable for checks. M3 reflects Monitis API, thus, if we’ll define a boolean check in M3 we’ll get a slightly different behavior than any other check (integer, string or float) – and this was the only code change required. In the next example we’ll delve into it.

Quick start

In the previous article about M3 I outlined how to use M3. This time the only change is that you have to use the config_nagios.xml sample file instead. I suggest having a look at config_nagios.xml as it might just be self-explanatory for many people.

First Nagios plugin: check_ssh

We’ve already shown what values check_ssh might return. Here comes an XML configuration snippet for M3 if you want to integrate check_ssh:

<monitor name="Nagios check_ssh">
	<exectemplate>/usr/lib/nagios/plugins/check_ssh monkey
	</exectemplate>
	<metric name="SSH check">
		<type>boolean</type>
		<uom>SSH Connectivity</uom>
		<regex>^SSH OK</regex>
	</metric>
</monitor>

What happens here is very simple. M3 will execute “/usr/lib/nagios/plugins/check_ssh monkey” and if the string returned contains “SSH OK”, we'll simply report this check to Monitis as a success. If there's no “SSH OK” in the string we'll declare it as a failure.

Simple, isn’t it?

Second Nagios plugin: check_load

In a previous article the integration of Nagios and Monitis was outlined, integrating the check_load plugin. M3 can do it just as well. The configuration for the check_load plugin would produce 3 counters that we will parse them all and send their data to Monitis: There is nothing special about this example, it’s a simple M3 capability.

<monitor name="Nagios check_load">
	<exectemplate>/usr/lib/nagios/plugins/check_load -w 0,0,0 -c 0,0,0
	</exectemplate>
	<metric name="Load1">
		<type>integer</type>
		<uom>Processes in queue</uom>
		<regex>load1=([0-9.]+);</regex>
	</metric>
	<metric name="Load5">
		<type>integer</type>
		<uom>Processes in queue</uom>
		<regex>load5=([0-9.]+);</regex> </metric>
	<metric name="Load15"> <type>integer</type>
		<uom>Processes in queue</uom>
		<regex>load15=([0-9.]+);</regex>
	</metric>
</monitor>

However, it is recommended later to set your limits in Monitis and decide when and how to receive alerts. Setting your limits and alerts are described in this article.

More Nagios plugin examples

config_nagios.xml provide some more examples for integrating nagios plugins with Monitis, among them are check_mysql, check_procs, check_users and some others.
There’s no real need in my opinion to delve into them as they merely represent some more regular expressions that’ll parse some different output.

Liked it? Sign up for Monitis and try it now! Don’t forget to check (and follow) also monitis exchange – our github open source repository for some more surprises.

Mon.itor.us is our 100% free website and server monitoring service. It is unique among similar services in that it imposes no cap on the number of URL’s monitored. As a result, we have some users monitoring hundreds, even thousands of URL’s from one account, for free, forever. That’s great, but what if you want to upgrade to our premium service, Monitis? Until now, you had to set everything up from scratch, but we’ve decided to make it extremely easy with a new Upgrade Wizard. It walks you through easy steps that allow you to select the monitors you’d like to keep and/or add in your upgraded account.

The first step lets you select the external monitors you’d like to keep and specify how many additional ones you’ll need and their frequency. The monthly and annual price is reflected at the bottom of each step. The next 2 steps allow you to add fullpage, transaction, internal and cloud monitors to your account. The last step lets you select API access, specify your SMS alert needs and select a payment method and Bam, proceed to checkout.

The Wizard has been active for a day and we’ve received great feedback so far. I think the step-by-step approach is a huge improvement in User Experience over the previous Upgrade form, which showed a bunch of stuff in one window. If you have upgraded from Mon.itor.us to Monitis and have any thoughts on our upgrade process please comment.

Nagios is a widely used monitoring software for systems and networks. It provides the flexibility to monitor anything on your systems or networks using a script or plugin.  Known for having plugins and scripts available to monitor your needs, Nagios’ the interface and user friendliness leaves much to be desired.  Plus you have to maintain and monitor another server to store and analyze the data provided through your Nagios plugins and scripts.  And worst of all, if your Nagios server or network fail – you may not get an alert at all when you need them the most.

A hosted system monitor gathering your stats is a good way to ensure that alerts get to you, and having it have nice tools and interfaces is definitely a bonus.  Monitis is a hosted systems and networks monitoring solution that offers a simple user interface, with powerful tools, and a distributed network to prevent any service failures  blocking your alerts.  It will free up your sysadmins from monitoring their monitoring servers, and will allow them to focus on the issues rather than looking for the issues.

But suppose you already rely on Nagios scripts and plugins.  There is a simple way to utilize these already known and popular plugins and scripts with a simple wrapper script loading data to your Monitis account.

Monitis provides you with the ability to measure any metric you want through the Custom Monitor.  I will demonstrate by creating a Custom Monitor that accepts data from the Load plugin of Nagios. The Load plugin for Nagios monitors the average load in 1 minute, 5 minute, and 15 minute increments and will alert on user-defined Warning and Critical levels for each of the 3 average load increments.

Create Monitis Custom Monitors

The first thing you need when sending data to Monitis is a Custom Monitor.  The Custom Monitor is where you will store your information for analysis or alerting purposes.  In order to quickly setup the Custom Monitor download this script: https://github.com/monitisexchange/Monitis-Linux-Scripts/blob/master/API/monitis_create_monitor.sh.

To use the above script, you will need your API Key and Secret Key available from your Monitis Account page.   If you do not have a Monitis Account, you can get a free trial by going here.

Now we are set to create our Custom Monitor where we can load data from the Load plugin for Nagios.  The Load plugin for Nagios monitors 3 results plus has a state value (OK, WARNING or CRITICAL).  So the Custom Monitor that we need to create will monitor these same values, plus use a numeric state value for graphing.  You can run the check_load plugin without the use of nagios to see its default values and expected parameters.

The -w sets the warning level of the avg load and the -c sets the critical level.  You have three options for 1, 5, 15 minute intervals.  So run the plugin with some values in -w and -c.  In the output, you should notice that it gives you State, the load averages results, and then after the | is the performance data.  Performance data is not present for every plugin.

We want to capture the load averages and state for our Custom Monitor.  So we need to setup a Custom Monitor that has 5 columns – load1, load5, load15, state, and state_val.  State_val is used for graphing the different states of OK, WARNING, or CRITICAL.  Here is how to run monitis_create_monitor.sh:

$ ./monitis_create_monitor.sh -n "Load Monitor" -m loadMonitor -r "state:State:state:3;state_val:State Value:state:2;load1:Load 1 Min:load:2;load5:Load 5 Min:load:2;load15:Load 15 Min:load:2" -a API_KEY -s SECRET_KEY

The -n is the Name of the Custom Monitor, -m is the Tag of the Custom Monitor, -r is the ResultParams of the Custom Monitor, -a is your API Key, and -s is the Secret Key.  Definitions for the ResultParams and other necessary Custom Monitor API requests, are available here: http://www.monitis.com/api/api.html#addCustomMonitor

Now you should be able to log into your Monitis account and go to Monitors -> Manage Monitors -> Custom Monitors and add your newly created monitor.

In front of you is your customizable systems monitoring Dashboard.  You are able to place the monitors that are most important to you right in front of your face, not amongst a list of never-ending checks and monitors.  You can have graphs and status checks mixed on the same Dashboard.  The interface is intuitive and has many possibilities for server and network health analysis.

Create Nagios Wrapper Script to Send Data to Monitis

Since a Custom Monitor without any data is not all that interesting, we want to populate it with some data, from the Nagios plugin.  The simplest way is to wrap the plugin script with a custom wrapper script.  Here is an example for the check_load plugin: https://github.com/monitisexchange/Monitis-Linux-Scripts/blob/master/nagios/monitis_nagios_load_wrapper.sh

This script relies on the script found here to upload data to your Custom Monitor: https://github.com/monitisexchange/Monitis-Linux-Scripts/blob/master/API/monitis_add_data.sh

Using these two scripts, you are able to quickly upload data to your Custom Monitor.

Basically this script runs the plugin then parses through the data and sends the results off to your Custom Monitor.  We are now able to call this script from the command-line and send output to Monitis Custom Monitor.  Here is an example:

$ ./monitis_nagios_load_wrapper.sh -w 5,3,3 -c10,5,4
OK - load average: 0.88, 0.74, 0.65|load1=0.880;5.000;10.000;0; load5=0.740;3.000;5.000;0; load15=0.650;3.000;4.000;0;

As you notice, it outputs the same value as the original check_load plugin.   We are now able to utilize this script to run without Nagios and send data to the Custom Monitor we created.  This frees up the Nagios server we used to have for other services, such as that overloaded webserver, that you have been meaning to scale up for load balancing.

For checking load on a regular basis, we could set the wrapper up in a cronjob.  Since we are also outputting the original output of the check_load plugin, we are able to place this script directly into Nagios and replace the check_load plugin.  This would allow you to utilize both your internal monitoring server and your Monitis account during the transition from Nagios to Monitis, or as a second layer of monitoring.

Once you create your cron or restart Nagios, it will start sending data to your Custom Monitor.

Here is a sample output from a graph of the Custom Monitor we created.  I put a nice load on the end there by doing a large bzip2 process, while copying files to a different filesystem.  Much nicer than any graph displayed in Nagios.

Setting Up Alerts from Monitis:

OK, we have the data graphing, we all think the interface is beautiful, but we need to setup alerts.  Relying on Nagios to alert you is not always the most comforting solution, if the alert is due to network failure or if the Nagios server is not functioning properly, the alert will never get to you.

Monitis has a distributed framework, which means a single failure on a monitoring server will not prevent you from receiving your alert.  You get to leverage the benefits of this network for alerting from within your Custom Monitor.  In the Dashboard, from your Custom Monitor we can go to Notification rules and setup a new notification:

Here you can setup alerts based on the numeric values we captured in the wrapper script.  So we can have an alert on Load 1 Min > 10 or Load 5 Mins > 8.  We can also setup an alert if the load is too low, i.e. you are not receiving requests on your web server that always runs at >1 in the 1 min average.

That’s it, you now have hosted monitoring utilizing the plugins you already know and trust, but with the added benefit of an easy to use interface, and a distributed network ensuring alert delivery.
Monitis:

The Monitis account is flexible, allowing for integration with many other systems.

Utilizing Nagios plugins and scripts is just one way to monitor your servers.  It has many other tools and monitoring agents available.  But most of all the easy to use interface allows system administrators to focus on using their tools rather than learning their tools.  The distributed network that Monitis has built up around the tool, ensures that your alerts will get to you when you need them.  Get started utilizing Monitis: https://www.monitis.com/free_signup.jsp.

External Scripts:
https://github.com/monitisexchange/Monitis-Linux-Scripts/blob/master/API/monitis_create_monitor.sh
https://github.com/monitisexchange/Monitis-Linux-Scripts/blob/master/API/monitis_add_data.sh
https://github.com/monitisexchange/Monitis-Linux-Scripts/blob/master/nagios/monitis_nagios_load_wrapper.sh

External Links for further information:
http://monitis.com/api/api.html#addCustomMonitor
https://www.monitis.com/free_signup.jsp

Monitis provides you with the ability to monitor almost any detail on your Windows server (also see our post How to Monitor Windows Servers with VBScript, WMI and Monitis).

Using a simple Visual Basic Script (VBS), you will be able to read the value of any Performance Counter on your Windows Server and send it to a Custom Monitor.

It’s easy as pie. Keep reading for the recipe!

About Performance Counters

Performance Counters are used to provide information as to how well the operating system or an application, service, or driver is performing.  Performance Counters are highly detailed, and their counter value covers Processor, Disk, Network interface and a lot of other parameters.  The data from these counters can help determine system bottlenecks, and you can fine tune system and application performance.

You can access data from Performance Counters using interactive applications, such as Performance Monitor, or Windows Management Instrumentation (WMI) programs.  All Performance Counters’s value are made available through WMI via the classes named Win32_PerfFormattedData*.  The values’s names and instances are the same, which you can see within Performance Monitor and other interactive tools.

Also, you can browse available classes and values using WMI Explorer, and you can download it from this address: http://www.ks-soft.net/hostmon.eng/wmi/index.htm.

In this article, we will monitor the counter Connections Established in the Tcpip_TCPv4 class.
Monitoring established connections is important because it can give you a precise idea about what the usage pattern looks like. It can also give you a clue that your server is under attack or it is being exploited.  Of course, if you’re using Monitis to monitor your Performance Counters and something should go wrong, we’ll notify you immediately via a variety of ways — including cell phone, instant messaging, email, SMS, Twitter and URL callback.

You can learn more about monitoring Performance Counters with WMI here: http://msdn.microsoft.com/en-us/library/aa392397%28v=vs.85%29.aspx#using_raw_performance_data_classes

API Access

The first thing you will need in order to monitor WMI data is the Monitis API Key and Secret Key.  The API Key is an alphanumeric code that allows you to access the Monitis API urls and transmit or receive data about your Monitis services.  The Secret Key is an alphanumeric code that allows you to digitally sign your information to ensure that only you can transmit data to your Monitis account.

Your API Key may be disclosed to anyone, but your Secret Key must be maintained private and should not be shared or transmitted.  How safe is that? Very. To obtain your Monitis API Key and Secret Key, log into your account and from the top menu bar, go to:

• Tools,
• API
• API Key

Both your API Key and your Secret Key will appear.

Create a Custom Monitor

A Custom Monitor is needed to display the values you get from external sources.

In order to create it you need go through the following steps:

1. Connect to Monits API and obtain an authorization token
2. Create the Custom Monitor tailored to your needs.

The following VBScript code does it all for you:

'You API key and Secret Key
apiKey = "your API key here"
secretKey = "your secret key here"

'Connecting to WMI, "." is for local computer, specify computer name for another computer
computer = "."
Set oWMI = GetObject("winmgmts:{impersonationLevel=impersonate}!\\" + computer + "\root\cimv2")

'Finds current timezone to obtain GMT date
dtGMT = now
Set oRes = oWMI.ExecQuery("Select LocalDateTime from Win32_OperatingSystem")
For each oEntry in oRes
  dtGMT = DateAdd("n", -CInt(right(oEntry.LocalDateTime, 4)), dtGMT)
next

'Initialize HTTP connection object
Set objHTTP = CreateObject("Microsoft.XMLHTTP")

'Request a token to use in following calls
url = "http://www.monitis.com/api?action=authToken&apikey=" + apiKey + "&secretkey=" + secretKey
objHTTP.open "GET", url, False
objHTTP.send
resp = objHTTP.responseText
token = DissectStr(resp, "authToken"":""", """")

'Adds the custom monitor
url = "http://www.monitis.com/customMonitorApi"
monitorParams = "PerfCtrs_data:Connections:Connections+established:3:false;"
resultParams = "connections:Connections:N%2FA:2;"
name = "Connections established"
tag = "[perfctrs+sample]"
objHTTP.open "POST", url, False
objHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
postData = "apikey=" + apiKey + "&validation=token&authToken=" + token + "&timestamp=" + FmtDate(dtGMT) + "&action=addMonitor&monitorParams=" + monitorParams + "&resultParams=" + resultParams + "&name=" + name + "&tag=" + tag
objHTTP.send postData
resp = objHTTP.responseText

Set objHTTP = Nothing

Function DissectStr(cString, cStart, cEnd)
  dim nStart, nEnd
  nStart = InStr(cString, cStart)
  if nStart = 0 then
    DissectStr = ""
  else
    nStart = nStart + len(cStart)
    if cEnd = "" then
  	nEnd = len(cString)
    else
  	nEnd = InStr(nStart, cString, cEnd)
  	if nEnd = 0 then nEnd = nStart else nEnd = nEnd - nStart
    end if
	DissectStr = mid(cString, nStart, nEnd)
  end if
End Function

Function FmtDate(dt)
  FmtDate = cstr(Datepart("yyyy", dt)) + "-" + right("0" + cstr(Datepart("m", dt)),2) + "-" +  right("0" + cstr(Datepart ("d", dt)),2) + " " + right("0" + cstr(Datepart("h", dt)),2) + ":" + right("0" + cstr(Datepart("n", dt)),2) + ":" + right("0" + cstr(Datepart("S", dt)),2)
end function

Save this code to a file with a .vbs extension (such as createCustMon.vbs) and save it, then run it executing the following command from a command prompt:

cscript createCustMon.vbs

Uploading Performance Counters values to Custom Monitor

Once your custom monitor is created you can start uploading Performance Counters values into it.

Take the following steps:

1. Connect to Monits API and obtain an authToken
2. Get the list of Custom Monitors and locate the ID of the monitor you want to add data to
3. Execute your WMI query and get the necessary Performance Counter values
4. Upload the value to the Custom Monitor

The following script does exactly that:

'You API key and Secret Key
apiKey = "your API key here"
secretKey = "your secret key here"

'Connecting to WMI, "." is for local computer, specify computer name for another computer
computer = "."
Set oWMI = GetObject("winmgmts:{impersonationLevel=impersonate}!\\" + computer + "\root\cimv2")

'Finds current timezone to obtain GMT date
dtGMT = now
Set oRes = oWMI.ExecQuery("Select LocalDateTime from Win32_OperatingSystem")
For each oEntry in oRes
  dtGMT = DateAdd("n", -CInt(right(oEntry.LocalDateTime, 4)), dtGMT)
next

'Initialize HTTP connection object
Set objHTTP = CreateObject("Microsoft.XMLHTTP")

'Request a token to use in following calls
url = "http://www.monitis.com/api?action=authToken&apikey=" + apiKey + "&secretkey=" + secretKey
objHTTP.open "GET", url, False
objHTTP.send
resp = objHTTP.responseText
token = DissectStr(resp, "authToken"":""", """")

'Requests the monitor list in order to find the MonitorID
tag = "[perfctrs+sample]"
url = "http://www.monitis.com/customMonitorApi?action=getMonitors&apikey=" + apiKey + "&tag=" + tag + "&output=xml"
objHTTP.open "GET", url, False
objHTTP.send
resp = objHTTP.responseText

Set oResp = CreateObject("Microsoft.XMLDOM")
oResp.async = False
oResp.LoadXML(resp)

for each oNode in oResp.documentElement.childnodes
  if oNode.selectSingleNode("name").text = "Connections established" then
     monitorID = oNode.selectSingleNode("id").text
     exit for
  end if
next

wscript.echo "Monitor ID: " + monitorID

'Executes the WMI Query to obtain the data
Set oRes = oWMI.ExecQuery ("select ConnectionsEstablished from Win32_PerfFormattedData_Tcpip_TCPv4")
For each oEntry in oRes
  value = oEntry.ConnectionsEstablished
next

wscript.echo "Connections established: " & value

'Posts data
url = "http://www.monitis.com/customMonitorApi"
action = "addResult"
results = "connections:" & value & ";"
unixDate = CStr(DateDiff("s", "01/01/1970 00:00:00", DateSerial(Year(dtGMT), Month(dtGMT), Day(dtGMT)) + TimeSerial(Hour(dtGMT), Minute(dtGMT), Second(dtGMT)))) + "000"
objHTTP.open "POST", url, False
objHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
postData = "apikey=" + apiKey + "&validation=token&authToken=" + token + "&timestamp=" + FmtDate(dtGMT) + "&action=" + action + "&monitorId=" + monitorID + "&checktime=" + unixDate + "&results=" + results
objHTTP.send postData
resp = objHTTP.responseText

Function DissectStr(cString, cStart, cEnd)
  'Generic string manipulation function to extract value from JSON output
  dim nStart, nEnd
  nStart = InStr(cString, cStart)
  if nStart = 0 then
    DissectStr = ""
  else
    nStart = nStart + len(cStart)
    if cEnd = "" then
  	nEnd = len(cString)
    else
  	nEnd = InStr(nStart, cString, cEnd)
  	if nEnd = 0 then nEnd = nStart else nEnd = nEnd - nStart
    end if
    DissectStr = mid(cString, nStart, nEnd)
  end if
End Function

Function FmtDate(dt)
  FmtDate = cstr(Datepart("yyyy", dt)) + "-" + right("0" + cstr(Datepart("m", dt)),2) + "-" +  right("0" + cstr(Datepart ("d", dt)),2) + " " + right("0" + cstr(Datepart("h", dt)),2) + ":" + right("0" + cstr(Datepart("n", dt)),2) + ":" + right("0" + cstr(Datepart("S", dt)),2)
end function

Save this code to a file with a .vbs extension (such as pushDataPerfCtrs.vbs). Then run it executing the following command from a command prompt:

cscript pushDataPerfCtrs.vbs

Testing the Monitor

Each time you run the second script, a value is uploaded to your Custom Monitor.
You can use Windows Task Scheduler to run the script automatically and as frequently as you need.

Add your Custom Monitor widget to your Monitis account like this:

From the Monitors menu, select and click Manage Monitors. Select Create Custom Monitor, then click Add to Window.

Refresh the page after adding new data to see them show up inside the widget.

We at Monitis hope this information on monitoring Performance Counters with VBScript will help you see how important — and easy — it is to use an independent monitoring service for servers. That’s what we do best. If you don’t believe us, check out the testimony of customers who have found extraordinary value in hosted monitoring. For example, one customer, DCmedia Hosting,  says Monitis’s “unique interface is easy to use and informative at the same time making setting up monitoring in a browser anywhere a breeze.”

curl 'http://www.monitis.com/api?action=authToken&apikey=[API Key]&secretkey=[Secret Key]&version=2'

Want to track a certain metric on your server which is not available out-of-the-box?  The Monitis monitoring platform provides you with the ability to monitor almost anything you can think of, including any detail on your Windows servers. Using a simple Visual Basic Script (VBS or vbscript) you will be able to read any value from WMI (Windows Management Instrumentation) and send it to Monitis’s platform for visualization, tracking and alerting — using our so-called Custom Monitoring feature.

About WMI Service

WMI is a core Windows management technology that allows software to monitor and control managed resources throughout a network. WMI gives you a consistent way to access almost any detail of the operating system (OS) such as hardware, devices, services and applications.

When it comes to authentication, in order to manage remote computers, WMI is also easy to use. WMI shares authentication mechanism with other Windows Network operations, such as accessing shared folders on networked servers. So if you can access a remote folder you can also access WMI on that computer. If you are monitoring your server in a domain — you’re probably already done.

Be sure to have Administrator privileges to be able to access all available information.

After ensuring that, if you want to monitor a remote computer just replace the dot in your computer (“.”) with the actual name of the computer to monitor in the scripts below. That’s it!

WMI service offers a wide range of objects where you can find useful information, browse available information and test your queries using WMI Explorer:  Here’s a helpful link: http://www.ks-soft.net/hostmon.eng/wmi/index.htm

Learn more about WMI here, too: http://msdn.microsoft.com/en-us/library/aa384642%28v=vs.85%29.aspx

A Monitoring Platform and API

Monitis’s platform provides an Application Programming Interface (API) to extend and automatize system management and monitoring tasks. The first thing you will need in order to access Monitis’s platform is the Monitis API Key and Secret Key.

The API Key is an alphanumeric code that allows you to access the Monitis API URLs and transmit or receive data about your Monitis services.  The Secret Key is an alphanumeric code that allows you to digitally sign your information to ensure that only you can transmit data to your Monitis account.  Your API Key may be disclosed to anyone and it is like your username, but your Secret Key must be maintained private and should not be shared or transmitted (it is like a password).  To obtain your Monitis API Key and Secret Key, log into your account and, from the top menu bar, go to Tools -> API -> API Key.

Both your API Key and your Secret Key will appear on a dialog box.

Custom Monitoring Script to Monitor Anything on Your Server

Monitis custom monitoring allows you to monitor any metric on a local or remote server, from system-level metrics to application-specific ones. Data from your custom monitor is collected and aggregated just like every other metric within Monitis’s dashboard. You may add alerting (notifications should your server go down or slow to a crawl) or customize graphical views.

In order to create your script, take the following steps:

1. Connect to Monits API and obtain an authorization session token
2. Create the Custom Monitor tailored to your needs.

The following VBScript code does it all for you:

apiKey = "3TE4K9JAJWCQDKRANI3IPTBLQK" 'Replace with your API key
secretKey = "5CK8P21E6A21Q9ARDDRGUJSAK" 'Replace with your secret key

'Connecting to WMI, "." is for local computer else specify the computer name
computer = "."
Set oWMI = GetObject("winmgmts:{impersonationLevel=impersonate}!\\" + computer
+ "\root\cimv2")

'Finds current timezone to obtain GMT date
dtGMT = now
Set oRes = oWMI.ExecQuery("Select LocalDateTime from Win32_OperatingSystem")
For each oEntry in oRes
dtGMT = DateAdd("n", -CInt(right(oEntry.LocalDateTime, 4)), dtGMT)
next

'Initialize HTTP connection object
Set objHTTP = CreateObject("Microsoft.XMLHTTP")

'Request a token to use in following calls
url = "http://www.monitis.com/api?action=authToken&apikey=" + apiKey +
"&secretkey=" + secretKey
objHTTP.open "GET", url, False
objHTTP.send
resp = objHTTP.responseText
token = DissectStr(resp, "authToken"":""", """")

'Adds the custom monitor
url = "http://www.monitis.com/customMonitorApi"
monitorParams = "wmi_data:WMI+data:Free+space+on+C+drive:3:false;"
resultParams = "bytes:Bytes:N%2FA:2;"
name = "sample_wmi_monitor"
objHTTP.open "POST", url, False
objHTTP.setRequestHeader "Content-Type", "application/x-www-form-urlencoded"
postData = "apikey=" + apiKey + "&validation=token&authToken=" + token +
"×tamp=" + FmtDate(dtGMT) + "&action=addMonitor&monitorParams=" +
monitorParams + "&resultParams=" + resultParams + "&name=" + name +
"&tag=[wmi+sample]"
objHTTP.send postData
resp = objHTTP.responseText

Function DissectStr(cString, cStart, cEnd)
dim nStart, nEnd
nStart = InStr(cString, cStart)
if nStart = 0 then
DissectStr = ""
else
nStart = nStart + len(cStart)
if cEnd = "" then
nEnd = len(cString)
else
nEnd = InStr(nStart, cString, cEnd)
if nEnd = 0 then nEnd = nStart else nEnd = nEnd - nStart
end if
DissectStr = mid(cString, nStart, nEnd)
end if
End Function

Function FmtDate(dt)
FmtDate = cstr(Datepart("yyyy", dt)) + "-" + right("0"+cstr(Datepart("m", dt)),2) +
"-" + right("0"+cstr(Datepart("d", dt)),2) + " " +
right("0"+cstr(Datepart("h", dt)),2) + ":" + right("0"+cstr(Datepart("n", dt)),2) +
":" + right("0" + cstr(Datepart("S", dt)),2)
end function

Did you know that you can download monitoring agents from Monitis that check the health of your servers, networks and applications — regardless of whether your firewall is up and running? In fact, these agents (which work for all operating systems) are such a convenience for so many sysadmins and website masters that Monitis has just published a new whitepaper — “Monitis Internal Monitoring Agent: Security and Performance” — to explain the workings behind the technology.

The whitepaper, which can be downloaded free from Monitis’s portal, discusses how these agents deliver the monitoring results in real-time to the Monitis Main Server, to be further displayed via Monitis’s web-based dashboard. The information — sometimes not so good, as in, a site is down — also triggers warnings and critical alerts through a whole menu of notifications, for example, email, mobile phone, SMS, IMs, Twitter and URL callback.

Monitis agents use the Monitis API, which is well documented and open.

Check out the diagram below to see how Monitis agents work:

If you’re thinking: “How will these agents affect my site?” or “Will Monitis’s tools slow down my server or network?” then you need to read this whitepaper — as it discusses how the Monitis agents perform, as well as how they operate securely (Don’t we have enough to worry about as far as security goes?).

For example, as far as performance goes, generally, the internal agent uses an Internet connection very economically: it requests the main server for current tests configuration every minute and then sends the accumulated test information every five minutes. And agents operating in both the Linux and Windows OSs use tiny bits of CPU and occupy modest amounts of virtual memory.

Now let’s talk security. Monitis agents provide standard security with the following features and practices:

• Encrypted HTTPs protocol (used for the connection with main server)
• Client initiated encrypted HTTP — which eliminates altering firewalls, thus reducing risk for possible attacks
• Heartbeat checks performed to ensure that agents are alive and connected with the main server
• The tests configuration and necessary parameters are kept on the main server and sent periodically to the client by using an encrypted channel. Current configuration is stored by the client internally in the memory (not in the file);
• The internal client does nothing other than testing and therefore cannot cause unpredictable system damage — that’s a Monitis guarantee;
• Monitis performs daily and weekly backups, including backups to storage outside of the main server’s data center.

Check out the new whitepaper for more detailed information on how Monitis agents work! And we’d love to get your feedback; please share.