How-to: Monitor Custom Windows Application Counters

A common request of up.time is to collect flexible sets of windows performance counters based on custom applications or applications that up.time does not natively gather statistics from. Unfortunately there isn't a point and click method to accommodate this today (there will be /wink.gif” style=”vertical-align:middle” emoid=”;)” border=”0″ alt=”wink.gif” /> ) but the process is relatively straight forward if you are comfortable with a Windows scripting language. The walk through below outlines a standard process that can be used to create your own plug-in monitor much like other existing monitors in the customizations thread.

Terminology & Assumptions

• Agent: This is the target server that up.time will collect stats from
• Scriptomatic: A utility that will crawl Windows counters via WMI
• Language: This example uses vb, XML and bat files
• Platform: This example assumes you are running both a windows agent and up.time is installed on a windows monitoring station

Out example is going to gather a simple windows performance counter. More complex examples with multiple counters and ranges counters are included in the customizations forum.

Step 1: Install Scriptomatic on your target server

Scriptomatic is a free utility published by Microsoft ©. It provides an easy to user GUI that will crawl windows counters and provide an example script to print out those counters. Scriptomatic can be downloaded from Microsoft, a simple google search for 'Scriptomatic' will bring up the download page link.

Download the file (validation required) and install it on a system that has the performance counters you are interested in.

Step 2: Use Scriptomatic To find your counters

Lets get started by browsing your counters. Start Scriptomatic, select 'rootCIMV2' from the 'VMI Namespace' drop down. Under the 'WMI Class' dropdown select the class that contains the counters you are interested in. In our case we select 'Win32_PerfFormattedData_TermService_TerminalServices”. It can take a bit of digging to find the class you are interested in but you will generally find most counters under the Win32_PerfFormattedData* class tree.

Scriptomatic automatically generates a script in the main window that lists all of the values in the counter class you have chosen. Click 'Run' to see what is produced from this script on the command line. In our example we see the following output:

Step 3: Prune the Scriptomatic Output

To keep things simple we are really only interested in the 'ActiveSessions' value from the script output above. To prune the script to only show that output lets make some changes to the Scriptomatic script example. First, save the Scriptomatic example to a file named 'check_agentwts.vbs' somewhere on the agent server. From now on we will change that script directly using a regular text editor.

Remove the following line blocks from the script using a text editor

You should now be left with a much smaller script similar to the one below that will produce the output at the bottom of the next code block

Script Body

Const wbemFlagReturnImmediately = &h10
Const wbemFlagForwardOnly = &h20

arrComputers = Array(“localhost”)

For Each strComputer In arrComputers
   Set objWMIService = GetObject(“winmgmts:” & strComputer & “rootCIMV2″)
   Set colItems = objWMIService.ExecQuery(“SELECT * FROM Win32_PerfFormattedData_TermService_TerminalServices”, “WQL”, _
                                          wbemFlagReturnImmediately + wbemFlagForwardOnly)

   For Each objItem In colItems
      WScript.Echo “ActiveSessions: ” & objItem.ActiveSessions
   Next
Next

[codebox]Script Output

Step 4: Setup the Agent to run your agent script

Now that you have a functioning script on your agent you can setup the up.time agent to execute this script. For those that know WMI this could be done remotely but we have found that authentication and permissions issues are much easier when running the script via the up.time agent.

Enable the up.time agent to run this script by completing these steps

– run regedit
– Open the Agent Registry folder: HKLMSOFTWAREuptime softwareup.time agent
– If a subkey named 'rexec_commands' does not exist, create it by right clicking in the main window and then selecting 'New' -> 'Key'
– Create a new String value for this script, again by right clicking, name it 'run_wts' and give it this value:

Now restart the agent for good measure. Generally we recommend placing your scripts in the up.time agent installation directory under a 'scripts' subfolder.

Your agent side setup is complete /wink.gif” style=”vertical-align:middle” emoid=”;)” border=”0″ alt=”wink.gif” /> You can roll this script out to other agent systems by copying the script to each agent and entering the registry keys to define the script location.

Step 5: Create the monitoring station bat file

In order for up.time to contact the agent and run the agent side script we need to create a script on the monitoring station that will do the work of contacting the agent, getting the results, and then printing them to screen. Because we are in a windows only environment we can use a simple bat file to launch our agent side script. In most cases, and certainly in the examples posted here, the monitoring station script is written in an OS agnostic language like Perl, PHP or Java.

Create a .bat file in your monitoring station installation folder under the 'scripts' sub folder. Name it 'launch_check_wts.bat'. Within the script put the following information:

NOTE: The 'run_wts' portion of this command must match the registry key name on the agent system.

If you run the launch_check_wts.bat manually be sure to set the UPTIME_HOSTNAME environment variable before hand so the agentcmd knows which agent to communicate with. With this .bat file complete this template script can now be used to execute the 'run_wts' command on any of your agent systems.

Step 6: Create the monitoring station plug-in XML

We're almost there. Our scripting portion is done, now we can create the XML definition that tells up.time how to work with this plug-in monitor. Using the Plug-in Monitor XML Generator generate the XML definition for your Terminal Services plug-in. Here are some example settings:

After double checking the settings, click next and save the generated XML as a file.

Step 7: Import the plug-in

Place the XML from the XML generator on your monitoring station in the scripts directory. Name it something easy to remember like 'check_wts.xml'

Using the erdcloader import the XML definition

> cd “C:Program Filesuptime softwareuptime4″
> scriptserdcloader -x scriptscheck_wts.xml

If no error messages appear go to the 'Add Service Instance' page within the up.time UI and verify that your monitor is now available. It should be at the bottom of the page along with the other Advanced Monitors.

Success, you have correctly imported your plug-in monitor. From here you can use this monitor against any windows agent system that you have enabled the correct registry settings for.

Step 8: Test the plug-in

Create your monitor using the Add Service Instance page and have it run against the testing agent. After the monitor is created use the 'Test Service Instance' from the monitor view page to verify that your 'Active Sessions' value is returning from the agent system correctly.

And there you have it, your first custom plug-in designed to gather windows performance counters. Using the simple template above you can create your own plug-in's to gather whatever custom counters you like. You can add multiple counters to the example by adding additional output lines to the vbscript and adding additional names to the XML generator. You can also allow your monitor to collect flexible lists, for instance one block of counters per user who happens to be logged in. An example of that will be posted shortly.

Please help the community and post your examples online.