Administer > Policies > REST Web Service Listener Policies > REST Web Service Listener Policy User Interface > Configuring Metrics Defaults in REST Web Service Listener Policies

Configuring Metrics Defaults in REST Web Service Listener Policies

The Default Metric Attributes page enables you to assign default values to the metric attributes. The values can be used when defining the policy rules on the Rules tab, and can also be overridden there.

For examples and end-to-end workflow information on collecting metrics data, see Collecting Metrics Data topic.

To access

In the Operations Connector user interface, click Create in the toolbar. Then click Metrics > REST Web service listener REST Web Service Listener.

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

Click Defaults to open the policy Default Metric Attributes page.

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.

Parameters for metrics policies

The reportMetricObject and reportMetricsArray methods send the following keys, which you can reference in a metrics integration policy as $key. For example, if you insert $MonitorName in the Monitor Name field, the policy replaces $MonitorName with the monitor name from the SOAP message before sending the metric to OMi.

Key from SOAP Message Policy Parameter
monitorName $MonitorName
monitorType $MonitorType
targetName $TargetName
timeStamp $TimeStamp
quality $Quality
monitorState $MonitorState
measurementName $MeasurementName
measurementValue $Value
measurementCIHint $MeasurementCIHint
measurementETI $MeasurementETI

Tasks

How to configure metrics defaults for REST Web service listener policies

This task describes how to configure metric attribute defaults for all metrics collected by this policy.

  1. Define the metric attributes common to all metrics collected by this policy, such as metric class and name. All metrics in the Basic tab marked with a * are required. Advanced attributes are optional.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

  6. 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

UI Descriptions

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 Find Matching XML Events in Sample Data. 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.

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
<$MSG_TYPE> Delivers the name set for message type.

Policy Variables Tab for XML File and Structured Log File 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 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_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
<$MSG_TYPE> Delivers the name set for message type.

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
<$MSG_TYPE> Delivers the name set for message type.

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.