Monitoring Your Servers via the System Health API
Last modified on 22 March 2016 10:30 AM
Introduced in PaperCut 15.3, the System Health API exposes a REST API endpoint for the purposes of monitoring your PaperCut deployment. Accessible via HTTP, this API presently facilitates monitoring of the online status of PaperCut Application Servers and Site Servers, as well as the databases employed by these servers.
In less alarmingly fancy terms, this means your PaperCut Application and Site Servers provide a URL which reports the current state of the database. You can go ahead and check-in with them right now! Just plug the following into your web browser’s address bar, replacing ‘serveraddress’ with the hostname or IP address of your Application Server or Site Server:
You should see something like the following:
If you don’t, and you’re running PaperCut 15.3 or newer, and the server is normally accessible from your network location, then you might have a situation on your hands! Which, as it happens, is exactly why monitoring and alarming can come in handy.
Monitoring and Alarming
There’s an enormous variety of readily available monitoring tools out there in the wild. Some open source and free, plenty more for enterprise; some quite straightforward, and others endlessly scaleable and customisable. At their core, however, they all share the purpose of keeping you informed of the state of your servers, applications, services, and infrastructure. Data collected by these tools can be used towards many ends; for example, it could be graphed to allow analysis of ongoing system performance and reliability, such that informed decisions can be made surrounding resourcing changes.
In a more immediate capacity, alarming can be configured on the basis of this monitoring; effectively, notifications which are triggered by observed changes in the state of your devices. A log entry could be recorded when a server’s CPU utilisation passes a certain threshold, or an incident ticket could be opened when network bandwidth becomes saturated, or perhaps an email could be sent when a particular application becomes unavailable. Which reminds me…
Here’s One I Prepared Earlier
The following is a high level how-to, running through an example of configuring some basic monitoring and alarming of PaperCut using the System Health API. In this example, the third party network monitoring tool used is PRTG Network Monitor. Which of the many, many available network monitoring tools is right for your environment will, of course, depend on many factors beyond the current scope of this article, but I’ve chosen PRTG Network Monitor because:
Want some other options? Maybe look into Nagios, Icinga, Zabbix… the list goes on!
Pick a server in your environment which has network visibility of the PaperCut server you wish to monitor. Put simply, the server needs to be able to successfully access this url:
If you’re running PaperCut 15.3 or later, the server is online, and you seemingly can’t access this URL, you’ll want to check to make sure the hostname can be resolved by your DNS (or that the IP address is correct), and that TCP communications over port 9191 are allowed by your firewall. Also note that you might have configured the PaperCut server to use some other port within your environment!
Download and install PRTG Network Monitor on this server. When done, it should automatically open up its web interface, and start auto-discovering objects in your environment visible over the network. It’ll probably look something like this when done, only the structure will be full of discovered elements on your network.
Either identify your PaperCut server in this structure, or click to “Add Device” to manually add it. In the screenshot below, I’ve given my new device a descriptive name, and provided the relevant hostname for reaching it.
When it has been successfully added, it will appear in the structure similarly to as shown below.
Click to “Add Sensor” for your server; this is where we configure the particular element we will be monitoring on it. In the page that appears, you’ll find a ‘SEARCH’ field right at the top. Enter “HTTP XML/REST Value” into this field in order to filter the list of available sensor types down to the one we want.
Click to “Add This” when you find it!
There are presently one node available for monitoring in our REST API endpoint, ‘database’, with two properties, ‘online’ and ‘reason’. The values of these two properites will change as the status of the database changes; if ‘online’ is ‘true’, the database is currently running. If ‘online’ is ‘false’, the database is offline, and the value of ‘reason’ will be populated with an error message describing why. And if the value of either of these node properties can’t be retrieved, then the PaperCut application service itself must be down, or temporarily unreachable over the network!
The first sensor we add will track the ‘online’ property. Note the descriptive name, the correct URL being populated, and the relevant node and property being defined as ‘database/online’.
Other important basic settings for this sensor would be to make the message easily interpretable by changing the “Custom Message” field to read “Online: %1”, and making sure that the “If Value Changes” option is set to “Trigger ‘change’ notification”, so that when the value of this property changes, the monitoring tool knows to act upon it!
If you like, you can then add another sensor to track the ‘reason’ property of the ‘database’ node. The basic settings you’ll want are much the same, except you’ll be targeting the ‘database/reason’ XML node and property.
When you’re done, and if all is A-OK super kick-your-heels-up fine (and dandy), you’ll be able to see these sensors reporting successfully for your server device:
It’s imporant to note that before any alarming email notifications will work, you’ll need to configure and test these notifications from with PRTG Network Monitor. The relevant options can be found by first navigating to the ‘Setup’ tab in the PRTG web interface, then clicking on “Notification Delivery”, and scrolling down to the section labelled “SMTP DELIVERY”. Your SMTP server settings will need to provided here, and when you’re done, you can hop back to the ‘Setup’ tab before clicking on “Notification Contacts” in order to check that the system has the correct “Primary Email Address” supplied as the notification recipient. Finally, jump over to the ‘Notifications’ subtab, and click to ‘Test’ the “Email and push notifcation to admin”. If you don’t receive an email notifcation off the back of this test, you might need to check out the ‘Logs’ tab in order to discern what might be wrong with your SMTP settings!
Click on the name of the ‘online’ property sensor for your server to be taken to its ‘Overview’ page. If you shift to the ‘Notifications’ subtab from here, you can click to “Add State Trigger”, as well as “Add Change Trigger”, and ensure that both of these result in an “Email and push notification to admin”. The change trigger will mean that an email will be sent if the ‘online’ property changes from ‘true’ to ‘false’, or vice versa. This sort of change will indicate the database going down, or becoming available once more! Meanwhile, the state trigger will send a notification if the ‘online’ property cannot be retrieved for over 60 seconds; typically, this might indicate that the application service itself has gone down, or that the network interconnect between your monitoring server and the PaperCut server is no longer available.
If you stop the PaperCut service on the server, you should then note that the sensors will switch to a status of ‘Warning’, before then moving to a status of ‘Down’.
… and if our alarming has been configured correctly, you should receive an email around a minute later.
Congratulations! You’ve successfully configured a basic level of monitoring and alarming for your PaperCut server. Naturally, we’ve only just scratched the surface here. With a little research and experimentation, you’ll quickly begin to realise the many further possibilities now open to you!