References > Component Monitor Types > Creating a Windows Script monitor

Windows Script monitor

This component monitor runs a Windows script on the SolarWinds SAM server and then processes the script's exit code and text output. This monitor has the ability to return up to ten pairs, i.e.: 10 statistic values + 10 [optional] messages. This is best used in conjunction with the Multiple Statistic Chart. To create this monitor, see Create a Windows Script Monitor.

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.

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 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.

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. 

Script Body

This field is in the script editing window and allows you to enter your script via typing or pasting.To enter your script, click the Edit button that reveals the script editing window.

Status 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."

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
  • 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