Monitoring a text instance

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 Product Short PATROL Configuration Manager plug-in as described in PATROL Agent Configuration Variables.

To monitor a text instance

1. Access the LOG application menu as described in Accessing Menu Commands, InfoBoxes and Online Help.
2. Select Add Instance.
3. In the Add Instance dialog box, enter a label for the log file that you want to start monitoring.
   The log icon label must be 50 characters or less and cannot contain any spaces.
4. Click Accept.

5. In the File/Pipe Name text box on the Add File for Label: instanceNamedialog box, enter the full path and file name for the file you want to monitor.

   Note

   • To monitor log files that have dynamic names, use the * and ? regular expressions to define the file name. For example, if a log file is named backup_date.log, where date changes each day, enter the log file name as backup_.log.*
   • Regular expressions are not accepted for named pipes.
   • For more information about using regular expressions, see Regular Expressions.
6. Enter a logical name for the LOGMON instance that you want to monitor, which appears in the event manager.
7. Select the ContainsEnvironmentalVariables check box to enter a path defined by an environment variable that is resolved at run time. If you select this check box, environment variables in the text file path are resolved. Otherwise, the text file is treated as a pure file name.
8. Select Text File as the File Type option.
9. In the Filter Program text box, enter the path and name of the filter program that is reading the file specified in the File/Pipe Name field.

10. (Optional) If you want to scan the entire text file on each scan, rather than scanning only the new content, choose the Always Read at Beginningcheck box.

    Note

    The text file will only be scanned if the file changes.

11. (Optional) If you are monitoring a dynamically named file and you want to monitor all of the files using the dynamic name specified in the File/Pipe Name field, rather than just the latest file, choose the All option.
12. (Optional) Select the Generate ALARM if file not modified in check box if you want the LOGMON instance to generate an alarm if the monitored file is not modified periodically. Specify the time in minutes after which you want the KM to alarm if the file is not modified, in the minutes text box.
13. Specify the default settings for a search criterion, as follows:
    1. In the Threshold #1 text box, specify the minimum number of text search string matches in a polling cycle required to produce a specified state.
       
       To search for a minimum number of text strings across a number of polling cycles, enter values in the x : y format; x represents the minimum number of text string matches, and y represents the total number of polling cycles.
    2. In the Threshold #2 text box, specify the minimum number of text search string matches required to produce a specified state. You can specify a different state and a different number of matches from Threshold #1. Threshold #2 should be higher than Threshold #1. To search for a minimum number of text strings across a number of polling cycles, enter values in the x: y format.

    3. Select the state that you want the KM to exhibit when a threshold is reached - NONE, OK, WARN, or ALARM.

       Example

       If you want the KM to go into alarm when the search string is found 3 times in the monitored file, then you would set the value of Threshold #1 to 3 and select Alarm from the State list.

    4. (Optional) In the Custom Event Message text box, specify the message that you want to be displayed in the events when your search string conditions are satisfied.
       
       For more information, see Customizing event messages.
    5. In the Custom Event Origin text box, specify the customized 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.textFileName.
       
       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 Built-in macros.
       
       For more information, see Generating a custom event when a search string is found in the file and Generating an alarm based on file age .

    6. In the Minutes text box, specify the time threshold for which the duplicate events will be ignored.

       Note

       You can also modify the default search criterion settings after you configure the instance. For more information, see To modify the default search criterion settings for an instance .

14. In the Number of Lines in Log Entrytext box, specify the number of lines that you want to be displayed when a match is found.

    Example

    If you want to determine when a disk is full and where the disk is mounted, you would enter Error: Disc Full as the search string and 2 as the value of Number of Lines in Log Entry so that when a disk is full, the product displays a message similar to the following one in LOGMatchString text parameter:
    Id=id1
031605: Error: Disc Full
Id=;MatchedLines
/hd001 mounted as /opt
SUMMARY:id1=1;

    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.

15. 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 Criteria: instanceName: Define Search Criterion 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).

    Example

    If you specify Alarm up in the String1 text box and Alarm down in the Nullify Alarm/Warn String text box, the KM goes into an alarm state when Alarm up is found in the monitored file and the alarm is nullified when Alarm down is found in the monitored file.

16. If the KM goes into an alarm or a warning state because the search string is found and you want the KM state to return to OK if the search string is not found on the next scan, select the Return to OK if no match found on next scan check box.

17. From the Scan Priority list, select a scan priority: Normal, Medium, or Low.

    Note

    Do not select a value other than Normal for remote log instances.

18. Click Next.

19. (Optional) In the Configure Search Criteria: instanceName: Define Search Criterion dialog box, in the Search Criterion area, define a search criterion, specify a unique label in the Search Identifier text box, and configure a search string to define what type of messages the KM should search for.
    The Search Identifier label appears in the search list and helps you identify the search criterion.

    Note

    • You can view the search patterns of the configured search criterion for the instance by using the Report Configuration menu command. For more information, see Viewing search criteria for an instance.
    • You can also modify individual search criterion for an instance after you configure the instance. For more information, see To modify individual search criteria for an instance.
20. In the String1 text box, enter one of the following:
    • First search string that you want to search in the text instance
    • Regular expression for the first search string that you want to search in the text instance (4096-byte limit)

    • Search pattern (s). Each search pattern should be a valid regular expression and should be enclosed in parentheses ({}). For example, .

      Note

      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 the number of polling intervals that you specify in the Polling Intervals text box on the Configure Search Criteria: instanceName: Override Default Settings dialog box. If all the search patterns are not found in the specified polling intervals, the KM generates an alarm.

      Note

      BMC does not recommend performing the following actions:

      • Entering multiple search patterns in the String1 text box, and selecting the Always Read At Beginning check box in step 10 simultaneously.
      • Entering a single search pattern in the String1 text box. The KM might not generate any alarm in this case. For example, {Job Started}.

21. (Optional) If you want the KM to alarm if a string is not present in the file, select the Not check box.

    Note

    This option displays all the lines in the file that do not match the search string.

22. In the String2 text box, enter the second search string or regular expression.
23. Select the Not check box next to the text box if you want to identify log files in which the string is not found.
24. In the First Number text box, specify a number to specify a starting position of a search range in the matched file.
25. Select an operator from the Op list.
26. In the Begin token text box, specify a valid beginning token value.
27. In the End token text box, specify a valid ending token value.
28. Select an operator from the Op list.
29. In the Second Number text box, specify a number to specify an ending position of a search range in the matched file line.
30. Click Next.
31. In the Configure Search Criteria: instanceName: Override Default Settings dialog box, you can custom-define a search criterion with settings that are different from the default settings in the Add File for Label: instanceName dialog box. To do so, select the Override default setting check box and custom-define the settings for each search criterion as described in step A through step F.
32. In the Generate ALARM when pattern not found within..Polling Intervals text box, specify the number of polling intervals after which an alarm should be generated if the search patterns are not found within those polling intervals.
33. Click Next.
34. In the Configure Search Criteria: instanceName: Summary dialog box, do one of the following:
    • To define more search criterion for the instance, select the Add option, and click Update.
    • To delete a search criterion, select the search criterion, select the Delete option, and click Update to delete the search criterion.
    • To modify a search criterion, select the search criterion, select the Modify option, and click Update to modify the search criterion.
35. Select the Discard changes option if you want to revert all changes made in this dialog box and use the original Search list.

36. Click Finish.
    PATROL adds the new log file name to the list of monitored files and displays the new log instance in the Desktop tree tab.
    Once the search string is found in the file, the KM generates an alarm. For more information about configuring search strings, see Monitoring a file for a particular string or Monitoring a file for multiple search criteria.

    Note

    If you do not specify a search string, the LOGErrorLvl parameter will not be set. When the LOGErrorLvl parameter is not set for a period of time, "no data for specified range" messages are displayed in BMC PATROL history. If you did not specify a search string, this message is benign.

37. (Optional) If you want to further configure the log file, access the LOGT application menu as described in Accessing Menu Commands, InfoBoxes, and Online Help.
38. Select Advanced Features > Configure Size Actions to configure automatic recovery actions to determine how the KM should respond when the file reaches a defined size.
    For more information, see  To configure a recovery action for a log file based on file size.
39. (Optional) Select Advanced Features > Schedule Log Scan to configure the KM to scan the file at different schedules.
    For more information, see  To schedule a file scan .
40. (Optional) Select Advanced Features > Configure Log Monitoring Blackout to prevent the KM from generating events for a file for a specified period of time
41. (Optional) Select Advanced Features > Configure Alarm to configure an alarm when the size of the monitored file exceeds a specified threshold

42. (Optional) Select Advanced Features > Multiline Search to configure limits to search a block of lines containing a match string.

    Note

    This option is not available if you are monitoring an XML file.

    PATROL updates the configured log file instance in the list of monitored files and displays the log instance in the Desktop tree tab.