Share via

How to Use Monitoring Data in a Management Pack

  • Article

Applies To: Operations Manager 2007 R2, Operations Manager 2007 SP1, System Center Operations Manager 2007

After creating a custom runtime script to collect monitoring data, you must add the script to a Management Pack. You can add a script to any of the following Management Pack elements:

  • A data source module type—Adding a script to a data source module type allows you to define configuration overrides and reuse the script in different monitoring objects that are defined in the Management Pack.

  • A monitor (or monitor type), a rule, or a task—Adding a script to a specific monitor, rule, or task allows you to use the script only for that monitoring object.

A Management Pack that uses script-based monitoring data must also contain an element that maps the collected data to one of the following data types for storage in the Operations Manager database:

  • Discovery

  • Event

  • Performance

  • Alert

This data mapping can be performed by a data source module that includes a mapping component or by a specific monitoring object that uses a write action.

Example

The following examples show how to add a script to a Management Pack by editing the Management Pack's XML file. For information about how to add a script to a Management Pack by using the Operations Console, see the Operations Manager 2007 Help.

Example 1—Defining a Monitor That Runs a Script

In this example, a Management Pack creates a monitor that runs a custom script at regular intervals. The script iterates through the files in a given directory and adds each file's name and size to a property bag that is stored in the Operations Manager database. The monitor indicates whether any file's size exceeds a specified threshold.

To create the monitor, the example Management Pack creates the following elements:

  • A new data source module type, which contains the script.

  • A custom monitoring type, which uses a module of the new type as its data source.

  • A monitor of the custom monitoring type, which runs the script at regular intervals.

The example Management Pack first creates the following data source module, of type Microsoft.Demo.Scripting.AppYComponent.FileSizeProvider, a custom type. For more information about the script used in this example, see How to Create Monitoring Data by Using a Script.

<DataSourceModuleType ID="Microsoft.Demo.Scripting.AppYComponent.FileSizeProvider" Accessibility="Internal">
  <Configuration>
    <xsd:element name="IntervalSeconds" type="xsd:integer"/>
    <xsd:element name="Path" type="xsd:string"/>
    <xsd:element name="FileName" type="xsd:string"/>
  </Configuration>
  <OverrideableParameters>
    <OverrideableParameter ID="IntervalSeconds" ParameterType="int" Selector="$Config/IntervalSeconds$"/>
  </OverrideableParameters>
  <ModuleImplementation>
    <Composite>
      <MemberModules>
        <DataSource ID="DS" TypeID="Windows!Microsoft.Windows.TimedScript.PerformanceProvider">
          <IntervalSeconds>60</IntervalSeconds>
          <ScriptName>CollectAppYComponentFileSize.vbs</ScriptName>
          <Arguments>$Config/Path$</Arguments>
          <ScriptBody>
            <![CDATA[
Option Explicit

Dim oAPI
Set oAPI = CreateObject("MOM.ScriptAPI")

' Check for the required script arguments.
Dim oArgs
Set oArgs = WScript.Arguments
if oArgs.Count < 1 Then
    ' If the script is called without the required arguments,
    ' create an information event, and then quit. 
    Call oAPI.LogScriptEvent("CollectAppYComponentFileSize.vbs",101,0, _
        "CollectAppYComponentFileSize script was called without any " _
        & "arguments and was not executed. ")
    Wscript.Quit -1
End If

Dim sPath
sPath = oArgs(0) ' The path of the directory containing the files.

Dim oFso, oFile, oFolder, oBag, oSize
Set oFso = CreateObject("Scripting.FileSystemObject")

if (oFso.FolderExists(sPath)) Then
    Set oBag = oAPI.CreatePropertyBag()
    Set oFolder = oFso.GetFolder(sPath)
    For Each oFile in oFolder.Files
        oSize = oFile.Size/1024
        Call oBag.AddValue(oFile.Name, oSize)
    Next
    Call oAPI.Return(oBag)
End If
]]>
                    </ScriptBody>
                    <TimeoutSeconds>20</TimeoutSeconds>
                    ' The module uses the following elements to map 
                    ' values in the property bag to performance data 
                    ' stored in the Operations Manager database.
                    <ObjectName>AppY</ObjectName>
                    <CounterName>File Size</CounterName>
          <InstanceName>$Target/Property[Type='System!System.Entity']/DisplayName$</InstanceName>
                    <Value>$Data/$Config/FileName$$</Value>
                </DataSource>
            </MemberModules>
            <Composition>
                <Node ID="DS"/>
            </Composition>
        </Composite>
    </ModuleImplementation>
    <OutputType>SystemPerf!System.Performance.Data</OutputType>
</DataSourceModuleType>

The custom module type is based on the Microsoft.Windows.TimedScript.PerformanceProvider module type defined in the Microsoft.Windows.Library Management Pack. The Microsoft.Windows.TimedScript.PerformanceProvider accepts the following configuration elements that are used to run the script:

  • IntervalSeconds—The length of time between each run of the script.

  • ScriptName—A user-defined script name with the required .vbs or .js extension. To run the script, the agent creates a temporary script file with the specified name, which is then executed by CScript.exe (the command-line version of the Windows Script Host).

  • Arguments—Whitespace-delimited values for any arguments that are required by the script.

  • ScriptBody—The body of the script.

  • TimeoutSeconds—The amount of time to allow the script to run before terminating it.

The Microsoft.Windows.TimedScript.PerformanceProvider also includes a component that maps each name-value pair in the property bag to a performance data type that is stored in the Operations Manager database. To perform this mapping, the module's configuration accepts the following additional configuration elements:

  • ObjectName—A user-defined name for the object for which performance data is collected.

  • CounterName—A user-defined name for the performance data.

  • InstanceName—A user-defined name for the entity that generated the performance data.

  • Value—The value from the property bag data that is converted to a performance data point.

The custom module type defines values for each of these required configuration elements. When defining the script's body, the module wraps the script in CDATA to ensure that any XML characters in the script that are not valid are not exposed in the Management Pack's XML file—for example, an ampersand or a greater than or less than symbol.

The custom module type also allows users of the Management Pack to override the value of the IntervalSeconds configuration element, which defines how frequently the monitoring script runs.

The Management Pack uses a data module of the custom type as a data source for a new monitoring type. The monitoring type defines two states for an AppYComponent file: GreaterThanThreshold or LessThanEqualThreshold. The type also defines conditions to compare the file size to the given threshold, which is specified when creating a monitor of this type.

<MonitorTypes>
  <UnitMonitorType ID="Microsoft.Demo.Scripting.AppYComponent.FileSize.ThresholdMonitorType" Accessibility="Internal">
    <MonitorTypeStates>
      <MonitorTypeState ID="GreaterThanThreshold"/>
      <MonitorTypeState ID="LessThanEqualThreshold"/>
    </MonitorTypeStates>
    <Configuration>
      <xsd:element name="IntervalSeconds" type="xsd:integer"/>
      <xsd:element name="Path" type="xsd:string"/>
      <xsd:element name="FileName" type="xsd:string"/>
      <xsd:element name="ThresholdKB" type="xsd:double"/>
    </Configuration>
    <OverrideableParameters>
      <OverrideableParameter ID="IntervalSeconds" ParameterType="int" Selector="$Config/IntervalSeconds$"/>
    </OverrideableParameters>
    <MonitorImplementation>
      <MemberModules>
      <!-- The monitor type uses the script-based module as its data source. --> 
        <DataSource ID="DS" TypeID="Microsoft.Demo.Scripting.AppYComponent.FileSizeProvider">
          <IntervalSeconds>$Config/IntervalSeconds$</IntervalSeconds>
          <Path>$Config/Path$</Path>
          <FileName>$Config/FileName$</FileName>
        </DataSource>
        <ConditionDetection ID="FilterLessThanEqual" TypeID="System!System.ExpressionFilter">
          <Expression>
            <SimpleExpression>
              <ValueExpression>
                <XPathQuery Type="Double">Value</XPathQuery>
              </ValueExpression>
              <Operator>LessEqual</Operator>
              <ValueExpression>
                <Value Type="Double">$Config/ThresholdKB$</Value>
              </ValueExpression>
            </SimpleExpression>
          </Expression>
        </ConditionDetection>
        <ConditionDetection ID="FilterGreaterThan" TypeID="System!System.ExpressionFilter">
          <Expression>
            <SimpleExpression>
              <ValueExpression>
                <XPathQuery Type="Double">Value</XPathQuery>
              </ValueExpression>
              <Operator>Greater</Operator>
              <ValueExpression>
                <Value Type="Double">$Config/ThresholdKB$</Value>
              </ValueExpression>
            </SimpleExpression>
          </Expression>
        </ConditionDetection>
      </MemberModules>
      <RegularDetections>
        <RegularDetection MonitorTypeStateID="GreaterThanThreshold">
          <Node ID="FilterGreaterThan">
            <Node ID="DS"/>
          </Node>
        </RegularDetection>
        <RegularDetection MonitorTypeStateID="LessThanEqualThreshold">
          <Node ID="FilterLessThanEqual">
            <Node ID="DS"/>
          </Node>
        </RegularDetection>
      </RegularDetections>
    </MonitorImplementation>
  </UnitMonitorType>
</MonitorTypes>

The Management Pack uses the new monitor type to define a new monitor. The monitor associates each of the monitor type's states with a corresponding health state. If the file's size is less than or equal to a given threshold, the monitor sets the file's health state to "Success." If the file's size is greater than a given threshold, the monitor sets the file's health state to "Error" and generates an alert. When defining the configuration values required by the monitor's type, the monitor sets the file's threshold to 100 KB.

<Monitors>
  <UnitMonitor ID="Microsoft.Demo.Scripting.AppYComponent.FileSizeMonitor" Target="Microsoft.Demo.Scripting.AppYComponent" TypeID="Microsoft.Demo.Scripting.AppYComponent.FileSize.ThresholdMonitorType" Enabled="true" Remotable="false" ParentMonitorID="SystemHealth!System.Health.PerformanceState" Accessibility="Internal">
    <Category>PerformanceHealth</Category>
    <AlertSettings>
      <AlertOnState>Error</AlertOnState>
      <AutoResolve>true</AutoResolve>
      <AlertPriority>Normal</AlertPriority>
    </AlertSettings>
    <OperationalStates>
      <OperationalState HealthState="Success" MonitorTypeStateID="LessThanEqualThreshold" ID="FileSizeOK"/>
      <OperationalState HealthState="Error" MonitorTypeStateID="GreaterThanThreshold" ID="FileSizeTooBig"/>
    </OperationalStates>
    <Configuration>
      <IntervalSeconds>60</IntervalSeconds>
      <Path>$Target/Host/Property[Type='Microsoft.Demo.Scripting.AppY']/Path$</Path>
      <FileName>$Target/Property[Type='Microsoft.Demo.Scripting.AppYComponent']/FileName$</FileName>
      <ThresholdKB>100.0</ThresholdKB>
    </Configuration>
  </UnitMonitor>
</Monitors>

Example 2—Defining a Rule that Runs a Script

In this example, a Management Pack creates a rule that runs a custom script by using the same data source as defined in example 1.

<Rule ID="Microsoft.Demo.Scripting.AppYComponent.GetFileSizeAsPerf" Target="Microsoft.Demo.Scripting.AppYComponent" Enabled="true" Remotable="false">
  <Category>PerformanceHealth</Category>
  <DataSources>
    <DataSource ID="DS" TypeID="Microsoft.Demo.Scripting.AppYComponent.FileSizeProvider">
      <IntervalSeconds>60</IntervalSeconds>
      <Path>$Target/Host/Property[Type='Microsoft.Demo.Scripting.AppY']/Path$</Path>
      <FileName>$Target/Property[Type='Microsoft.Demo.Scripting.AppYComponent']/FileName$</FileName>
    </DataSource>
  </DataSources>
  <WriteActions>
    <WriteAction ID="WriteToDB" TypeID="SC!Microsoft.SystemCenter.CollectPerformanceData"/>
  </WriteActions>
</Rule>

The rule uses a write action to map the property bag data to a performance data type that is stored in the Operations Manager database.

See Also

Tasks

How to Create Monitoring Data by Using a Script

Concepts

Getting Started Developing Runtime Scripts
Runtime Scripts Overview