Submit a ticketCall us

Systems Monitoring for Dummies
Our new eBook will teach you the fundamentals and help you create monitors and alerts that are effective, meaningful, and actionable. Monitoring is more than a checkbox on your to-do list. This free eBook will give you practical advice to help you succeed in all aspects of monitoring – discovery, alerting, remediation, and troubleshooting. Don’t miss out on this indispensable resource for newbies, experienced IT pros, and everyone in between. Register Now.

Home > Success Center > Server & Application Monitor (SAM) > SAM 6.5 Administrator Guide > Manage application monitor templates and component monitors > Creating a Windows Script monitor

Creating a Windows Script monitor

doc-icon.png For the ultimate custom template guide, see  SAM Custom Template Guide.

Updated: 3-9-2017

The Windows Script monitor is a component monitor you can assign to poll and collect data directly for a node or in a template. For information on creating a Windows Script monitor, see the section below and the examples.

This component monitor runs a custom Windows script you create to complete scripted tasks and gathering metrics. You can create a Windows Script monitor to have SolarWinds SAM run a script using Windows Script Host. Windows Script Host comes with VBScript and Jscript, but can be extended with other scripting languages.

The script is run on the SAM server using credentials you specify, not on the remote node you are monitoring. When run it processes the script's code, returns an exit code such as positive completion or a specific value, and displays the result in text output.

This monitor has the ability to return up to ten pairs of data on script completion: 10 statistic values and 10 [optional] messages. We recommend using this component monitor in conjunction with the Multiple Statistic Chart to display the value and description in a visual representation.

A maximum of 10 output pairs can be returned. If you exceed the maximum allowed, remove the excess output pairs or they will simply be ignored. Or create multiple Windows Script monitors to return additional values.

Format the Statistic value to use the same decimal separator as the SolarWinds SAM server. The SolarWinds SAM server uses the decimal separator set by its Microsoft Windows regional settings. You may need to log in with an administrator account to perform this action.

Statistic

The statistic for this component monitor is the value returned by the script.

Script Monitor Formatting

At least one message and statistic is required. The statistic must be a valid integer and be able to be converted to double, otherwise it is handled as Not as Number (NaN). There is no maximum length for the message; however, only alphanumeric characters and the underscore are allowed.

Field Descriptions

Description

This field provides a default description of the monitor. You have the ability to override the default description by adding to or replacing the text, which will then be automatically saved. The variable to access this field is ${UserDescription}.

Component Type

This describes the type of monitor you are using.

Enable Component

This option determines whether or not the component is enabled. Disabling this component leaves it in the application as deactivated and does not influence application availability or status.

Credential for Monitoring

Select a Windows credential that is both a user who can log on to the SolarWinds SAM server, and has sufficient rights on the target node (which may be the SAM server itself, depending upon your application) to do whatever the script needs to do. For example, if the script does something with WMI, the credentials also need WMI rights on the target node. If the credential you need is not already present in the credentials list, use the Quick Credentials section to add a new credential.

Script Engine

This field allows you to specify the scripting language to be used. The default value is vbscript. Below is a list of scripting engines that the Windows Script Host supports:

Name File Extensions Availability

VBScript

.vbs

Installed by default

JScript

.js

Installed by default

PerlScript

.pls

Freeware

ooRexxScript

.rxs

Freeware

PythonScript

.pys

Freeware

TclScript

.tcls

Freeware

ActivePHPScript

.phps

Freeware

RubyScript

.rbs

Freeware

Object Rexx engine

 

Commercial

Delphi scripting engine

 

Commercial

VBscript runs locally on the SAM server only. PowerShell uses WINRM that runs over TCP ports 5985 and 5986. All Linux, Unix, and Nagios script monitors use SSH over TCP Port 22. 

Roll-Up

This option allows you to choose how you would like the monitor to report the returned results based on the output provided by the script. With the ability to have multiple values returned, selecting how your scripts report back to you offers more flexibility. The default selection is “Show worst status."

Script

This field allows you to enter the script you want to run on the target node. To enter your script, click the Edit button that reveals the script editing window.

Script Arguments

This field is in the script editing window and allows you to specify arguments to pass to the script. You may include the variables ${IP}, ${USER}, and ${PASSWORD}, which are replaced respectively by the IP address of the target node, the credential user name, and the credential password.

Body

This field is in the script editing window and allows you to enter your script via typing or pasting.

User Notes

This field allows you to add notes for easy reference. You can access this field by using the variable, ${UserNotes}.

Create a Windows Script Monitor

You can create a Windows Script monitor to have SolarWinds SAM run a script using Windows Script Host. Windows Script Host comes with VBScript and Jscript, but can be extended with other scripting languages.

Scripts run on the SolarWinds SAM server and use the credentials you specify. The script must both return an exit code and output a text string containing a statistic value conforming to the specifications described later in this section.

Format the Statistic value to use the same decimal separator as the SolarWinds SAM server. The SolarWinds SAM server uses the decimal separator set by its Microsoft Windows regional settings. You may need to log in with an administrator account to perform this action.

Adapt an existing Visual Basic script to a Windows Script Monitor in a new template

  1. On the Web Console, click Settings > SAM Settings > Create a New Template, then name the template.
  2. Click Add Component Monitor, then expand the Custom Component Monitors group, and then check Windows Script Monitor.
  3. Click Submit, and then select credentials with the appropriate permissions to run the script on the SolarWinds SAM server, and that also has appropriate permissions to do whatever else the script requires.
  4. Copy the Visual Basic script into the Script Body field.
  5. Type any script arguments into the Script Arguments field.
  6. Specify the critical and warning thresholds, then click Submit.

Macros for Script Arguments

Specify script arguments in the Script Arguments field if needed. You can use the following variables as script arguments:

${IP}

This is replaced with the target node’s IP Address.

${USER}

This is replaced with the user name from the credential set.

${PASSWORD}

This is replaced with the password from the credential set.

Scripts Must Report Status Through Exit Codes

Scripts must report their status by exiting with the appropriate exit code.

To correctly create this component monitor, you must first return an exit code which results in an Up (0), Warning (2), or Critical (3) status. When one of these exit codes is received the appropriate dynamic evidence table structure is created and all further exit codes are handled correctly. If the component only returns Down (1) or Unknown (4) on first use, the appropriate dynamic evidence table structure is not created appropriately.

Exit Code Meaning

0

Up

1

Down

2

Warning

3

Critical

Any other value

Unknown, for example 4

For example, if you want to inform SolarWinds SAM that a VBScript reports Up status, you would exit the script using code similar to the following, where 0 reports Up: Wscript.quit(0)

Scripts with Text Output

Scripts report additional details by sending text to the script’s standard output. SAM supports multiple values returned by a script using the following format.

Statistic.Name1: xMessage.Name1: abc

Statistic.Name2: yMessage.Name2: abc

Detail Type Required Meaning

Statistic

Yes

A numeric value used to determine how the monitor compares to its set thresholds. This must be an integer value, (negative numbers are supported).

Statistic.Name1: 123Statistic.Name2: 456

Message

No

An error or information message to be displayed in the monitor status details. Note: Multi-line messages are supported. To use this functionality print each line using a separate command. For example:Message.Name1: abc
Message.Name2: def

There is a limit of ten Statistic and Message pairs for the script. These can be placed anywhere in the script output. The Statistic and Message names you give must contain valid letters and/or numbers.

Sample output:

# Script comment: This shows two pairs. Ten pairs are possible.
Statistic.CPU: 31.08Message.CPU: svchost.exe cpu usage
Statistic.RAM: 1234.56Message.RAM: svchost.exe ram usage

Example Scripts

Below is a sample vbscript that returns two values; the total number of files in a folder, and twice the total number of files in the same folder. The code that represents these two values are bold, To use this script, copy and paste the following code into the Script Body field. In the Scripts Arguments field, type in C:\Windows, or any other folder you want to monitor.

Option Explicit
On Error Resume Next
Dim lstArgs, path, fso, objDir, objFiles, objFiles2
Set lstArgs = WScript.Arguments
If lstArgs.Count = 1 Then
path = Trim( lstArgs( 0 ))
Else
WScript.Echo "Message: Usage: wscript.exe filelist.vbs [pathToFiles]" &vbCRLF &"[pathToFiles] Local or UNC Path"
WScript.Echo "Statistic: 0"
WScript.Echo "Message: Usage: wscript.exe filelist.vbs [pathToFiles]" &vbCRLF &"[pathToFiles] Local or UNC Path"
WScript.Echo "Statistic: 0"
WScript.Quit( 1 )
End If
Set fso = Wscript.CreateObject( "Scripting.FileSystemObject" )
If fso.FolderExists( path ) Then
Set objDir = fso.GetFolder( path )
If( IsEmpty( objDir ) = True ) Then
WScript.Echo "Message: Object Not Initialized"
WScript.Echo "Statistic: 0" WScript.Quit( 1 )
End If
Set objFiles = objDir.Files
If( IsEmpty( objFiles ) = true) Then
WScript.Echo "Message: Object Not Initialized"
WScript.Echo "Statistic: 0"
WScript.Quit( 1 )
End If
WScript.Echo "Message.Total: " & CInt( objFiles.Count ) & " files in this folder."
WScript.Echo "Statistic.Total: " & CInt( objFiles.Count )
WScript.Echo "Message.Twice: " & CInt( objFiles.Count*2 ) & " = twice the number of files in this folder."
WScript.Echo "Statistic.Twice: " & CInt( objFiles.Count*2 )
WScript.Quit( 0 )
Else
WScript.Echo( "Message: Folder Not Found" )
WScript.Echo "Statistic: 0"
WScript.Quit( 1 )
End If

There are several examples of Windows Script component monitors included in templates. These include: File Count, File Modified, LDAP Connection Monitor, Run 3rd Party Application, and Windows Event Log Count.

Sample scripts are installed on your SolarWinds SAM server, in the folder: C:\Program Files\SolarWinds\Orion\APM\SampleScriptMonitors\WindowsScripts

 
Last modified

Tags

Classifications

Public