Reading/Collecting Events created from script with the LogScriptEvent API

[System-Center-Team]

First published on TECHNET on Apr 23, 2008

Overview

A lot of scripts have need to create events which are external to the normal function of the script.  This is a technique which is typically used for tracing, it is not recommended to release scripts which expose traces in this way as there is considerable overhead in writing and consequently reading these events from OpsMgr, however given some throttling mechanism (overrides for instance) it is an effective means of producing traces which can easily be collected from the OpsMgr UI.  These events also in some cases indicate errors to other workflows which can consume them.  For instance if a script is using a service to collect discovery data and that service is unavailable the script can drop an event which sets the state of the service to such.

The short version

Use MOMScript.LogScriptEvent API to generate an event from script, use a unique Script Name parameter and a different Event Number to indicate different errors.  See ‘Creating events from Script’ section below for more details.

Use WindowsLibrary!Microsoft.Windows.ScriptGenerated.EventProvider to read events generated from script.  Provide the same Script Name and Event Number values as used in the LogScriptEvent API call to generate the event.  See ‘Reading these events created from Script’ for more details.

See ‘Script.Composite.Functions.xml’ sample MP (attached) for an example MP.

Creating events from Script

To create events from Script is a relatively easy task, using the LogScriptEvent API defined on the MOMScriptAPI object.  This API takes the following Parameters:

Script Name	The string provided here uniquely identifies your script for the purposes of your event (think event source).  This is important as this string should also be used to read your event(s) created by your script (more on this later)
Event Number	The integer value here should be in the range 1-20000.  This value is also important as it should indicate the reason for the event to the collection rule (555 = service not running, 9000 = unknown error, etc…).
Severity	Severity is an integer value which indicates why the event is raised: 0 Success event 1 Error event 2 Warning event 4 Information event
Description	This is a string value which indicates what the problem or trace is in a human readable format.

To call this from VBScript:

const EventSeverityError =    1

const ServiceUnavailable =    555

dim oAPI

set oAPI = CreateObject("MOM.ScriptAPI")

call oAPI.LogScriptEvent("My Unique VbScript", ServiceUnavailable, EventSeverityError, "The service was unavailable")

To call this from Jscript:

const EventSeverityError =    1;

const ServiceUnavailable =    555;

var oAPI;

oAPI = new ActiveXObject("MOM.ScriptAPI");

oAPI.LogScriptEvent("My Unique JScript", ServiceUnavailable, EventSeverityError, "The service was unavailable");

See ‘Script.Composite.Functions.xml’ sample MP (attached) for an example MP.

Reading these events created from Script

A little known fact is that reading the events created with this API is also a relatively simple task.  For reference you should know that these events are written to the “Operations Manager” event log using the source “Health Service Script” however knowing this is not necessary to read these events.  There is a specific composite module which is capable of reading these events given the same “Script Name” and optionally the “Event Number” field provided to the LogScriptAPI.  This module is defined in the WindowsLibrary MP, it is called “Microsoft.Windows.ScriptGenerated.EventProvider”.  It takes three pieces of information:

ComputerName	This is the name of the computer on which you want to read these events.  Typically this should be set to something like $Target/…/Property[Type="Windows!Microsoft.Windows.Computer"]/PrincipalName$.
ScriptName	This is the unique name of the script provided to as the “Script Name” parameter to the LogScriptEvent API.
EventNumber	This is optional, if provided it should be the Event Number which was provided as the “Event Number” parameter to the LogScriptEvent API.  If not provided the module will read all event numbers from the provided script name.

To read the specific event (555) generated from the VBScript sample above you can use a rule like the following: