Sanity Check Plugins for AlwaysUp and Service Protector

AlwaysUp and Service Protector are both designed to keep your applications functioning 24/7. While they can monitor and take action when a wide range of events occur (for example, your program uses too much RAM or CPU), not all failure detection capabilities are built in. For example, if your program doesn't operate correctly when another program has stopped, there is no way for AlwaysUp or Service Protector to find out about the special relationship and stop/restart your application.

Fortunately both AlwaysUp and Service Protector can be extended to "plug in" your own arbitrary, failure detection logic. All you have to do is supply an executable (or batch file) that can detect the failure and communicate that situation to AlwaysUp or Service Protector via a return/exit code. We call these small, targeted failure detection programs Sanity Check Plugins.

A Sanity Check Plugin can be an executable written in any language (C++, C#, VB, Delphi, etc.) or can be a DOS batch file. The only requirement is that it exits with a special code. Feel free to construct your own plugins, specific to your situations, or simply use one that we have already written (below).

---

Available Sanity Check Plugins

We have developed a few Sanity Check Plugins that can be used freely. Each will signal AlwaysUp or Service Protector to:

• Stop/restart your application if a specified program is not running
• Stop/restart your application if a particular file has not changed for a while
• Stop/restart your application if it is using too much virtual memory
• Stop/restart your application if a specific web site/URL is not responding

---

  Stop/restart your application if a specified program is not running

Command Line Usage

	CheckProgramIsRunning.exe <program-name>

where

	<program-name> is the name of an executable, as seen in Task Manager

Example

To check if Microsoft Word is running, use:

	CheckProgramIsRunning.exe winword.exe

Downloads

CheckProgramIsRunning.exe (490 KB)

---

  Stop/restart your application if a particular file has not changed for a while

Command Line Usage

	CheckFileChanged.exe <file-name> <num-minutes> [-v]

where

	<file-name> is the full path to the file to be checked
		- Please enclose in quotes if the path contains spaces.
		- Note that this file name can contain special macro-like
		strings that will be dynamically replaced when the program
		is run. These are:
			$DAY == The current 2-digit month (01-12)
			$MONTH == The current 2-digit day (01-31)
			$YEAR2 == The current 2-digit year
			$YEAR4 == The current 4-digit year
		For example, if today is May 26 2011, then:
			C:\Files\Myfile_$MONTH_$DAY_$YEAR4.log
		will be expanded to
			C:\Files\Myfile_05_26_2011.log
		when the utility is run.

	<num-minutes> is the number of minutes
	-v signals to produce verbose output (optional)

Example

To check if a log file located at C:\myserver\log.txt has not been modified for the past 10 minutes:

	CheckFileChanged.exe "C:\myserver\log.txt" 10

Downloads

CheckFileChanged.exe (230 KB)

---

  Stop/restart your application if it is using too much virtual memory

Command Line Usage

	CheckVMSize.exe <process-id> <vm-size> [-v]

where

	<process-id> is the numeric identifier of the process to be checked.
	<vm-size> is the memory threshold, in MB.
	-v signals to produce verbose output (optional)

Example

To check if the process with ID 4521 is using more that 100 MB of virtual memory:

	CheckVMSize.exe 4521 100

Downloads

CheckVMSize.exe (238 KB)

---

  Stop/restart your application if a specific web site/URL is not responding

Command Line Usage

	check-web-server.bat

Configuration

1. Download our free http-ping executable and place it in a new directory
2. Download the Sanity Check batch file and place it in the same directory
3. Open the batch file in a text editor and modify it to:
   • specify the URL to your web server (instead of http://localhost:80)
   • set the path to http-ping.exe to point to the location where you saved it

Downloads

http-ping.exe (406 KB)
check-web-server.bat (1 KB)

---

Special Command Line Parameters

AlwaysUp and Service Protector are able to pass your Sanity Check Plugins one or more "special" values. Compose your command line with the appropriate string and AlwaysUp/Service Protector will make the substitution before invoking your program.

Replacement String	Replaced With
$ALWAYSUP_PID	The program identifier (PID) of your running application/service. This can be seen in the Task Manager.
$ALWAYSUP_EXENAME	The name of the executable run to invoke your application. (Just the name, not the full path.)
$SERVICEPROTECTOR_PID	The program identifier (PID) of your running service. This can be seen in the Task Manager.
$SERVICEPROTECTOR_SERVICENAME	The name of the service being protected (the short name).

For example, to have AlwaysUp pass your Sanity Check program the application's program identifier (PID), then your command line might resemble this:

	C:\myserver\my_check.exe $ALWAYSUP_PID

If your main application is running with PID 563, then your plugin program will be invoked like this:

	C:\myserver\my_check.exe 563

---

Writing your own Sanity Check Plugins

A Sanity Check Plugin can be an application written in any language (C++, C#, VB, Delphi, etc.) or can be DOS batch file. The only requirement is that it exits with a return code of:

• 0 when the check succeeds;
• 1 when the check fails and the application should be stopped and restarted as you have configured;
• 10 when the check fails and the computer should be rebooted;
• 100 when the check fails and your application should be stopped and not restarted;
• any other value when the check fails due to an error independent of the application being monitored (such as an error internal to the utility), or to simply indicate failure without causing a restart.

In the last case, the application is not restarted but a message is written to the event log (and an email is sent if so configured).

Note that if the Sanity Check plugin fails to complete in 120 seconds, the application will be restarted.