Configure Perl Script Policies

You can create or edit a Perl Script policy using the Perl Script policy editor, which you can open in the following ways.

• To open the editor from the Edit Aspect dialog box:

  1. Open the Management Templates & Aspects manager:

     Administration > Monitoring > Management Templates & Aspects

     Alternatively, click Management Templates & Aspects.

  2. In the Configuration Folders pane, expand the configuration folders.

  3. In the Management Templates & Aspects pane, click an aspect, and then click the  Edit Item button.

     The Edit Aspect dialog box opens.

  4. Click the Policy Templates tab, and then do one of the following:

     • To add a new policy template:

       1. Click the Add Policy Templates From List button. The Add Policy Templates From List dialog box opens.

       2. Click the  New Item button, and then click the Add New Policy Template or the Add New Policy Template (Raw Mode) button. The Select Type for New Policy Template dialog box opens.

       3. Select the appropriate type <DataType> from Perl Script, and then click OK.

     • To edit an existing policy template, click the policy template in the list, click the button, and then click the Edit Policy Template or the Edit Policy Template (Raw Mode) button.

     The Operations Connector High Availability policy editor opens.

     The Perl Script policy editor opens.

• To open the editor from the Policy Templates manager:

  1. Open the Policy Templates manager:

     Administration > Monitoring > Policy Templates

     Alternatively, click Policy Templates.

  2. In the Policy Template Groups pane, expand Policy Management > Templates grouped by type.

  3. Depending on the type of data collected by the particular policy, expand Configuration, Events, Generic, Metrics, or Topology. Each policy type can be used only for a subset of the available data types.

  4. Click the <DataType> from Perl Script item in the appropriate folder, and then do one of the following:

     • To add a new policy template, in the Policy Templates pane, click the button, and then click the Add New Policy Template or the Add New Policy Template (Raw Mode) button.

       The New <DataType> from Perl Script policy editor opens.

     • To edit an existing policy template, click the policy template in the Policy Templates pane, click the button, and then click the Edit Policy Template or the Edit Policy Template (Raw Mode) button.

       The Edit <DataType> from Perl Script policy editor opens.

• The integrated product is properly configured for integration with OMi. For more information, see the Integrate section.

• The certificate request from the integrated product is approved in OMi.

• The integrated product is configured as a connected server in OMi.

Collecting and processing data

that are passed to it.

During the execution of the script, the agent initializes an embedded Perl interpreter (the HPE Operations Agent Perl runtime), and passes all provided parameters to the Perl subroutine. The subroutine then collects and processes the data.

Perl scripts cannot be executed in parallel.

Passing data to policies

Before the subroutine exits, all data to be passed to the agent must be present in the transfer data structure. This data structure must be an array of hash references and available as a global variable in the Perl script. You can define the name of this array, but it must match the name that you specify in the policy configuration.

Each hash inside the array indicates a single record of information. The hash is formed by pairs of an attribute name (the hash key) and a value, both represented as strings. In the OMi terminology, the attribute name is an input property and can be accessed as <$DATA:<AttributeName>> in set operations and as '<AttributeName>' in conditions.

Assuming that the hash %BASIC_METRIC_DATA, which you use to pass data to the agent, contains the following attribute names:

my %BASIC_METRIC_DATA = (
    "counter_name"  => "<Value>",
    "counter_value" => "<Value>",
    "time_measured" => "<Value>"
);

In this case, the input data properties are:

<$DATA:counter_name>

<$DATA:counter_value>

<$DATA:time_measured>

If the execution is successful, the subroutine should return 0. Any other value indicates an error in the script execution and is logged to system.txt.

A custom variable consists of a map name, a key attribute name, and one or more source and target value pairs. For example, you can assign the data key name Severity to the map name mapSeverity, and add a source value of 2. You can then assign the target value Critical to the variable so that the agent inserts the value Critical into the event in all places where the variable is used.

Perl attribute key names use the following syntax: <$DATA:<AttributeName>>

where <AttributeName> is the data key name in a Perl hash array.

The key field mapping consists of an input field qualifier, an eligible field name, and a mapped field name. To map the key field, map the eligible field name to the mapped field name. The eligible field name is automatically extracted from the input field qualifier.

Perl script policies integrate unstructured data. Therefore, the eligible field name is identical to the input data qualifier.

You can add additional fields to data that is sent to Data Forwarding targets. Additional fields are simple key-value pairs and you must manually add both the keys and values. If a defined key field name equals a field name in the mapped data set, it is discarded.

The actual field value can consist of user defined strings and data references to the input data (<$DATA:…>).

Example:

The data references in the additional field combined_text are replaced when the policy is run. In the above example, after the variables are replaced, the resulting value in the field combined_text is:

At 12/05/2015 14:01:39, Monitoring: Threshold violation detected an substantial impact on system performance. This has happened 8264 times.

Note that data references must refer to the input format, not the mapped format.

In the Perl Script policy editor, follow the steps:

1. In the Properties page, define general policy information.
   

   Type the name of the policy in the Name text box.

   Optional. Provide a description of the policy (Description), select the instrumentation that will be deployed with the policy onto the host system where the agent is running (Instrumentation), and select the operating systems with which the policy is compatible (OS Types).

   For more information, see Properties Page.

2. In the Source page, define the path to an external script or embed a script by either uploading it into the policy or manually typing it in.
   

   Additionally:

   • Define the script polling interval.

   • Provide the name of the subroutine that is executed.

     The name of the subroutine must match the name of the subroutine in the Perl script.

   • Optional. Provide a list of parameters that are passed to the subroutine. Click to add a new parameter and to remove it.

     The parameters can be saved to the policy encrypted and are decrypted only before the subroutine is called. To encode the parameter values, right-click the parameter and select the option Encode as password.

   • Define the result data array name.

     The name must match the name of the result data array name in the subroutine.

   • Provide a list of result data key names. Click to add a new key name and to remove it.

3. In the events and metrics policies, in the Mappings page, configure mappings of the gathered attribute keys to custom variables.

   1. Create custom variables.

      Drag the data keys from the Data key names list to the Map Name column. The policy editor automatically adds the default prefix map to the map name and inserts the corresponding input data property.

      Alternatively, click above the Map Name column and type a data key name in the map name field.

   4. Add source and target value pairs to each custom variable.

      • Click above the Source Value column and type the source and target values in the corresponding fields.

      • Optional. In the Indicators tab, add indicators to the source or target value fields. After loading the indicators from the OMi server, the Indicators tab shows a hierarchy of configuration item types with the associated health indicators (HIs) and event type indicators (ETIs).

        To insert an indicator in a source or target value field, drag the indicator state (for example, HTTPServer:Normal) from the Indicators tab and drop it on the corresponding field.

      • Optional. In the Policy Variables tab, add policy variables to data attributes. The agent replaces the variables with the appropriate values in the generated data.

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

4. In the generic output data policies, in the Mappings page, configure mappings for key fields.

   1. Create key field mappings.

      If keys derived from input data are available, drag an input data property from the Meta Data list to the Input Field Qualifier column. The policy editor automatically extracts the eligible field name.

      Alternatively, click above the Input Field Qualifier column and type the qualifier name in the corresponding field.

   2. Optional. Change the Keep All Input Fields setting. By default, the option is selected and all fields are kept, regardless whether they are mapped or not. To keep only the mapped fields, clear the option.

   3. Add any additional fields as required.
5. Optional for events. In the Defaults page, configure default settings for all events collected by the policy.

   Note The default values configured in this page:

   • Apply only to a subset of event attributes. You can configure defaults of other attributes within individual policy rules.

   • Affect new as well as already existing rules. You can override the defaults in individual policy rules. If a rule contains empty event attributes, the agent will use the defaults for incoming events.

   1. Click Event Attributes to define default event attributes, such as severity and category.

      In the strings that define event defaults, you can use indicators, policy variables, and policy parameters.

      Tip After loading the indicators from the connected OMi server, the Indicators tab shows a hierarchy of configuration item types.

      To insert an indicator, drag the indicator with its state from the Indicators tab to the policy.

      To insert an indicator, drag the indicator from the Indicators tab to the policy. The policy editor inserts the indicator name.

   2. Click Event Correlation to set the type of duplicate event suppression and define the method used to suppress duplicate events.

   3. Click Custom Attributes to add additional information to all events generated by this policy. For example, you might add a company name, contact information, or a geographical location to an event.

   4. Click Advanced to define default advanced attributes such as legacy OM attributes and agent MSI (Message Stream Interface) settings.

   5. Optional. Use the Data key names tab to drag data keys to the attribute boxes. Alternatively, you can type the name of the data key directly into the attribute box.

      Perl attribute key names use the following syntax:

      <$DATA:<AttributeName>>

      where <AttributeName> is the data key name in a Perl hash array.

      The agent replaces the data key at runtime with the value of the specified data key.

      Note The Data key names tab is empty if no result data key names have been specified in the Source page of the Perl Script policy.

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

      Mappings are custom variables that you define in the Mappings tab (see also Configure Perl Script Policies). The default name of the mapping variable is map<AttributeName>, for example mapSeverity.

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

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

      • Input Data Property list item: <$DATA:<AttributeName>>

        For example, the custom variable mapSeverity has the <$DATA:Severity> input data property, where Severity is the name of the hash key value.

   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.

      Note 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 with the associated health indicators (HIs) and event type indicators (ETIs).

   9. Optional. In the Policy Variables tab, add policy variables to data attributes. The agent replaces the variables with the appropriate values in the generated data.

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

6. Optional for metrics. In the Defaults page, configure default settings for all metrics collected by the policy.

   Note You can use the default values configured in this page when defining the policy rules on the Rules page, where you can also override them.

   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 Data key names tab to drag data keys to the attribute boxes. Alternatively, you can type the name of the data key directly into the attribute box.

      Perl attribute key names use the following syntax:

      <$DATA:<AttributeName>>

      where <AttributeName> is the data key name in a Perl hash array.

      The agent replaces the data key at runtime with the value of the specified data key.

      Note The Data key names tab is empty if no result data key names have been specified in the Source page of the Perl Script 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 (see also Configure Perl Script Policies). The default name of the mapping variable is map<AttributeName>, for example mapSeverity.

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

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

      • Input Data Property list item: <$DATA:<AttributeName>>

        For example, the custom variable mapSeverity has the <$DATA:Severity> input data property, where Severity is the name of the hash key value.

   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.

      Note 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 with the associated health indicators (HIs) and event type indicators (ETIs).

   6. Optional. In the Policy Variables tab, add policy variables to data attributes. The agent replaces the variables with the appropriate values in the generated data.

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

7. In the events and metrics policies, in the Rules page, define policy rules.

   Events policies:

   Rules define the action a policy should take in response to a specific type of incoming event. 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 event data that the agent 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.

   Metrics 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 the agent 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 define policy rules, follow the steps:

   1. In the Policy Rules list, click the button, and then select an appropriate value. For more information, see Policy Rules List.

   2. Click Rule Description and type a brief description of the rule.

   3. In the Rule Content section, use the Condition tab to define values that you want the policy to search for in the incoming data. If the policy finds a match, it may or may not generate output data record, depending on the rule type.

      1. Click to create a new condition. New conditions by default use the equals operator.

      2. Click to expand the new condition.

      3. In the Property field, specify the attribute key that the policy searches for.

         If keys derived from input data are available, you can drag and drop the input data property from the Data key names list to the Property field.

      4. Select the pattern operator.

         If you select the matches operator, you can type a pattern in the Operand field.

      5. In the Operand field, type the value or pattern that you want the policy to compare with the data key value. If keys derived from input data are available, you can drag the value from the Data key names list and drop it in the Operand field.

         Tip For matching patterns, you can use standard pattern-matching rules of the agent. Select the matches operator and click the icon in the Operand field to open the pattern matching toolbox window. The toolbox includes the following sections:

         • Pattern Matching Expressions. Click an expression to insert it into the Operand text box.

         • Variable Bindings Options. Variable binding options include the setting of case sensitivity check and the field separators used in the rule. If you do not specify the pattern matching options for the rule, either the defaults (enabled case sensitivity check; the space and the tab character as the separators) or the default options set for the policy are used.

      For further details, see Condition Tab.

   4. Optional. In the Rule Content section, click any of the tabs except the Condition tab, and then click the Pattern Matching Variables tab to add variables created through 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 it from the Pattern Matching Variables list to the event/metric attribute.

   5. Optional for events. If you are creating a rule of the "Event on matched rule" type, set attributes for events that you want the policy to send. You can override the default event attributes here. You can also enter instructions that help operators handle the associated event (or add the name of the instruction text interface in order to retrieve event instructions from an external source), and configure actions to solve problems automatically or manually.

      In text boxes, you can specify sample data, mappings, pattern-matching variables, indicators, policy variables, and policy parameters.

      For details, see Event Attributes Tab, Event Correlation Tab, Custom Attributes Tab, Instructions Tab, Advanced Tab (Default Event Attributes), and Actions Tab.

   6. Optional for events. Use the Event Attributes tab to define event attributes (for example, event title and description) for all events generated by this rule.

      Tip After loading the indicators from the connected OMi server, the Indicators tab shows a hierarchy of configuration item types.

      To insert an indicator, drag the indicator with its state from the Indicators tab to the policy.

   7. Optional for events. Use the Event Correlation tab to set the type of duplicate event suppression and define the method used to suppress duplicate events.

   8. Optional for events. Use the Custom Attributes tab to add additional information to all events generated by this rule. For example, you might add a company name, contact information, or a city location to an event.

   9. Optional for events. Use the Advanced tab to define an event drill-down URL, legacy OM attributes, and agent MSI (Message Stream Interface) settings.

   10. Optional for metrics. If you are creating a rule of the "Store on matched rule" type, set the attributes (basic or advanced) for metrics that you want the rule to override. All metrics on the Basic tab are required. Advanced attributes are optional. If default attributes are specified in the Defaults tab, you can use the defaults or you can override them as described below.

       In text boxes, you can specify sample data, mappings, pattern-matching variables, indicators, policy variables, and policy parameters.

       For details, see Basic Tab and Advanced Tab (Default Metric Attributes).

   11. Optional. Use the Data key names tab to drag data keys to the attribute boxes. Alternatively, you can type the name of the data key directly into the attribute box.

       Perl attribute key names use the following syntax:

       <$DATA:<AttributeName>>

       where <AttributeName> is the data key name in a Perl hash array.

       The agent replaces the data key at runtime with the value of the specified data key.

       Note The Data key names tab is empty if no result data key names have been specified in the Source page of the Perl Script policy.

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

       Mappings are custom variables that you define in the Mappings tab (see also Configure Perl Script Policies). The default name of the mapping variable is map<AttributeName>, for example mapSeverity.

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

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

       • Input Data Property list item: <$DATA:<AttributeName>>

         For example, the custom variable mapSeverity has the <$DATA:Severity> input data property, where Severity is the name of the hash key value.

   13. 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 eventmetricevent or metric attribute.

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

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

   15. 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 with the associated health indicators (HIs) and event type indicators (ETIs).

   16. Optional. In the Policy Variables tab, add policy variables to data attributes. The agent replaces the variables with the appropriate values in the generated data.

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

8. Optional for events and metrics. In the Options page, set additional policy options.
   

   In this page, you can:

   • Configure which rule matching actions are logged by the policy

   • Define how the integrated agent behaves on unmatched events or metrics

   • Set the pattern matching options

   For details, see Options Page.

9. Click Save and Close to save the policy template and exit the dialog.

• To start troubleshooting, check the log files of the agent in the %OvDataDir%log directory (Windows systems) or the /var/opt/OV/log directory (Linux systems).

• To investigate issues related to policy execution, first examine the %OvDataDir%log\System.txt file (Windows systems) or the /var/opt/OV/log/System.txt file (Linux systems).

  Note The log files whose names start with the opr- prefix are generated by the OMi web console.

The Defaults page enables you to set default attributes for all events that a policy sends. The event defaults only affect new rules. You can override the defaults for individual rules.

For details, see Event Attributes Tab, Event Correlation Tab, Custom Attributes Tab, Instructions Tab, Advanced Tab (Default Event Attributes), and Actions Tab.

The Defaults page enables you to set default attributes for all metrics that a policy sends. The metric defaults only affect new rules. You can override the defaults for individual rules.

For details, see Basic Tab and Advanced Tab (Default Metric Attributes).

Specify if you want the instructions to accompany the event.

Events generated by a policy can include instructions that explain what to do when the event is generated. This instruction text can often help an operator to solve a problem when a particular type of event is received. The operator can view the instructions included with an event by checking the Event Details pane in the Event Browser. You can define default instructions for all rules in a policy. You can also override the default with different instructions for any rule.

The Rules page enables you to define one or more policy rules.

For details, see Policy Rules List, Condition Tab, Event Attributes Tab, Event Correlation Tab, Custom Attributes Tab, Instructions Tab, Advanced Tab (Default Event Attributes), and Actions Tab.

The Rules page enables you to define one or more policy rules.

For details, see Policy Rules List, Condition Tab, Basic Tab, and Advanced Tab (Default Metric Attributes).