Part 2: Custom Performance Objects in Runtime Scripts

Second installment in the System Center Forum Operations Manager 2007 Scripting Series

Author: Pete Zerger, MS MVP-Operations Manager

Version: 1.0 January 17, 2008

Some Rights Reserved: This and all works on System Center Forum are published under the Creative Commons Attribution-Noncommercial-Share Alike 3.0 license. You are free to use and reference this document for non-commercial use and it’s, so long as, when republishing you properly credit the author and provide a link back to the published source. See Creative Commons Attribution-Noncommercial-Share Alike 3.0 for full details

Table of Contents Introduction ................................................................................................................................ 3

The MOM 2005 Method ...................................................................................................... 3

The OpsMgr 2007 Method .................................................................................................. 3

Walkthrough of Script Updates .................................................................................................. 4

Download ............................................................................................................................ 7

Testing Your Script .................................................................................................................... 7

Using Your Script in a Rule in Operations Manager 2007 .......................................................... 9

Creating an Alert Rule ...............................................................................................................13

Enabling the Rule Using Overrides ...........................................................................................17

Enabling the File Size Check with Performance Collection Rule ............................................17

Enabling the Alert Rule ..........................................................................................................17

Create a Performance View ...................................................................................................18

Feedback ..................................................................................................................................19

Introduction In the first installment of our scripting series, we took our first steps into Operations Manager 2007,

updating a simple MOM 2005 script that logged events based on the presence and size of a file we

defined in a script parameter. If you have not yet read part 1, you can download the full article and

accompanying management pack HERE. Get the MP and sample code for part 2 HERE.

In part 2, we are going to add to the script we created in part 1 to log performance data tracking the size

of the file in a custom performance object. This data can then be viewed in a Performance View.

Let’s get down to business...

The way we create performance data in Operations Manager 2007 is different than MOM 2005, so before we update our script, I want to make a quick comparison of the old method versus the new method. I think you will find the OpsMgr 2007 method even easier than the same operation in MOM 2005.

The MOM 2005 Method In MOM 2005, we would collect our data just as we did in the file size script we edited in part 1, and use that numeric data with the ScriptContext.CreatePerfData method to create a custom performance object. Below is a basic subroutine I used in all my MOM 2005 scripts of this type. Sub CreatePerfData(strObjectName,strCounterName,strInstanceName,numValue)

Set objPerfData = ScriptContext.CreatePerfData

objPerfData.ObjectName = strObjectName

objPerfData.CounterName =strCounterName

objPerfData.InstanceName = strInstanceName

objPerfData.Value = numValue

ScriptContext.Submit objPerfData

End Sub

The OpsMgr 2007 Method In OpsMgr, the process can be performed in three short steps with less code than MOM 2005, using the

MOMScriptAPI.CreatePropertyBag method to create a PropertyBag object. As we mentioned last time,

the top level object for the Operations Manager 2007 is the MOMScriptAPI.

1. To create performance data in OpsMgr, we use the CreatePropertyBag method. This will create

a PropertyBag object.

2. We will then use the AddValue method of our PropertyBag object to add the file name and file

size to the PropertyBag.

3. Finally, we will use the ReturnItems method to close the PropertyBag and submit the data to the

Management Server.

MOMScriptAPI.CreateDiscoveryData Creates a new discovery data object, which stores discovery data and is used to submit the collected data back to the Management Server.

MOMScriptAPI.CreatePropertyBag Creates a new property bag object, which is used to temporarily store discovery data as a collection of name-value pairs.

MOMScriptAPI.LogScriptEvent Writes a message to the Operations Manager event log.

MOMScriptAPI.Return Submits the discovery and monitoring data back to the Management Server and ends the execution of the script.

Syntax:

1. Create the PropertyBag

Set propertyBag = objAPI.CreatePropertyBag()

2. Add name / value pair to the PropertyBag (the file name and file size in this case)

propertyBag.AddValue "targetName", FileName

propertyBag.AddValue "perfValue", FileSize

objAPI.AddItem(propertyBag)

3. Close the PropertyBag and submit to the management server

objAPI.ReturnItems

Walkthrough of Script Updates Again, the script we‟re working with today is the File Size Monitor script we updated in part 1. If you do not have it handy, do not worry, as I will provide a link to the download of our finished product along with the updated sample management pack. The script from part 1 monitors for file size over/under a threshold, as well as a missing file. In this installment, we‟re going to make a couple of very simple updates to log the file size data into a custom performance object. Then we will put this script into a rule and have a look at our new performance object in a Performance View. Again, my comments in each step will be in RED, and download links will be provided at the end of the tutorial. NOTES: MS Word will cause some line wrap in the sample, so better to use the final copy in the download link provided later in this document. We will add the propertyBag code to 3 places in the script, to log data in event of the 3 possible outcomes; 1) file does not exists (file size = 0) 2) file larger than threshold 3) file smaller than threshold

‘****************************************************************************

**********************************

‘Name: File Size Monitor Script with Performance Collection

‘Parameters: (Parameters are values we must supply to the script. Also called

arguments)

‘FileName (file name including path) and

‘FileSizeThreshold (file size in KB)

‘Version: 2.0

‘Author: Pete Zerger

‘Description:

‘This is the file size monitoring script for part 2 of the

‘System Center Forum Scripting Series. This file monitors for file

‘existence and file size and logs file size to a custom performance object.

‘Download the management pack and readme.rtf ‘document from

‘systemcenterforum.org/downloads

‘Download Part 2 of the scripting series at

‘http://www.systemcenterforum.org/scripting-series-part-1-updating-mom-2005-

runtime-scripts-for-opsmgr-and-sce/

‘Download Part 1 of the scripting series at

http://www.systemcenterforum.org/scripting-series-part-1-updating-mom-2005-

runtime-scripts-for-opsmgr-and-sce/

‘Download the updated MP (version 2.0) at

‘****************************************************************************

**********************************

Option Explicit

On Error Resume Next

‘Declare variables

Dim filesize, fs, file

Dim Filename, FileSizeThreshold

Dim objEvent, objParameters

Dim objAPI

„We are going to declare a new variable for the PropertyBag object

Dim propertyBag

‘Instantiate Opsmgr runtime scripting

Set objAPI = CreateObject("MOM.ScriptAPI")

‘Instantiate object for collecting values passed to the script

Set objParameters = WScript.Arguments

‘Create the propertyBag object

Set propertyBag = objAPI.CreatePropertyBag()

Const EVENT_TYPE_ERROR = 1

Const EVENT_TYPE_WARNING = 2

Const EVENT_TYPE_INFORMATION = 4

‘Assign target FileName from arguments.

‘The 0 indicates FileName is the first argument

FileName = objParameters(0)

‘Assign target FileSizeThreshold from arguments.

‘The 1 indicates FileSizeThreshold is the second argument

‘The int() function ensures the argument is interpreted as a number.

FileSizeThreshold = int(objParameters(1))

‘Instantiate WSH FileSystemObject.

‘This is used for retrieving values from the Windows file system.

Set fs=CreateObject("Scripting.FileSystemObject")

Set file=fs.GetFile(Filename)

‘Verify the file exists

If Err.Number > 0 Then

„Log a “file not found” error event

Call objAPI.LogScriptEvent("FileSizePerf.vbs ",4441,

EVENT_TYPE_ERROR ,"File " & FileName & " was not found.")

‘Add the file name and file size to the property bag

propertyBag.AddValue "targetName", FileName

propertyBag.AddValue "perfValue", 0

objAPI.AddItem(propertyBag)

‘Close the propertyBag and submit the data

objAPI.ReturnItems

ELSE

‘Determine file size (in KB)

Filesize = file.Size / 1024

‘If file exists, check file size and compare to

‘file size threshold provided.

IF filesize > FileSizeThreshold then

„If larger than threshold, log event

Call objAPI.LogScriptEvent("FileSizePerf.vbs ",4444,

EVENT_TYPE_ERROR ,"File " & FileName & " is " & filesize & _

" KB. This is larger than the error threshold of " & _

FileSizeThreshold & " KB.")

‘After checking file size, add the file name and file size values to the

‘property bag. We’ll map these values to a custom performance object in the

‘Console later.

‘Add the file name and file size to the property bag

propertyBag.AddValue "targetName", FileName

propertyBag.AddValue "perfValue", FileSize

objAPI.AddItem(propertyBag)

‘Close the propertyBag and submit the data

objAPI.ReturnItems

ELSE

„Else, if file is smaller than threshold, log event.

Call objAPI.LogScriptEvent("FileSizePerf.vbs ",4445,

EVENT_TYPE_INFORMATION ,"File size for " & FileName & _

" is below the error threshold of " & FileSizeThreshold & _

" KB. File size is " & filesize & " KB.")

‘Add the file name and file size values to the ‘property bag. We’ll map these

values to a custom performance object in the ‘Console later.

‘Add the file name and file size to the property bag

propertyBag.AddValue "targetName", FileName

propertyBag.AddValue "perfValue", filesize

objAPI.AddItem(propertyBag)

‘Close the propertyBag and submit the data

objAPI.ReturnItems

End If

End if

‘**************END SCRIPT********************

Download You can download a copy a clean copy of the finished product (FileSize_Sample.txt) and the completed management pack containing all Part 2 material on the SystemCenterForum.org website HERE.

Testing Your Script Okay, that‟s it. We‟re ready to test our script. If you want to test your script before you can run this script on any machine with an agent or the Operations Console installed (you need the Operations Manager Event Log for this test). Type the following on the command line on the target machine you wish to monitor. Replace the file name and path and file size with the values applicable to your environment (Make sure to add the cscript in front of the script name).

You will immediately see the propertyBag output containing the performance data returned to your screen. Then, check the Operations Manager Event Log for the event output as in the original script. Results should look like one of the following. Play with the values you pass the script to create one of each of the following conditions to make sure your script behaves as expected. Later, we‟ll create rules to raise alerts on these events.

File not found (error)

File size exceeds threshold (error)

File size below threshold (information)

Using Your Script in a Rule in Operations Manager 2007 Now we will use this script in a simple rule in Operations Manager 2007. In the Operations Console.

1. In the Authoring space of your Operations Console, expand Management Pack Objects and browse to Rules.

2. Right-click Rules and select New Rule. Browse to Collection Rules Probe-based Script (Performance)

3. Select SCF Scripting Series MP (created in part 1) from the „Select destination management pack‟ dropdown. If you have not already created a custom management pack to store the rules we create, do so now by clicking the New button next to the dropdown.

4. Type a name for your rule. Uncheck the „Rule is enabled‟ checkbox. Target the rule to the Windows Server 2003 Operating System. BEST PRACTICE: It is best practice to create custom rules and monitors in a disabled state and use overrides to selectively enable for select monitored entities or groups of monitored entities.

5. Set the desired recurring schedule. Be sure not to set this value too low or you may impact normal function of the systems for which the rule is enabled.

6. Now we‟re ready to paste our script into the rule. On the Script screen in the File Name window,

entering a meaningful name for your script. TIP: Give your scripts distinct, recognizable names. If the script fails, any error will likely be logged to the Operations Manager Event Log containing the name of the script.

7. Next, click the Parameters button. Here we‟ll enter the same parameters we did when testing our

script on the command line. Click OK NOTE: Entering parameters is a bit different than in MOM 2005. Individual script parameters are separated by spaces. If your file path\name has spaces in it, enclose it in quotes.

8. On the Performance Mapper screen, edit the values to appear as pictured below. You will notice

that the name defined in Instance and Value are set to the values in the script, but the Object and Counter values are user-defined.

9. Click Create and the rule is created. Now we will create rule(s) to generate alerts for the events logged by the script.

Creating an Alert Rule Remember that the script in the rule we created above simply generates an event in the Operations

Manager Event Log. If we wish to raise an alert in the event that the file is larger than the threshold, we

need to create an alert rule.

1. In the Authoring space of your Operations Console, expand Management Pack Objects and browse to Rules.

2. Right-click Rules and select New Rule. Browse to Event Based NT Event Log (Alert). 3. Select our custom management pack in the „Select destination management pack‟ dropdown.

4. On the Rule Name and Description enter a rule and

5. The Operations Manager Event Log where the events will be generated.

6. On Build Event Expression screen, we will build the alert criteria. The events generated by the

script are of source Health Service Script. The Event IDs are 4441, 4444, or 4445. We can create a separate alert rule for each event desired, specifying the desired Event ID in each rule.

7. On the Configure Alerts screen, we can enter the alert name, priority and severity.

8. If we click the Alert Suppression button, we can set criteria for suppressing duplicate alerts. In this

example, we will set Event Source, Logging Computer, and Full Event Number.

9. Click Create. The alert rule is now created.

Enabling the Rule Using Overrides Since we followed best practices in creating the rules in a disabled state, we will need to enable both the

Timed Event Rule and NT Event Log (Alert) rules for the target computer(s). To enable the rule for the

computer or group or computers of your choice, you will need to create an override.

WARNING: If the rule you created in part 1 (rule name “SCF File Size Check”) is already running in a production environment, make sure you disable that rule by removing the overrides you created. Otherwise, you‟ll have the same events being generated by two scripts for that computer. You can still use it for machines for which you do not wish to collect performance data.

Enabling the File Size Check with Performance Collection Rule 1. Begin by finding the rule you created in the Authoring pane in Rules. 2. Right click the rule and select Overrides Override the Rule For a specific object of type. 3. Select the server for which you wish to enable the rule. 4. Check the box next to Enabled and set the value to True.

5. Check the box next to Parameters and set the file path\name and the file size (in KB) to the

values of your choice. Remember to use quotes if your file path\name contains spaces. 6. Click OK. The changes will be sent to the agent-managed machines for which you enabled the

rule momentarily.

Enabling the Alert Rule 1. Begin by finding the rule you created in the Authoring pane in Rules. 2. Right click the rule and select Overrides Override the Rule For a specific object of type. 3. Select the same server you chose previously to enable the rule. 4. Check the box next to Enabled and set the value to True.

Create a Performance View Next, we will create a Performance View for viewing our file size data. With this view, performance data

for any computer to which you apply this rule will be available for selection

1. Browse to the SCF Scripting Series MP folder in the Performance pane. 2. Right click and select New Performance View 3. Name the view “File Size Tracking” 4. On the Criteria tab, select with a specific object name. 5. Click the link in the Criteria description.. window and type “File Size Tracking”.

The resulting Performance View should appear as follows:

You should now see both an Alert View and Performance View for the SCF Scripting Series MP.

You should now have the following rules in the Management Pack

Feedback Send feedback and errata to administrator@systemcenterforum.org