System.Correlator

  • Article

Applies To: System Center 2012 - Operations Manager, System Center 2012 R2 Operations Manager, System Center 2012 SP1 - Operations Manager

The System.Correlator condition detection module type is used to correlate two incoming data item types, to detect a specific counting and/or ordering pattern of data items. A module of this type accepts data of any type and outputs System.CorrelatorData data.

Usage

This is the base native module used in all modules and monitors that support correlation. Generally, you would not use this module directly and would instead use one of the primary composite modules that implement it. The primary correlation scenarios are related-events detection and missing-related-events detection. Both of these usage scenarios are time-based and correlate the occurrence or lack of occurrence of an event pattern within a specific time delta.

Type Definition

<ConditionDetectionModuleType ID="System.Correlator" Stateful="true" Accessibility="Public" PassThrough="false" Batching="false">
  <Configuration>
    <IncludeSchemaTypes>
      <SchemaType>System.ExpressionEvaluatorSchema</SchemaType>
    </IncludeSchemaTypes>
    <xsd:element name="Correlator" type="CorrelatorType"/>
  </Configuration>
  <ModuleImplementation Isolation="Any">
    <Native>
      <ClassID>6BB6ADFC-85E3-4D65-9998-2566C3C17F70</ClassID>
    </Native>
  </ModuleImplementation>
  <OutputType>System.CorrelatorData</OutputType>
  <InputTypes>
    <InputType>System.BaseData</InputType>
    <InputType>System.BaseData</InputType>
  </InputTypes>
</ConditionDetectionModuleType>

Parameters

The System.Correlator supports the configuration parameters described in the following table.

Parameter Type Overrideable Description

Correlator

CorrelatorType

False

Required parameter. Defines the configuration of the correlator module.

For more information about the Correlator parameter and how to configure its elements, see CorrelatorType.

Remarks

The System.Correlator module type assumes two data sources as input. One data source is the primary data source, and the other is the secondary data source.

This module’s objective is to determine whether one incoming data item (primary) is followed by a different data item (secondary) within a specific time delta. Within a Ruleor a UnitMonitorType definition, the two data sources must be appropriately arranged to specify which one is to be primary and which one secondary.

In the following XML sample, two condition detection modules are implemented in a unit monitor type definition. The SuccessfulConfigCondition correlator module’s primary data source is SuccessfulConfigEventDataSource. The secondary data source is PartialConfigEventDataSource . The ConfigurationPartiallyLoaded correlator module’s primary data source is PartialConfigEventDataSource. The secondary data source is SuccessfulConfigEventDataSource.

<UnitMonitorType ID="Microsoft.SystemCenter.ConfigurationProcessingMonitorType" Accessibility="Internal">
  <MonitorTypeStates>
    <MonitorTypeState ID="ConfigurationSuccessfullyLoaded" NoDetection="false" />
    <MonitorTypeState ID="ConfigurationNotLoaded" NoDetection="false" />
    <MonitorTypeState ID="ConfigurationPartiallyLoaded" NoDetection="false" />
  </MonitorTypeStates>
  <Configuration>
    <IncludeSchemaTypes>
      <SchemaType>Windows!Microsoft.Windows.ComputerNameSchema</SchemaType>
    </IncludeSchemaTypes>
    <xsd:element name="ComputerName" type="ComputerNameType" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
    <xsd:element name="ManagementGroupName" type="xsd:string" xmlns:xsd="http://www.w3.org/2001/XMLSchema" />
  </Configuration>
  <MonitorImplementation>
    <MemberModules>
      <DataSource ID="FailedConfigEventDataSource" TypeID="Windows!Microsoft.Windows.EventProvider">
…
      </DataSource>
      <DataSource ID="PartialConfigEventDataSource" TypeID="Windows!Microsoft.Windows.EventProvider">
…
      </DataSource>
      <DataSource ID="SuccessfulConfigEventDataSource" TypeID="Windows!Microsoft.Windows.EventProvider">
…
      </DataSource>
      <ConditionDetection ID="PartialConfigCondition" TypeID="System!System.CorrelatorAutoCondition">
…
      </ConditionDetection>
      <ConditionDetection ID="SuccessfulConfigCondition" TypeID="System!System.CorrelatorCondition">
…
      </ConditionDetection>
    </MemberModules>
    <RegularDetections>
      <RegularDetection MonitorTypeStateID="ConfigurationSuccessfullyLoaded">
        <Node ID="SuccessfulConfigCondition">
          <Node ID="SuccessfulConfigEventDataSource" />
          <Node ID="PartialConfigEventDataSource" />
        </Node>
      </RegularDetection>
      <RegularDetection MonitorTypeStateID="ConfigurationNotLoaded">
        <Node ID="FailedConfigEventDataSource" />
      </RegularDetection>
      <RegularDetection MonitorTypeStateID="ConfigurationPartiallyLoaded">
        <Node ID="PartialConfigCondition">
          <Node ID="PartialConfigEventDataSource" />
          <Node ID="SuccessfulConfigEventDataSource" />
        </Node>
      </RegularDetection>
    </RegularDetections>
  </MonitorImplementation>
</UnitMonitorType>

To see how to specify primary and secondary data sources within a rule definition, see the sample XML as the end of this document.

It is also possible to detect whether or not an event pattern does not happen in a specific way. If you want to detect missing event patterns, you can implement the System.CorrelatorCondition module type. The correlator condition type module enables you to define a filter expression on the output data of the System.Correlator module.

Composition

The System.Correlator module is a native module.

Errors

The errors listed in the following table can occur from within the System.Correlator module.

Exception Reason

11150

The module failed to initialize.

11151

The module’s configuration data is invalid.

11152

The module encountered an internal fatal error and must be unloaded.

11153

The module failed to process an incoming data item and the data item was dropped.

11154

The module failed during the garbage collection phase.

11155

The module processing thread failed with an internal error and must unload.

11156

The module failed to initialize because the number of input ports specified did not match what was expected.

11157

The module failed to initialize because of some invalid or missing configuration.

11158

The module failed to initialize due to an out of range configuration.

11159

The module failed to initialize due to invalid configuration.

11160

The module cannot accept the combination of a reset window policy with any order.

11161

The module failed to initialize because the specified compare count is less than the minimum allowed.

11162

The module failed to query the time stamp of a delivered item, item was dropped

11163

The module could not convert the specified property to a date time value.

11164

The module could not get the creation time of the item, item was dropped.

11165

The module reached the maximum allowed queued items for a given interval, forced output happened.

None.

External Module References

The System.Correlator module is a member of the following modules:

Module Type Library Usage

System.CorrelatorAutoCondition

System.Library

Correlates two incoming data item types to detect a specific counting and/or ordering pattern of data items. Returns data only when the value specified in the Count parameter has been met.

System.CorrelatorAutoCondition

System.Library

Correlates two incoming data item types to detect a specific counting and/or ordering pattern of data items. Returns data only when the value specified in the Count parameter has not been met by the time the correlation window ends.

System.CorrelatorCondition

System.Library

Correlates two incoming data item types to detect a specific counting and/or ordering pattern of data items. Allows for the filtering of the output data.

Sample

The following XML sample illustrates a rule that generates an alert whenever data is returned from the correlator. The correlator module’s primary data source is DS1. The secondary data source is DS2. The correlator will begin queuing up primary data items as it receives them and begin the first interval when it receives the first primary data item. The correlator will then return data either when the 30 second interval ends or when the number of secondary items has been reached. It will move to the next primary data item in the queue and begin a new window.

Warning

In a real-world scenario, you would not raise an alert in this manner because an alert would be generated after every interval has been reached. The sample in this topic is only for illustrative purposes. Use the System.CorrelatorCondition instead to provide a filter over the correlator data so as to scope the type of alerts the system will receive.

<Rule ID="Microsoft.Samples.CorrelationRule.InSequenceFirstOccurence " Enabled="true" Target="Windows!Microsoft.Windows.OperatingSystem" ConfirmDelivery="false" Remotable="true" Priority="Normal" DiscardLevel="100">
  <Category>Custom</Category>
  <DataSources>
    <DataSource ID="DS2" TypeID="Windows!Microsoft.Windows.EventProvider">
      <ComputerName>$Target/Host/Property[Type="Windows!Microsoft.Windows.Computer"]/NetworkName$</ComputerName>
      <LogName>Application</LogName>
      <Expression>
        <And>
          <Expression>
            <SimpleExpression>
              <ValueExpression>
                <XPathQuery Type="String">PublisherName</XPathQuery>
              </ValueExpression>
              <Operator>Equal</Operator>
              <ValueExpression>
                <Value Type="String">EventCreate</Value>
              </ValueExpression>
            </SimpleExpression>
          </Expression>
          <Expression>
            <SimpleExpression>
              <ValueExpression>
                <XPathQuery Type="UnsignedInteger">EventDisplayNumber</XPathQuery>
              </ValueExpression>
              <Operator>Equal</Operator>
              <ValueExpression>
                <Value Type="UnsignedInteger">101</Value>
              </ValueExpression>
            </SimpleExpression>
          </Expression>
        </And>
      </Expression>
    </DataSource>
    <DataSource ID="DS1" TypeID="Windows!Microsoft.Windows.EventProvider">
      <ComputerName>$Target/Host/Property[Type="Windows!Microsoft.Windows.Computer"]/NetworkName$</ComputerName>
      <LogName>Application</LogName>
      <Expression>
        <And>
          <Expression>
            <SimpleExpression>
              <ValueExpression>
                <XPathQuery Type="String">PublisherName</XPathQuery>
              </ValueExpression>
              <Operator>Equal</Operator>
              <ValueExpression>
                <Value Type="String">EventCreate</Value>
              </ValueExpression>
            </SimpleExpression>
          </Expression>
          <Expression>
            <SimpleExpression>
              <ValueExpression>
                <XPathQuery Type="UnsignedInteger">EventDisplayNumber</XPathQuery>
              </ValueExpression>
              <Operator>Equal</Operator>
              <ValueExpression>
                <Value Type="UnsignedInteger">102</Value>
              </ValueExpression>
            </SimpleExpression>
          </Expression>
        </And>
      </Expression>
    </DataSource>
  </DataSources>
  <ConditionDetection ID="Correlator" TypeID="System!System.Correlator">
    <Correlator>
      <CorrelationExpression>
        <Expression />
      </CorrelationExpression>
      <Count>3</Count>
      <Interval>30</Interval>
      <CorrelationOrder>InSequence</CorrelationOrder>
      <CorrelationItemPolicy>First</CorrelationItemPolicy>
    </Correlator>
  </ConditionDetection>
  <WriteActions>
    <WriteAction ID="GenerateAlert" TypeID="Health!System.Health.GenerateAlert">
      <Priority>1</Priority>
      <Severity>2</Severity>
      <AlertMessageId>$MPElement[Name="StaceyTest.CorrelationRule.InSequenceFirstOccurence.AlertMessage"]$</AlertMessageId>
      <Suppression>
        <SuppressionValue />
      </Suppression>
    </WriteAction>
  </WriteActions>
</Rule>

Information

   

Module Type

ConditionDetectionModuleType

InputType

System.BaseData

Output Type

System.CorrelatorData

Implementation

Native

Library

System.Library