Best practices for SAM script monitors
Script component monitors (also called "script monitors") offer limitless options for monitoring and returning metrics for target servers when used in SAM application monitor 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:
To learn about modifying script monitors, or how to write your own scripts, see the SAM Custom Application Monitor Template Guide.
Disclaimer: Scripts provided outside of the SolarWinds Platform 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.
Your organization should internally review and assess to what extent PowerShell is incorporated into your environment. This is especially important when importing scripts from third parties, including content posted by other customers in the SolarWinds online IT community, THWACK. For details, see Use PowerShell in SAM.
Check credentials and server permissions for scripts
Verify that credentials have permission to execute scripts on the SolarWinds Platform server and target servers. 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 Application Monitor Template Guide.
Test scripts before monitoring
When adding and configuring script component monitors, test scripts before using them. When the test completes, SAM registers each returned metric as a numbered output in the SolarWinds Platform 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
Add comments to describe how the script works and 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 list of exit codes.
- Set variables for return metrics commonly used in your scripts.
-
Use code to determine if you are testing code on the SolarWinds Platform server or target server. For example, the following PowerShell code returns a message identifying if the server is a test system or the SolarWinds Platform server:
Additionally, you could add a step to save the code to the SolarWinds Platform server if it's not already there.
Use macros
When using macros, consider assigning them to named variables in your scripts.
In some languages, you need to surround the macro with quotation marks (for example, “${Node.Caption}”).
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.Custom.CustomPropertyName} - Application Custom Property Macros
${Application.Custom.CustomPropertyName}
For nodes monitored by SolarWinds Platform agents, 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, which determines how the status of the monitor appears in the SolarWinds Platform 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, a dynamic evidence table structure is created to support all further exit codes. 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 to return 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.
Performance enhancement tips
Modify the polling frequency
Depending on the length of calls and amount of data pulled for a monitor, you may want to modify the frequency. For script monitors you may need to only run the script once per day or once per week. For example, to compare MIBs using the SolarWinds MIB Database template, you may only need to run the comparison once a day or week.
Extend the polling timeout for long calls
For scripts with lengthy calls for large amounts of data, extend the polling timeout. The default 300 seconds may not be long enough to process scripts. If the call may take longer, especially during peak times, increase the timeout. For example, for MIB database comparison scripts using the SolarWinds MIB Database template, multiple files are called, downloaded, and compared to return status messages and complete specific actions.
Enhance latency and performance by pulling multiple metrics per template
When executing script component monitors in a template, SAM affects performance and latency making calls to a target server. Complete calls for up to 10 metrics per script to reduce the number of calls, increasing performance. Depending on the size and processing of scripts, balance scripts and lengthy calls across multiple instances of a script monitor.