Documentation forServer & Application Monitor

Best practices for SAM script monitors

As detailed in the SAM Custom Template Guide, script component monitors (also called "script monitors") offer limitless options for monitoring and returning metrics for target servers when used in SAM templates and application monitors. Each monitor has different options to execute scripts, add credentials, set working directories, and then generate and display returned values as output.

SAM's Component Monitor Library includes the following predefined script monitors, but you can also write your own.

Disclaimer: Scripts provided outside of the Orion Web Console are not supported under any SolarWinds support program or service. Scripts are provided AS IS without warranty of any kind. SolarWinds further disclaims all warranties including, without limitation, any implied warranties of merchantability or of fitness for a particular purpose. The risk arising out of the use or performance of the scripts and documentation stays with you. In no event shall SolarWinds or anyone else involved in the creation, production, or delivery of the scripts be liable for any damages whatsoever (including, without limitation, damages for loss of business profits, business interruption, loss of business information, or other pecuniary loss) arising out of the use of or inability to use the scripts or documentation.

Check credentials and server permissions for scripts

Verify you have the correct credentials with assigned account permissions to execute scripts on the Orion server and target servers. The script monitors may provide fields for credentials, or you may need to provide credentials in the script code, arguments, or command line. Test the script in SAM prior to verifying credentials and access. For details, see the SAM Custom Template Guide.

Test scripts before monitoring

When adding and configuring script component monitors, test scripts. When the test completes, SAM registers each returned metric as a numbered output in the Orion database. You can configure the display of collected metrics and values through the component monitor. Each script monitor supports up to 10 different outputs.

Confirm node status updates

Until tested, scripts and component monitors return an initial "Unknown" status. After testing, polling returns accurate application status.

Use code comments

Code comments help document the intent for code, decisions made, and to track changes. SolarWinds recommends using code comments to keep detailed steps and responses in your code. If additional administrators work in the script monitors, the comments provide context for the code.

# for a comment per line.
<#
For lengthy comments per code section.
#>

Do not use positional parametrization

In the command line for executing scripts, always add the parameter per value. Do not assume the position of data in the command dictates the parameter. For example, use -h for hostname.

Use a header for writing multiple scripts

Create a header in your code to reuse throughout your scripts. The header could include example code and code comments for:

  • A listed of exit codes.
  • Set variables for return metrics commonly used in your scripts.
  • Use code to determine if you are testing code on the Orion server or target server. For example, the following PowerShell code returns a message identifying if the server is a test system or the Orion server:

    Additionally, you could add a step to save the code to the Orion server if it's not already there.

Use macros

When using macros, consider assigning them to named variables in your scripts.

The following macros are available for Linux/Unix, Nagios, Windows Script, and PowerShell script monitors:

  • ${USER}
  • ${PASSWORD}
  • ${PORT}
  • ${Node.SysName}
  • ${Node.Caption}
  • ${Node.DNS} - Use this instead of ${IP}.
  • ${Node.ID}
  • ${Component.ID}
  • ${Component.Name}
  • ${Application.Id}
  • ${Application.Name}
  • ${Application.TemplateId
  • ${Threshold.Warning}
  • ${Threshold.Critical}
  • Node Custom Property Macros ${Node.CustomPropertyName}
  • Application Custom Property Macros ${Application.CustomPropertyName}

For agent monitored nodes, use the macros ${Node.SysName} and ${Node.DNS}. The ${IP} may return a loopback IP before polling starts.

Report status through exit codes

Scripts must report their status by exiting with the appropriate exit code. The exit code is used to report the status of the monitor, as displayed in the Orion Web Console.

A script should return an exit code which results in an Up (0), Warning (2), or Critical (3) status. When an exit code 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.

  • 0 - Up
  • 1 - Down
  • 2 - Warning
  • 3 - Critical
  • Any other value - Unknown, for example 4

Multiple options for returning exit code and message

You can return one of multiple options for exit codes and messages using IF/ELSE or case statements in scripts.

Use error trapping to capture issues

Using error trapping code such as try/catch blocks help capture and report errors, thus blocks providing more details about an issue.