A Heartbeat Monitor is a process that periodically checks if an app is fine. This can be done in multiple ways, either by the monitored application "pinging" the monitoring application in a regular interval; or by the monitoring application asking the monitored application if everything is ok (on a regular interval too). In both cases if the monitored application detects that there is a problem (by not hearing from the app in a while, or not receiving the expected response) then it sends some sort of alert to a system administrator. The model we will describe in this post is the first one, in which the application being monitored (the "Target") contacts the monitoring application (BugLogHQ) in a regular interval. We will then instruct BugLogHQ to send us an alert whenever it hasn't heard from the target app in a set amount of time. On a follow up post, we will describe how to implement the second approach, in which BugLogHQ periodically checks the target app for its status and then tell us whenever there is a problem. There are two steps to build our monitor. First we need to modify our target application (the one that we want to see if it is OK) to periodically send a short message to BugLogHQ telling it that everything is great. The second step is configuring your BugLogHQ server to listen to these messages.

Step 1: Modifying the Target Application

The first thing you need to have is the BugLog Client cfc. This is a small coldfusion component (cfc) that knows how to talk to a BugLog server. If you are reading this, you are probably already using BugLog to keep track of your application errors, so the client cfc is already part of your application. If not, don't worry, there is not magic voodoo here. The gist of what we will do is create a scheduled task that will call a cfm template, which in turn will send an "I'm alive!" message to BugLog. Using your favorite editor or IDE create the following file: heartbeat.cfm If you are using ColdSpring or some other sort of DI engine, then you can replace line 1 to whatever is appropriate for your application. The idea is to obtain an instance to the bugLogService.cfc component. Also, if you are wondering from where this CFC came from, you can find it in the BugLogHQ source code, inside the "bugLog/client/" folder. The argument to the init() method is the URL where your BugLogHQ listener endpoint lives. This could be located in the same server as your application (if you are running BugLog alongside your app) or on a completely separate location (if your BugLog has it's own server). Now you only need to add hearbeat.cfm as a scheduled task using your CFML engine's admin panel. How often to execute? well, that depends on how granular you want to be with your checks. The more frequent the heartbeats, the faster you can react to a downtime. For the sake of this example, let's set the scheduled task to execute every 1 hour.

Step 2: Configuring the Heartbeat Monitor in BugLogHQ

Ok, so now we have the target application happily sending an "I'm Alive!" message every hour to your BugLog server. Now we need to tell BugLog that this is a special message and that if it doesn't receive it then it means that the app is (likely) in trouble. To do that, we will create a new instance of the "Hearbeat Monitor" rule. So, log on into your BugLog server and head into the "Rules" section in the main menu. In the selection box next to "Create new rule of type" select "heartbeatMonitor" and click on "Go". Here is where we tell BugLog how to recognize our heartbeat messages. Here are the different settings and what they mean: Description: This is just a user-friendly text describing this particular rule. You can enter something like "Heartbeat monitor for application X" Timespan: This is how long to wait for a heartbeat message. In Step 1 we configured our scheduled task to emit a heartbeat once every hour, so in here we will set the timespan to 70 minutes (1 hour plus 10 minutes) to give it some extra time just in case the app server is busy. This is the amount of time the monitor will wait before it thinks that there is something wrong. Alert Interval: This controls how often we want to be notified if the app remains down. So if we set it to 30 minutes, once the initial alert of the app being down has been sent to us, BugLog will only notify us again once this amount of time has passed. Otherwise we would be receiving alerts every two minutes until the heartbeat messages are received again. Application: This is the name of the application sending the heartbeats. This is the application name as it appears on its Application.cfc. Host Name: Use this if you want to configure heartbeats for different hosts running the same application. Severity Code: This tells the monitor how to identify which messages to listen to. Remember that on heartbeat.cfc on the target app we used a severity code of "ping". Use that value here. Using a unique severity code is useful so that the heartbeat messages can be filtered out from the other "normal" messages and bug reports. Recipient Email: This is where to send the alerts whenever the target app appears to be down. You can add one or more email addresses here, or even use one of those email addresses that are linked to phone numbers to receive the alert via SMS message. Save the rule definition and then Stop/Start the BugLogListener service (in the BugLogHQ homepage) to make the rule go into effect; and that's it! So there you have it, you can now let BugLogHQ do its thing while you relax poolside drinking fruity umbrella drinks with the comfort of knowing that you will be alerted once your app starts getting into trouble.