Configuring the search string for an XML instance

This task describes how to define a log file search string. The product allows you to define what type of messages PATROL should search for and how PATROL should respond when it locates a defined search string. It also allows you to define multiple search criteria for an instance. 
When you define a search string and associate it with a log file, the KM monitors the log for the following:

• text string or pattern specified in the search string
• number of string matches per scan of the log file
• corresponding alert severity (OK, WARN, or ALARM) when the specified string or pattern is found

To configure a search string for an XML file

1. Access the LOG application menu as described in Accessing KM menu commands.
2. Select
   • Add Instance to add and configure a new search string. Enter the label for the new file.
   • Modify > Default Settings or Modify > Search Criteria to reconfigure an existing search string and select the label for the file that you want to change.
3. Click Accept.
4. In the Add-File-for-Label-instanceName-dialog-box, enter a name in the File/Pipe Name text box. If you are in the Change-File-for-Label-instanceName-dialog-box, the File/Pipe Name field is already populated, based on your label selection in the previous dialog box.
   If you are in the Change File for XML Monitoring dialog box, the XML File field is already populated, based on your label selection in the previous dialog box.
5. Specify a logical name for the LOGMON instance that you want to monitor, which appears in the event manager.
6. Select the Contains Environmental Variables check box to enter a path defined by an environment variable that is resolved at runtime. If you select this check box, environment variables in the XML file path are resolved. Otherwise, the XML file is treated as a pure file name.
7. Select either of the File Type options: Text File, Script, Named Pipe, XML File or Binary File.

8. If needed, identify a Filter Program. A filter program, may be needed to read a file type, such as a binary.

   Warning

   Note

   In case of a Binary file type, PATROL KM for Log Management does not accept arguments.

9. To always read the log file from the beginning, rather than the portion of the file that has been added since the last time the file was read, select Always Read at Beginning.

   Warning

   Note

   An XML file is scanned only if the file changes.

10. Select a File Disposition option.
11. Select the Generate Alarm if File not modified in check box to indicate how the LOGMON instance icons should act when PATROL finds the search string or matches the regular expression.
12. Specify the time threshold in the Minutes text box, after which the specified generate action will occur, if the file is not modified.
13. Specify the default settings for the search criteria. Enter the Match Count for Threshold #1 and #2 and select a State. The selected state option does not occur until the threshold count has been satisfied.
14. Select one of the following Stateoptions:
    • NONE – do not change
    • OK – place the icon into the ok state
    • WARN – place the icon into the warning state (yellow icon base)
    • ALARM – place the icon into the alarm state (red, flashing icon base)
15. Enter the Custom Event Message, if any, that you want to display when your search string conditions are satisfied.
16. Specify the origin for events. If you do not specify the origin, the product uses the instance name as the default origin of events, which is APPCLASS.INSTANCE.xmlFileName.
    You can use built-in macros (except the %x-y macro) as the customized origin for events. For more information about built-in macros, see Customizing event messages.
17. Specify the time threshold in the Minutes text box, for which the duplicate events will be ignored.

18. You can further customize responses by specifying the number of lines that you want to be displayed when a match is found in the Number of Lines in Log Entry text box.

    Warning

    Note

    If either, the search string or the nullify string, occurs again within the number of lines selected to be displayed, the KM does not find the instances of the search strings for all the search identifiers.

19. In the Nullify Alarm/Warn String text box, specify the string that is used to nullify the alarm for the dual search feature. You can configure dual search for an instance so that the KM goes into the alarm state when any of the search criteria is found in the monitored file and nullifies the alarm when the nullify string is found in the monitored file.
    
    You must specify the first string in the String1 text box (in the Configure Search Criterion: instanceName dialog box) and the nullify string in the Nullify Alarm/Warn String text box. For nullified customized events, the default custom event message is used (as provided in the Custom Event Message text box).
20. You can further customize responses by specifying the Number of minutes before next alert is generated and Override if matches exceed values in the Configure-Log-Monitoring-Blackout-dialog-box.
21. Select a Scan Priority.Click Continue.
22. In the Configure-Search-Criterion-for-XML-file-dialog-box, enter a unique identification label for a search criterion in the Search Identifier text box. This is unique to every search criterion and appears in the search list.
23. In the XML Search String text box, enter a combination of XML elements and values that you want to find in the monitored file. For configuring XML search strings, see Rules-for-entering-XML-search-strings.
    
    You can search for a literal word or phrase or you can search for a type of message that has an identifiable format or pattern. For more information about searching based on patterns, see Creating-regular-expressions.
24. Select the Override default setting check box to define the threshold, state, and event for a particular search criterion.
25. Enter the match count for Threshold #1 and Threshold #2 and select a State for each threshold.
26. Enter the Custom Event Message, if any, that you want displayed in the event, when your search string conditions are satisfied.
27. Specify the customized origin for events for the particular search criterion.
28. Specify the time threshold in the Minutes text box, for which the duplicate events will be ignored.
29. Select Add to include the defined search criterion in the Search list, and click Update to populate the search list.
    
    PATROL begins monitoring the XML file for the search string or regular expression that you specified. If the text string or regular expression is found, PATROL sets the icon for the log instance to the Alert Severity that you specified and sets the values of the LOGSearchString parameter and LOGErrorLvl parameter. In addition, the LOGMatchString parameter displays the matches found for all of the search criteria during the last scanning cycle.
30. Select Modify, and click Update to populate the search list. Select a criterion from the search list and click Update to populate the Search Criterion. Make the required changes in the Search Criterion section, and click Update to save the changes.