Configuring Metrics Rules in XML File Policies

Rules define the action a policy should take in response to a specific type of incoming metric. Each rule consists of the following:

• A condition for the incoming data

  The condition is the part of a policy that describes the data source.

• Settings for the outgoing event

  The settings define the actual metric data that Operations Connector sends to OMi.

A policy must contain at least one rule. If the policy contains multiple rules, they are evaluated consecutively. After the condition is matched in one rule, rule evaluation stops.

To access

In the Operations Connector user interface, click in the toolbar. Then click Metric > XML File.

Alternatively, double-click an existing policy to edit it.

Click Rules to open the policy Rules page.

Rule types

The rule types are:

• Store on matched rule. If matched, Operations Connector stores metrics in a buffer until a maximum number of records or a maximum amount of time is reached. These metrics are sent to OMi when they are requested, and they use the settings defined for the rule. If you do not configure these settings, the default settings are used.

• Suppress on matched rule. If matched, Operations Connector stops processing.

• Suppress on unmatched rule. If not matched, Operations Connector stops processing.

Metric attributes

Each time a metric policy runs, it extracts raw data from its defined data source and builds a metric structure.

A metric structure consists of these attributes:

• Basic attributes:

  • Data domain

    The namespace of the integrated performance records, used in the Operations Agent store to avoid clashes.

  • Metric class

    Defines the metric class under which the metric appears in the Operations Agent store and consumers.

  • Metric name

    Defines the metric name under which the metric appears in the Operations Agent store and consumers.

  • Related CI

    Used to identify an instance of a performance record and associates it with a concrete CI instance. For details on how to associate the Related CI with the values in the RTSM model, see Create a policy topic. For an example, see Example – Create a Metrics Policy topic.

  • Node

    Used to identify a node-like CI to which the performance records are associated to.

  • Value

    The actual performance value which is converted to 64-bit floating point number.

  • Time measured

    The time stamp when the value was determined in the third-party system.

• Advanced attributes:

  • Original metric name

    The name of the metric as used on the third-party system.

  • Unit

    The unit of the metric.

  • Integration id

    An id, used to identify the source of the integration.

Tasks

How to configure metric rules in XML policies

This task describes how configure policy rules.

1. In the Policy Rules section, click and select the type of rule to define what the policy should do in response to a specific string in the XML file. Each policy must have at least one rule.

2. In the Rule Content section, use the Condition tab to define the match condition.

   Click to create a new condition. Enter the property and select the operator from the drop-down list. Add the operand. Use the arrows and collapse/expand buttons to navigate the conditions.

3. Optional. If you are creating a rule of the type 'store on matched rule', set the attributes (Basic or/and Advanced) for metrics that you want the rule to override. If default attributes are specified in the Defaults tab, you use the defaults or you can override them as described below.

   The attributes are in two groups, basic and advanced. The advanced attributes are optional.

4. Optional. Use the Sample Data tab to drag XML properties (XML elements and attributes) and values to the attribute boxes. Alternatively, you can type the path to the XML property or value directly into the attribute box.

   XML properties use the following syntax: <$DATA:/<XMLProperty>>

   <XMLProperty> is the path from the root XML element of XML data to a specific XML element or attribute within that data. XML path uses slashes (/) as the path delimiters.

   Operations Connector replaces the XML property at runtime with the value of the specified XML element or attribute. If you insert an XML value, the value will be used.

   The Sample Data tab is empty if no sample data is loaded into Operations Connector or no XML data has been received for the policy.

5. Optional. Use the Mappings tab to add mapping definitions to the attribute boxes.

   Mappings are custom variables that you define in the mappings tab. The default name of the mapping variable is map<XMLProperty>, for example mapSeverity.

   Alternatively, type the custom variable into the attribute box using the following syntax:

   • Map Name list contains the map name of the variable: map<XMLProperty>, for example mapSeverity.

   • Input Data Property list item: <$DATA:/<XMLTag>/<XMLProperty>>

     For example, the custom variable mapSeverity has the following input data property: <$DATA:/PerformanceAlert/Severity> where Severity is a child element of PerformanceAlert.

6. Optional. Use the Pattern Matching Variables tab to add variables created with pattern matching.

   Pattern matching variables insert matched strings that have previously been assigned to variables. To insert a pattern matching variable, type the variable name enclosed in angle brackets (for example, <VariableName>) or drag and drop it from the Pattern Matching Variables list to the metric attribute.

7. Optional. Use the Operators tab to apply operators to the attribute values. Two functions are available:

   $MATCH(), to test a string or a variable against a pattern. The $MATCH function accepts three or four parameters:

   - the input string

   - the pattern definition

   - the output string if pattern matches on the input string

   - the output string if the pattern does not match (optional)

   Example: The data of the input field hostname start always with "TEST" (for example "TESTABC"). The $MATCH function to use the string after "TEST" is as follows:

   $MATCH(<$DATA:hostname>,TEST<*.prefix>,<prefix>)

   • <$DATETIME(FORMAT,VALUE)>, to convert the format of dates from the common format to the UNIX systems time (Epoch time) format.

     To apply operators to the attribute values, you can drag and drop them to a text field in the left pane of the same policy editor page. The appropriate tooltips are shown while performing this operation, which describe the role of the dragged operator.

8. Optional. Use the Indicators tab to add indicators to the source or target value fields. After loading the indicators from the connected OMi server, the Indicators tab shows a hierarchy of configuration item types.

9. Optional. In the Policy Variables tab, add policy variables to metric attributes. Operations Connector replaces the variables with the appropriate values in the generated metric.

   Use quotation marks to surround variables, for example "<$MSG_NODE>" or "<$MSG_GEN_NODE>", at least for those variables whose values can contain space characters.

Related tasks

• How to Collect Event Data from XML Files

UI Descriptions

Policy Rules List

UI Element	Description
	Create New Rule: Provides the following options: Store on matched rule. If matched, Operations Connector stores metrics in a buffer until a maximum number of records or a maximum amount of time are reached, when it sends them to OMi. The metrics use the settings defined for the rule. If you do not configure these settings, the default settings are used. Suppress on matched rule. If matched, Operations Connector stops processing and does not send metrics to OMi. Suppress on unmatched rule. If not matched, Operations Connector stops processing and does not send metrics to OMi.
	Copy Rule. Copies the selected rule. You can then rewrite the description of the copied rule and edit the rule.
	Delete Rule. Deletes the selected rule.
	Move Up. Moves the selected rule higher in the rule order.
	Move Down. Moves the selected rule lower in the rule order.
<Move to>	Entered number is used to select the rule with that sequence number in the list of rules. To select a specific rule in the rule list, type the rule's sequence number in the <Move to> field and click the button.
<Search Rules>	Entered search string is used to search the rule descriptions and highlight only the rules containing the specified string. To search for rules with specific text strings in the rule description, type the string in the <Search rules> field and click the button. The first matching rule is selected in the list of rules. Click the and buttons to move the previous and next matching rule.
	Activate/Deactivate Rule Filter. Activates and deactivates the rule filter.
Seq.	Sequence number of the rules. Rules are evaluated in a specific order. When one condition is matched, no additional rules are evaluated.
Rule Description	Description of the rule. It is good practice to use a description that helps you remember what the rule does.
Rule Type	The three rule types are: Store on matched rule. If matched, Operations Connector stores metrics in a buffer until a maximum number of records or a maximum amount of time are reached, when it sends them to OMi. The metrics use the settings defined for the rule. If you do not configure these settings, the default settings are used. Suppress on matched rule. If matched, Operations Connector stops processing and does not send metrics to OMi. Suppress on unmatched rule. If not matched, Operations Connector stops processing and does not send metrics to OMi. You can change the rule type by clicking the current rule type in the list of rules and selecting another rule type from the drop-down list.

Condition Tab

UI Element	Description
	New Item. Creates a new condition with the default operator equals.
	Delete Item. Deletes the selected condition.
	Move Up. Moves the selected condition higher in the condition order.
	Move Down. Moves the selected condition lower in the condition order.
	Expand. Expands the list of conditions to display all details.
	Collapse. Collapses the list of conditions to display only the names and hide the details.
	Click to expand the details of a condition.
	Click to hide the details of a condition.
Property	Input data property that the policy searches for (for example, host). XML Property that the policy searches for. You must prefix the XML property with <XML Event/Metric Tag> ( /<XML Event/Metric Tag>/<full path to XML Property>).
Operator	The following operators are available: equals not equals less than greater than less or equal greater or equal matches (Enables you to enter a pattern in the Operand field.)
Operand	Value or pattern that you want the policy to compare with the table column (Database policies), or the input data reference (Structured Log File policies), or the value of the XML property (REST Web Service Listener policies and XML File policies). If you are working with sample data, you can drag the value from the Values list and drop it in the Operand field.

Basic Tab (Default Attributes)

UI Element	Description
Data domain	The namespace of the integrated performance records, used in the Operations Agent store to avoid clashes. Example: "BSMCMetrics"
Metric class	Defines the metric class. Metric class and metric name are concatenated as the metric name that appears in the Operations Agent store and consumers. Example: "Windows CPU Monitor"
Metric name	Defines the metric name. Metric class and metric name are concatenated as the metric name that appears in the Operations Agent store and consumers. Example: "CPU Utilization"
Related CI	Contains the CI that is related to the metric (for example, oraclesid01@@node.example.com or C:@@server.example.com). Use the format <CI 1>:<CI 2>:...:<CI n>@@<hostname>. Best practices for related CIs It is necessary to differentiate between CIs that have a Composition relationship to a node, and those that do not have such a relationship: For “hosted on” CIs <key attribute 1>:<key attribute 2>:<key attribute n>@@<hostname> Typically, a “hosted on” CI is a sub-type of “Running Software”. For example, a CI of type websphereas has a Composition relationship to a node. For virtual CIs <key attribute 1>:<key attribute 2>:<key attribute n> A virtual CI does not have a strong containment relationship (Composition relationship) to node. An example of a typical virtual CI type is cluster. This CI type does not have a strong containment relationship to a node. If you have problems resolving non-hosted CIs, provide the RTSM ID of the desired CI by using the format UCMDB:<ci_uuid>. For more information about CI resolution in OMi, see the OMi Help.
Node	Used to identify a node-like CI to which the performance records are associated to. Example: "dbsys1.company.com"
Value	The actual performance value. It is automatically converted to a double-precision number. Example: 80
Time measured	The time stamp when the value was determined in the third-party system, expressed in the following formats: Integers.Operations Connector interprets integers in the policy source as seconds since 00:00:00 UTC on 1 January 1970 (UNIX system time). For example, 1276600333 is 15 June 2010, at 11:12:13. Use the $DATETIME function to convert it. For details about the function, see Configuring Event Defaults in Database Policies topic. Default time formats.Operations Connector by default interprets the following time formats: yyyy-mm-ddTHH:MM:SS (for example, 2010-06-15T11:12:13) mm/dd/yyyy HH:MM:SS (for example, 06/15/2010 11:12:13) Additional time zone formats are supported: yyyy-mm-ddTHH:MM:SS tz (for example, 2010-06-15T11:12:13 +3) mm/dd/yyyy HH:MM:SS tz(for example, 06/15/2010 11:12:13 -2) where tz is a number for the offsett to the UTC time zone. You can also use half or quarter hours (.25, .5, or .75, for example, 2010-06-15T11:12:13 -2.75). If you want to create your own pattern, you can store the time zone information in <@.tz> to match all above mentioned time zones.

Advanced Tab (Default Attributes)

UI Element	Description
Original metric name	The name of the metric as used on the third-party system. Example:
Unit	The unit of the metric values. Example: "MB"
Integration id	An ID, used to identify the source of the integration. Example: "DB-ORA"

Sample Data Tab

UI Element	Description
<Search Properties>	Entered search string is used to find an XML property or value. The list changes as you type; only matching items appear. To clear the search results, click .
XML Properties	Shows all XML elements and attributes that match an XML tag. The XML properties list is empty if no sample data has been loaded into the policy or if the sample data does not match any specified XML tags.
	Toggle Short/Full Path Notation. Shows or hides the full path to the XML property or value. The full path begins with the XML tag specified in the Source tab. The XML Properties section by default shows the short path to the XML property or value.
Values for '...'	Displays the values of the XML property selected in the XML Properties section.
	Find Matching Records. To find values that belong to more than one XML property, select the value and click . The XML Sample Data window opens and shows all XML properties that have the selected value.
	Toggle Deduplication. Shows or hides duplicate values.

Mappings Tab

UI Element	Description
<Mappings>	Displays the mapping definitions configured for the policy.

Pattern Matching Variables Tab

UI Element	Description
<Variables>	Displays the user-defined variables configured in the Condition tab. For more information about assigning strings to variables, see User-defined variables in patterns topic.

Operators Tab

Expressions and Functions	Description
$MATCH(<input>, <pattern>,<output_on_match>(,<output_on_no_match>))	Tests a string or variable against a pattern. The $MATCH function accepts three or four parameters: - the input string - the pattern definition - the output string if pattern matches on the input string - the output string if the pattern does not match (optional) Example: The data of the input field hostname start always with "TEST" (for example "TESTABC"). The $MATCH function to use the string after "TEST" is: $MATCH(<$DATA:hostname>,TEST<*.prefix>,<prefix>)
<$DATETIME(<format>,<value>)>	Converts regular dates to UNIX system time (Epoch time).

Indicators Tab

UI Element	Description
	Refresh. Loads the configured indicators from the connected OMi server. Loading indicators from the OMi server may take a few seconds. The Operations Connector server must be configured as an Operations Connector integration server in OMi for the indicators to load successfully.
<Search …>	Entered search string is used to search the indicators and highlight only the indicators containing the specified string. To search for indicators with specific text strings in the name, type the string in the <Search …> field and click the button. The first matching indicator is selected in the list of rules. Click the and buttons to move to the previous and next matching indicator.
<Indicators>	Hierarchy of configuration item types with associated health indicators (HIs), which are applicable for the event integration only, and event type indicators (ETIs). To insert an indicator with a state in a policy, drag and drop the indicator from the Indicators tab to the relevant field in the policy.

Policy Variables Tab

Policy Variables Tab for Database and REST Web Service Listener Policies (Events only)

Variable	Description
<$MSG_APPL>	Returns the name of the application associated with the input event that caused the message. Sample output: /usr/bin/su(1) Switch User
<$MSG_GEN_NODE>	Returns the IP address of the node that sends the event. Sample output: 192.168.1.123.
<$MSG_GEN_NODE_NAME>	Returns the host name of the node that sends the event. Sample output: node123.example.com.
<$MSG_GRP>	Returns the default category of the event. Sample output: Security
<$MSG_ID>	Returns the unique identity number of the event, as generated by the Operations Agent. Note that identity numbers are not generated for suppressed messages. Sample output: 6e998f80-a06b-71d0-012e-0f887a7c0000
<$MSG_NODE>	Returns the IP address of the node on which the original event took place. Sample output: 192.168.1.123
<$MSG_NODE_NAME>	Returns the name of the node on which the original event took place. This is the hostname that the agent resolves for the node. This variable is not fixed, however, and can be changed by a policy on a per-event basis.
<$MSG_SERVICE>	Returns the service name associated with the event.
<$MSG_OBJECT>	Delivers the name of the object associated with the event.
<$MSG_SEV>	Returns the default value for the severity of the event. Sample output: Normal
<$MSG_TEXT>	Returns the full text of the event. Sample output: SU 03/19 16:13 + ttyp7 bill-root
<$MSG_TIME_CREATED>	Returns the time the message was created on the managed node in seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time. Sample output: 950008585

Policy Variables Tab for XML File and Structured Log File Policies (Events only)

Variable	Description
<$LOGFILE>	Returns the name of the log file that contains the input event. Sample output: program_log.txt
<$LOGPATH>	Returns the name and path of the log file that contains the input event. Sample output: C:\temp\mylogfile\program_log.txt
<$MSG_APPL>	Returns the name of the application associated with the input event that caused the message. Sample output: /usr/bin/su(1) Switch User
<$MSG_GEN_NODE>	Returns the IP address of the node that sends the event. Sample output: 192.168.1.123.
<$MSG_GEN_NODE_NAME>	Returns the host name of the node that sends the event. Sample output: node123.example.com.
<$MSG_GRP>	Returns the default category of the event. Sample output: Security
<$MSG_ID>	Returns the unique identity number of the event, as generated by the agent. Note that identity numbers are not generated for suppressed messages. Sample output: 6e998f80-a06b-71d0-012e-0f887a7c0000
<$MSG_NODE>	Returns the IP address of the node on which the original event took place. Sample output: 192.168.1.123
<$MSG_NODE_NAME>	Returns the name of the node on which the original event took place. This is the hostname that the agent resolves for the node. This variable is not fixed, however, and can be changed by a policy on a per-event basis.
<$MSG_SERVICE>	Returns the service name associated with the event.
<$MSG_OBJECT>	Delivers the name of the object associated with the event.
<$MSG_SEV>	Returns the default value for the severity of the event. Sample output: Normal
<$MSG_TEXT>	Returns the full text of the event. Sample output: SU 03/19 16:13 + ttyp7 bill-root
<$MSG_TIME_CREATED>	Returns the time the message was created on the managed node in seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time. Sample output: 950008585

Policy Variables Tab for Open Message Interface, Scheduled Task, and SNMP Interceptor Policies (Events only)

Variable	Description
<$MSG_APPL>	Returns the name of the application associated with the input event that caused the message. Sample output: /usr/bin/su(1) Switch User
<$MSG_GEN_NODE>	Returns the IP address of the node that sends the event. Sample output: 192.168.1.123.
<$MSG_GEN_NODE_NAME>	Returns the host name of the node that sends the event. Sample output: node123.example.com.
<$MSG_GRP>	Returns the default category of the event. Sample output: Security
<$MSG_ID>	Returns the unique identity number of the event, as generated by the Operations Agent. Note that identity numbers are not generated for suppressed messages. Sample output: 6e998f80-a06b-71d0-012e-0f887a7c0000
<$MSG_NODE>	Returns the IP address of the node on which the original event took place. Sample output: 192.168.1.123
<$MSG_NODE_NAME>	Returns the name of the node on which the original event took place. This is the hostname that the agent resolves for the node. This variable is not fixed, however, and can be changed by a policy on a per-event basis.
<$MSG_SERVICE>	Returns the service name associated with the event.
<$MSG_OBJECT> (Open Message Interface and Scheduled Task Only)	Delivers the name of the object associated with the event.
<$MSG_SEV>	Returns the default value for the severity of the event. Sample output: Normal
<$MSG_TEXT>	Returns the full text of the event. Sample output: SU 03/19 16:13 + ttyp7 bill-root
<$MSG_TIME_CREATED>	Returns the time the message was created on the managed node in seconds elapsed since midnight (00:00:00), January 1, 1970, coordinated universal time. Sample output: 950008585

Policy Variables Tab for All Policy Types (Metrics only)

Variable	Description
<$MSG_GEN_NODE>	Returns the IP address of the node that sends the event. Sample output: 192.168.1.123.
<$MSG_GEN_NODE_NAME>	Returns the host name of the node that sends the event. Sample output: node123.example.com.

Related topics

Time Created