Getting Started With PoShMon - HiltonGiesenow/PoShMon GitHub Wiki

Thanks for choosing to try PoShMon as your monitoring solution! This guide will help you get it installed and to get started with your first monitoring run.

Installation Instructions

PoShMon can be run from a server or even directly from your workstation, but you first need to make sure that the PowerShell module is installed on the machine in question. PoShMon is available on the PowerShell Gallery so you can install it directly from the gallery onto your local workstation or server using:

PS> Install-Module -Name PoShMon

You only need to install it to one location, not to every environment you want to monitor (remember, it's 'agent-less'). For instance, if you have a SharePoint farm with 4 servers that has a SQL Server cluster with 2 servers, you'd only need to run this command once - on whatever server you want to do the monitoring from. This could even be your main workstation - it doesn't need to be an actual server.

Loading the PoShMon Module

After installing the module, it should be loaded from the PowerShell modules folder automatically every time you start PowerShell or the PowerShell ISE. However, because you've just installed it, you might need to import the module explicitly this first time into your running PowerShell session. You can do this by running:

PS> Import-Module -Name PoShMon

As an alternative, if you want to run the latest checked-in version of the code directly from GitHub, you can Clone or download this GitHub repo to get the latest copy, but you'll need to run the Import-Module command after that, pointing to the downloaded PoShMon.psd1 file.

Running Your First Monitoring Task

Once you've installed the module, you can immediately run a monitoring task with just one command:

PS> Invoke-OSMonitoring -PoShMonConfiguration (New-PoShMonConfiguration {})

(Note all the braces - these are all required for now).

This will perform a basic "operating system"-level monitoring operation on the local machine, be it a server or workstation, to monitor things like hard drive space, memory, cpu, and so on. It will return an output to the console similar to the following:

Name                           Value
----                           -----
NoIssuesFound                  True
OutputHeaders                  {EventID, InstanceCount, Source, User...}
ElapsedTime                    00:00:00.1604451
SectionHeader                  Critical Event Log Issues
OutputValues                   {System.Collections.Hashtable}
NoIssuesFound                  True
OutputHeaders                  {ServerName, CPULoad}
ElapsedTime                    00:00:01.0033737
SectionHeader                  Server CPU Load Review
OutputValues                   {System.Collections.Hashtable}
NoIssuesFound                  True
...

As a first step, have a look at the SectionHeader values and the NoIssuesFound entries. These tell you what output has been returned from your monitoring (the "Sections" and whether there where any issues found within them, i.e. if those respective sessions have anything to report. However, you might want to inspect the output a little more, so perhaps return the monitoring run into a variable that you can then inspect or work with. That might look something like this:

PS> $monitoringOutput = Invoke-OSMonitoring -PoShMonConfiguration (New-PoShMonConfiguration { OperatingSystem -CPULoadThresholdPercent 5 })

If any issues are found in the run, they will be reported in the console output. For instance, if we modify the earlier monitoring command, and tell it to report CPU usage above 5% as problematic, it will give us a warning if this occurs. The following command will achieve this:

PS> Invoke-OSMonitoring -PoShMonConfiguration (New-PoShMonConfiguration { OperatingSystem -CPULoadThresholdPercent 5 })

The above command might now start to report 'high' CPU usage to the console, as follows: WARNING: CPU Load (27%) is above variance threshold (5%)

Note that we've also introduced some operating-system specific configuration options in the above example, in the form of the OperatingSystem parameter, where we've asked to be alerted if the CPU usage is above a specific threshold percent, in this case 5%.

We might also want to see more explicitly what PoShMon is actually doing. To do so, simply add the Verbose switch to the earlier command, as follows:

PS> Invoke-OSMonitoring -PoShMonConfiguration (New-PoShMonConfiguration { OperatingSystem -CPULoadThresholdPercent 5 }) -Verbose

Now you'd see output similar to:

VERBOSE: Initiating 'Critical Event Log Issues' Test...
VERBOSE: 	MyMachine
VERBOSE: 		No Entries Found In Time Specified
VERBOSE: Complete 'Critical Event Log Issues' Test, Issues Found: No
VERBOSE: Initiating 'Server CPU Load Review' Test...
VERBOSE: 	localhost: 29%
WARNING: 	CPU Load (29%) is above variance threshold (5%)
VERBOSE: Complete 'Server CPU Load Review' Test, Issues Found: Yes
VERBOSE: Initiating 'Memory Review' Test...
VERBOSE: 	MyMachine : 7.88 : 2.51
VERBOSE: Complete 'Memory Review' Test, Issues Found: No
...

Note that the same Warning line appears inside there, but this time it's in context with all the tests being run. Each test will report that it's starting and ending, as well as providing information about what it discovers. This is aside from any errors or warnings actually identified.

That's it for this Quick Start. The next step is look at creating a more complex configuration and once that's done you can choose from one of the specific topics below.