In part 2 of this series, we discussed utilizing PowerShell with SAM templates and component monitors for monitoring your servers and applications. In this installment, we'll discuss the basics of PowerShell code and provide examples that you can use and modify for your monitoring environment.


PowerShell Code with SAM

 

Let's say we have a SAM template made up of various Exchange monitors to report email flow. The monitor we will use in this example is called, "Number of items received by specific user during last month." This monitor, when configured correctly, will simply report the number of emails a specific user received during the last month.

 

To edit the default script for this monitor, click the Edit button for that monitor within SAM. Below is the default PowerShell script for this component monitor. If you don't know anything about code, this will look a little scary. Don't panic. We'll cover what's going on here.

 

$ErrorActionPreference = "silentlycontinue";
add-pssnapin Microsoft.Exchange.Management.PowerShell.E2010;
add-pssnapin Microsoft.Exchange.Management.PowerShell.Admin;
$address = $args.get(0);
$server = $args.get(1);
$Error.Clear();
if ( !$address )
{
Write-Host "Message: Can't find "user_mailbox" argument. Check documentation.";
exit 1;
}
if ( !$server )
{
Write-Host "Message: Can't find "server" argument. Check documentation.";
exit 1;
}
$t1 = Get-Date;
$t2 = $t1.AddMonths(-1);
$stat = (Get-MessageTrackingLog -Server $server -Recipients $address -EventID "Receive" -ResultSize "Unlimited" -Start $t2 -End $t1 | Measure-Object).Count;
if ($Error.Count -eq 0) {
Write-Host "Message: User $address received: $stat items during last month";
Write-Host "Statistic: $stat";
Exit 0;
}
Write-Host "Message: $($Error[0])";
Exit 1;

 

Variables

 

Variables are used for storing information, much like the X in a simple algebraic equation. For example, X + 5 = 12. The variable X, in this case, represents, or stores, the number 7. As the name implies, variables change depending upon what they're asked to do. If the previous equation changes to X + 5 = 14, then the variable X becomes 9. In programming, variables represent more than simple numbers. They can store and represent just about anything, including text strings, times, email addresses, and so on. In SAM, variables are prefixed with "$", as highlighted below. The following code snippet from the above PowerShell code calculates a numerical value (number of emails received per month) and then stores it in the variable named $stat (short for statistic).

c1.png

Using the code snippet above, the $stat variable's value is reported to SAM as 9356, as highlighted in the Statistic column's output below:

c2.png

Let's look at the variables and see how they relate to the output SAM displays. The variables and the values they store are highlighted below in both the code and the output, respectively. Notice the variables change to show the actual values they store, be it a number or email address, when they are output to SAM's web console. The variable $stat reports 9356 in two places while the variable $address reports the email address.

c3.png

c4.png

Text and variables in code within quotes indicate information that is visible to the user. When made visible, the text will be displayed as it is written in the code. Variables will be replaced with the values they store, as demonstrated above. With these same lines of code, Message: and Statistic: refer to the columns where the information will be placed. So, the code highlighted below displays what you now see above.
c5.png

Let's examine the first two lines of code above.

  • Message: is within the quotes, therefore it is displayed in the output as the column header.
  • User $address received: $stat items during the last month is also within quotes and to the right of Message: therefore, the text of the message and the values of the variables are displayed in the Message column, also shown above..

 

Scripts Must 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, which is seen by the user through the interface. The following table explains the exit codes and their values:

 

 

Exit Code

Meaning

0

Up

1

Down

2

Warning

3

Critical

Any other value

Unknown

 

The following code snippet highlights proper usage of exit codes.

c6.png

The two exit codes in this example are conditional, meaning either one or the other will be triggered based on a certain outcome. When Exit 0; (status of Up) is reported, the message and statistic are displayed and the monitor shows a status of Up. When Exit 1; (status of Down) is reported, the message and statistic are not displayed and a status of Down is reported.

 

If you want to inform SolarWinds SAM that a PowerShell script reports an Up status, you would exit the script using Exit 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. There is a limit of 10 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.

 

Note: Each statistic and message output pair of your script requires a unique identifier. A maximum of 10 output pairs can be monitored per script.

 

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

  1. Statistic.Name1: 123
  2. Statistic.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

 

For more information, refer to the following:

"Creating a Windows PowerShell Monitor".

For more information about Windows PowerShell, visit: http://technet.microsoft.com/en-us/library/bb978526.aspx.

For a complete list of available PowerShell cmdlets, visit: http://technet.microsoft.com/en-us/library/ee692945.aspx