Monitoring a file for a particular string

The PATROL KM for Log Management allows you to define what type of messages the KM should search for. To filter the file for a particular type of message, you must define a search string for the monitored file. When you define a search string and associate it with a log file, the KM monitors the log for the following:

• Text or XML string, or pattern
• Multiple strings
• Multiple search patterns
• Numeric values
• 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

When the search string can consist of one or two regular expressions and/or a numeric comparison, PATROL combines the results of these three criteria to determine a match. The maximum length for a string is 4096 characters. For more information about using regular expressions, see Creating-regular-expressions. Once the search string has been defined, PATROL begins monitoring the file for the search string or regular expression that you specified. If the text string, XML string, or regular expression is found, PATROL sets the icon for the log instance to the alarm state that you specified and sets the values of the LOGSearchString parameter and LOGErrorLvl parameter. In addition, the LOGMatchString parameter displays the text string or regular expression that was returned by the log search.

In case you specify multiple search patterns, the KM searches for each search pattern in the log file in the order in which you have specified the search patterns. These patterns are searched for a particular number of polling intervals. If all the search patterns are not found in the specified polling intervals, the KM generates an alarm.

Before you begin

You must be using the PATROL Central Operator - Windows Edition, PATROL Central Operator - Web Edition, or a PATROL Console in Developer mode. You can also add a text file to monitor by using the PATROL KM for Log Management PATROL Configuration Manager plug-in as described in PATROL-Agent-configuration-variables.

Defining a search string for a text instance

To define a search string for a text instance

1. For a new text instance, do the following, and go to step 3:
   1. On the Add File for Label: instanceName dialog box, click Next to go to the Configure Search Criteria: instanceName: Define Search Criterion dialog box.
   2. Enter a unique identification label for a search criterion in the Search Identifier text box.
2. For an existing text instance, select the search criterion on the Configure Search Criteria: instanceName: Summary dialog box, select Modify and click Update.
3. Enter a search string, regular expression, or multiple search patterns in the String 1 text box. Select the NOT check box next to the String 1 field if you want to identify file entries in which the string is not found.
    You can search for a literal word or phrase or you can use regular expressions to search for a type of message that has an identifiable format or pattern. For more information about using regular expressions, see Creating-regular-expressions.
4. (Optional) In the String 2 text box, enter a search string or regular expression. Select the NOT check box next to the field if you want to identify files in which the string is not found.
5. (Optional) Define a numeric comparison by specifying the starting and ending positions of a search range in the matched file line, entering position numbers in the First Number and Second Number text boxes, along with operators in the Op text boxes. Enter valid Begin Token and End Token values. The numeric comparison is used to determine if a file entry exceeds a threshold or fits in a range. For example, you would use a numeric comparison to determine if the number of jobs in a print queue exceeds 500. To see how you would define a search string for this example, see Example: Defining a search string for print queue length.
    Tokens specify beginning and ending locations of the search within a matched file line. Valid values start at 1 and run from left to right. Multiple adjacent white spaces are treated as one position. Each white space-separated token in this search range is examined to determine if it is a base 10 number. This number must be a real number, not a percent. The first number encountered is used. If no numbers are found, the numeric portion of the search string is ignored. The converted number is used as variable X in this mathematical statement:
   
   A op1 X op2 B
   where:
   • A is the value entered in the First Number text box
   • op1 is the operator selected from the First Number field Op list
   • B is the value entered in the Second Number text box
   • op2 is the operator selected from the Second Number field Op list
      A is required; B is optional. op2 is not required unless B is supplied.
     op1 can be one of these operators:
   • less than, <
   • greater than, >
   • equal, =
   • less than or equal, <=
   • greater than or equal, >=
   • not equal to, !=
     op2 can be one of these operators:
   • greater than, >
   • greater than or equal, >=
6. Fill out or modify the rest of the dialog box fields as described in Monitoring a text instance.

Example: Defining a search string for print queue length

This example shows you how to define a search string that will monitor the print queue length in a log file to identify print queues with more that 500 jobs.

The sample log file contains entries like the following:

Print Queue HOU7 contains 323 jobs

Print Queue HOU19 contains 605 jobs

Print Queue HOU1 contains less than 10 jobs

To identify log entries that contain print queues with more that 500 jobs, you would define the search string as follows:

1. On the Add File for Label: instanceName dialog box, click Next to navigate to the Configure Search Criteria: instanceName: Define Search Criterion dialog box.
2. In the First number text box, enter 500.
3. From the Op list adjacent to the First number field, select <.
4. In the Begin token text box, enter 5.
5. In the End token text box, enter 7.
6. Fill out the rest of the dialog box fields as described in Monitoring a text instance.

Defining a search string for an XML file

To define a search string for a new XML instance or an existing XML instance that is being monitored:

1. For a new XML instance, do the following, and go to step 3:
   1. On the Add File for Label: instanceName dialog box, click Next to go to the Configure Search Criteria: instanceName: Define Search Criterion dialog box.
   2. Enter a unique identification label for a search criterion in the Search Identifier text box. This label appears in the search list and helps you identify the search criterion.
      
      The label must be unique for an XML instance. You can use the same search identifier in other XML instances, but not in the same XML instance. You can only use aplha-numeric characters such as a-z, A-Z, 0-9, and up to a maximum of 20 characters.
2. For an existing XML instance, select the search criterion on the Configure Search Criteria: instanceName: Summary dialog box, select Modify and click Update.
3. In the String1 text box, enter the 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.
4. Click Next and fill out or modify the rest of the dialog box fields as described in Monitoring an XML log instance.

 Example: Defining a search string for processes

This example shows you how to define a search string that will monitor an XML file with element structure.

The sample log file contains an element structure like the following:

To identify log entries for processes with ERROR

1. On the Configure Search Criteria: instanceName: Define Search Criterion dialog box, in the Search Identifier text box, enter ManagerInfo.
2. In the String1 text box, enter the following*:*
   <rec><level>ERROR</level><bmc_reg_ex>&</bmc_reg_ex> <procname>StartUpProcess</procname></rec>
    For configuring XML search strings, see Rules for entering XML search strings.
3. In the Threshold #1 text box, enter 1.
4. From the State list, select Alarm.
5. In the Custom Event Message text box, enter %1.
6. Fill out the rest of the dialog box fields as described in Monitoring an XML log instance.