NOT RELEASED YET!

In beta - see this post

Wolfpack.Contrib.Checks.Powershell

This package provides a HealthCheck that will execute a Powershell script. This plugin also provides some additional objects (in a dedicated .Net v2.0 assembly) for use in your scripts - these can be used to make Wolfpack generate alerts.

The Wolfpack.Contrib.Checks.Powershell.Scripting.dll assembly contains objects that are almost identical to core objects used within Wolfpack for alerting. The reason for "cloning" these objects into another assembly is twofold...
  1. .Net framework version compatibility. Powershell v2, by default loads the v2.0 .Net framework. Wolfpack targets .Net v4.0 which leads to "BadImage" exceptions when you try to load a v4.0 Wolfpack assembly in your powershell script. It is easy to fix this by tweaking the Powershell.exe.config file to support the v4.0 runtime but this is another "configuration" step and I hate configuration - by making a dedicated v2.0 Wolfpack assembly "it just works", no additional configuration required...good!
  2. Fluent interfaces....the data structures in core Wolfpack provide helper property setter methods that are fluent so they can be chained together - in a powershell script this causes problems as a call to a fluent method results in a return object being emitted into the script/pipeline result set....bad!
Wolfpack inspects all result objects returned from the script pipeline and will take action when specific object types are returned; see below for details on what object types is understands.

Install

Download the latest Wolfpack from codeplex...then you download & install this plug-in at a command line prompt in the Wolfpack installation folder with...
wolfpack.agent.exe /update:Wolfpack.Contrib.Checks.Powershell
Files installed...
  • \Wolfpack.Contrib.Checks.Powershell.dll - contains the HealthCheck components and supporting Powershell helpers.
  • \Wolfpack.Contrib.Checks.Powershell.Scripting.dll - a .Net v2.0 assembly that contains objects your script can return to Wolfpack to enable it to raise alerts.
  • \Omu.ValueInjecter.dll - used internally by the HealthCheck to convert objects returned from the script.
  • \Config\Checks\powershell.contrib.castle.config
  • \Powershell\WolfpackDemo1.ps1 - a sample script to demonstrate how you can return an object to get Wolfpack to raise an alert.

NOTE ON POWERSHELL CONFIGURATION
You will need to enable your powershell installation for script execution (more details on technet here).

#enable scripts with...
set-executionpolicy remotesigned

RunPowershellScript

This check will execute a powershell script....

Configuration

1. Move the powershell.contrib.castle.config file to one of the appropriate schedule subfolders of \Config\Checks...eg: \Config\Checks\EveryMinute. This will automagically bind this check to run "EveryMinute". You can create more subfolders, the only caveat is that they must correspond to a component named the same in the schedule.castle.config file.

2. To enable the check just set the "enabled" element value to "true".

3. Set a default NotificationMode - the docs for this common setting are here. This allows you to control the publication of an alert (should your script return them). This value will be used if any alerts you create in your script do not explicitly set this value. The default is to publish all alerts. So if you set this value to "SuccessOnly" and you did not set this property on the PSHealthCheckData object created in your script then the mode would be "SuccessOnly"; if you set this to "FailureOnly" on the PSHealthCheckData object then the "SuccessOnly" value would be not be used/ignored.

4. Set the name of the script in the "Script" element. This can be relative to the wolfpack root folder or a fully qualified filepath.

5. If you need to pass arguments to your script then create additional entry elements (like the one commented out) - just set the name and value of the arg and it will be available in the script. A good overview of Powershell parameters can be found here.

6. If you use Powershell SnapIns then use this list to register them for your script to use. Internally Wolfpack will call Add-PSSnapIn to make an already registered SnapIn available for use in the session/script.

<component id="RunPowershellScript"
			 lifestyle="singleton"
			 type="Wolfpack.Contrib.Checks.Powershell.RunPowershellScript, Wolfpack.Contrib.Checks.Powershell">
	<parameters>
		<friendlyName>RunPowershellScriptDemo</friendlyName>
		<enabled>false</enabled>
		<description>Runs a powershell command</description>
		<!-- See http://wolfpack.codeplex.com/wikipage?title=Notification%20Modes for details on NotificationModes. Use this to provide a default mode for any alerts that your script generates and does not explicitly set this value. -->
 		<NotificationMode></NotificationMode>
		<!-- The powershell script to execute -->
		<Script>.\Powershell\WolfpackDemo1.ps1</Script>
		<!-- pass any parameters to the script here -->
		<Parameters>
			<dictionary>
				<!-- example param
				<entry key="name">Value</entry>-->
			</dictionary>
		</Parameters>
		<SnapIns>
			<list>
				<!-- add more snapins here with new item lines
				<item>TODO: ADD SNAPIN NAME HERE</item>
				<item>TODO: ANOTHER SNAPIN NAME HERE</item>
				-->
			</list>          
		</SnapIns>
	</parameters>
</component>

Usage

Using the demo powershell script "WolfpackDemo1.ps1" installed in the \Powershell folder provided let's walk through how this plugin works to get an idea of how you can use this plugin in your monitoring set up.

Add-Type -Path .\Wolfpack.Contrib.Checks.Powershell.Scripting.dll

$hc = new-object -typename Wolfpack.Contrib.Checks.Powershell.Scripting.PSHealthCheckData
$hc.AddProperty("Wolfpack", "Is Awesome!")

# SetIdentity is optional - if you don't set this it will assume 
# the identity setup for the HealthCheck that runs this script
$hc.SetIdentity("MyFirstPowershellAlert", "{406C666B-FD00-4DE9-8A6C-B835FD0FFF82}", "This is my first Wolfpack Powershell Alert")
$hc.Result = $true
$hc.ResultCount = 42
return $hc

This script first adds a reference to the assembly that contains the special Wolfpack objects. This assembly, Wolfpack.Contrib.Checks.Powershell.Scripting.dll contains the custom Wolfpack objects that you can use in your script.

Next it creates an instance of "Wolfpack.Contrib.Checks.Powershell.Scripting.PSHealthCheckData" - this is a supported result object type - the plugin knows what to do with one of these objects should it be returned as a pipeline result.

Next we set properties or call methods on the $hc instance and finally we return this as a result from the pipeline; end of script.

Under the hood..

The plugin will receive the script/pipeline results (as a Collection<PSObject>). It enumerates through these objects and inspects each one - if it is of a type it understands it will take some type specific action. If your script does not return any results or the type is not known/supported then Wolfpack will do nothing.

PSObject Result types supported are...
  • System.Management.Automation.ErrorRecord - if the pipeline fails the result BaseObject will be an ErrorRecord. Wolfpack will extract the error information and publish a CriticalFailure alert in response so you are always informed when things go wrong (this is standard Wolfpack behaviour).
  • Wolfpack.Contrib.Checks.Powershell.Scripting.dll contains these objects...
    • PSHealthCheckData - this is equivalent to the core HealthCheckData structure that Wolfpack uses for alerts - its fields are mapped onto a regular HealthCheckData structure and then Wolfpack will publish it; this effectively allows your script to publish an alert, it even supports multiple alerts if the pipeline results contains them.

Additional Tasks

You can create as many independent instances of this HealthCheck as required - each can run on it's own schedule, execute a different script or have different parameters. To do this...
  1. Copy & rename the \Config\Checks\powershell.contrib.castle.config file
  2. Move the new file to the appropriate \Config\Checks\Schedule folder. Remember that the name of the Schedule folder must correspond to a component entry in the \Config\schedule.castle.config file.
  3. Update the configuration in the new config file...
    1. You must create an new unique value for both the component id attribute
    2. You must create an new unique value for friendlyName element
    3. Update the remaining elements as required (Script, Parameters etc)
<!-- TODO: Update the id attribute -->
<component id="RunPowershellScript<-CHANGEME!"
			 lifestyle="singleton"
			 type="Wolfpack.Contrib.Checks.Powershell.RunPowershellScript, Wolfpack.Contrib.Checks.Powershell">
	<parameters>
                <!-- TODO: Update the friendly name-->
		<friendlyName>RunPowershellScriptDemo<-CHANGEME!</friendlyName>

Last edited Jul 19, 2012 at 11:19 AM by jimbobdog, version 21

Comments

No comments yet.