Configuring Text Files

This topic provides information about configuring the text files by using the TrueSight console and the Central Monitoring Administration console. 

Configuring search string criteria video

This video helps you configure numeric search criteria in BMC PATROL for Log Management KM. 

Defining numeric search criteria video

This video helps you configure numeric search criteria in BMC PATROL for Log Management KM. 

Click Add to configure text files for monitoring.

Configuration details


Field
Description
Label for new file to be addedSpecify the name of the label for the log file that you want to start monitoring.
Logical name

Specify the logical name of the instance that you want to monitor. Maximum 80 characters are supported in this field.

File name

Specify the full path and the filename for the file that 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. Maximum 900 characters are supported in this field.

Path contains environment variables

Select this 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 path is treated as a pure file name.

Advanced Settings

File disposition

Select ALL option 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.

Scan priority

The KM has three predefined collection intervals which can be set by configuring the Scan Priority field. This field displays the priority level at which you want the instance to be scanned.

The priority-collection interval mapping:

Scan Priority

Predefined Data Collection interval

Normal

2 minutes                        

Medium

10 minutes

Low

30 minutes

  • Normal is associated with the LogMainColl and LogRemoteMainColl collectors. Select this option to scan the file every 2 minutes.
  • Medium is associated with the LogMainCollP2 collector. Select this option to scan the file every 10 minutes.
  • Low is associated with the LogMainCollP3 collector. Select this option to scan the file every 30 minutes.

If you want to change how often the file is scanned, change the polling time of these collectors. The default scan interval is 2 minutes.

Note: You cannot select a value other than Normal for remote log instances. Attempting to do so will result in an error message.

Setting a custom collection interval:

You can set a none-default value also known as, custom collection interval, for each of the above priority values.

  1. Navigate to your Log Management KM policy and select the Polling Intervals tab.
  2. Click Add Polling Interval.
    1. In the Monitoring solution field, select Log Management.
    2. Select the version.
    3. Select the Monitor Parameter as per your requirements. For more information, refer Scan priority, collection interval, and collection timeout table.
    4. Set the polling interval of the monitor parameter with the custom collection interval.

    5. Save the policy.

Scan priority, collection interval, and collection timeout table

Priority

Monitor Parameter

Predefined Data Collection
interval

Collection timeout

Normal

LogMainColl

2 minutes

8 minutes

Medium

LogMainColl2

10 minutes

13 minutes

Low

LogMainColl3

30 minutes

33 minutes

Note: If you are using Log Management KM prior to version 2.7.30, ensure that the predefined data collection interval value does not exceed the collection timeout value.

Generate alarm if file not modified

Select this check box if you want the 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.

Backup file nameSpecify the name of the backup file.
If no match on the next scan return to OK

Select this checkbox iIf 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.

Text Settings

Expand the Text Settings frame for configuration.

FieldDescription
Number of lines in log entry

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.

Nullify Alarm/Warn String

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


Always read at beginning

Select this check box if you want to scan the entire text file on each scan, rather than scanning only the new content.

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

File read position

Select the read position of a file after PATROL Agent is re-initialzed or when a new file matches the file path.

  • Read from last offset - Log file reads from the last offset
  • Read from end of file - Log file reads from the end of the file
  • Read from beginning of file - Log file reads from the beginning of the file
  • Use existing configuration -  Log file is read from the last offset

Multiline Search

Expand the Multiline Search frame to configure the start and end delimiters.

FieldDescription
Start delimiterSpecify the start limit to search a block of lines containing a match string.
End delimiterSpecify the end limit to search a block of lines containing a match string.

Remote Monitoring

Expand the Remote Monitoring frame to add a remote host for monitoring.

Remote hostname: Specify the hostname for remote monitoring. This field is applicable only for UNIX and Linux platforms. UNIX KM must be installed and the Remote Monitoring policy must be defined.

Search Criteria Settings

Pattern Search Criteria: Click  to configure a Pattern Search Criteria for the configured file. 

FieldDescription
Search Criterion
Search Identifier NameSpecify a unique label in the Search Identifier Name text box and configure a search string to define what type of messages the KM should search for.
Search String 1
NOT

(Optional) Select this checkbox if you want the KM to alarm if a string is not present in the file.

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

String

In the String 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, {Job started} {Job stopped} {Job aborted}.

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 Add Polling Intervals option. 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 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}.
Search String 2
NOT

Select this check box if you want to identify log files in which the string is not found.

For example, if we enter ERROR and FATAL as the search strings, the KM searches for the word ERROR AND FATAL at the same line.

StringEnter the second search string or regular expression.
Number Search
First numberSpecify a number to specify a starting position of a search range in the matched file.
Op

Select the operator from the operator list.

  • <
  • <=
  • =
  • >=
  • >
  • !=
Second numberSpecify a number to specify an ending position of a search range in the matched file line.
Op

Select the operator from the operator list.

  • <
  • <=
  • =
  • >=
  • >
  • !=
Begin tokenSpecify a valid beginning token value.
End tokenSpecify a valid ending token value.

Search Criteria Event Handling Configuration: Expand the frame to add a search criteria for handling events.

FieldDescription
Override default setting

Select this checkbox to custom-define the settings for each search criterion.

You can custom-define a search criterion with settings that are different from the default settings. To do so, select the Override default setting check box and custom-define the settings for each search criterion.

Threshold # 1Specify the minimum number of text search string matches in a polling cycle required to produce a specified state.
Threshold # 1 state

Select the state that you want the KM to exhibit when a threshold is reached.

    • None
    • Ok
    • Warn
    • Alarm

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

Threshold #2Specify 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.
Threshold # 2 state

Select the state that you want the KM to exhibit when a threshold is reached.

    • None
    • Ok
    • Warn
    • Alarm
Custom event messageSpecify 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.
Custom event origin

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.

Ignore duplicate events for next (mins)

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.

Default Settings For Search Criteria
Threshold # 1

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.

Threshold # 1 state

Select the state that you want the KM to exhibit when a threshold is reached.

    • None
    • Ok
    • Warn
    • Alarm

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

Threshold #2

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.

Threshold # 2 state

Select the state that you want the KM to exhibit when a threshold is reached.

    • None
    • Ok
    • Warn
    • Alarm

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

Custom event message

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.

Custom event origin

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.

Modifying this field affects the generated custom event origin causing the event to not be associated with the LOG instance level in the Central Monitoring Administration console.

Ignore duplicate events for next (mins)

Specify the time threshold for which the duplicate events will be ignored. You can also modify the default search criterion settings after you configure the instance.

OKClick to save the configuration.
CloseClick this button to exit without saving any changes.

Was this page helpful? Yes No Submitting... Thank you

Comments

  1. Daric Smith

    When specifying search strings I can't tell if there is an OR or an AND. 

     

    If I have Search string 1 populated with ERROR, if I populate search string 2 with "find this text" does that mean the entry has to be "ERROR" AND "FIND THIS TEXT"?  Or does it mean the line in the log file has "ERROR" OR "FIND THIS TEXT"?

     

    Nov 18, 2015 08:11
    1. Shweta Patil

      Hello,

      Apologies for the inconvenience caused.

      The entry has to be "ERROR" AND "FIND THIS TEXT".

      I have added an example that explains the query.  

      Thanks,
      Shweta 

      Sep 28, 2016 01:42
  2. Ivan Luna

    Is a waste of time to configure multiple string searches to create Proactivenet events because this configuration only generates Patrol events, if you configure one or more string searches with their own id, threshold, custom message, multiple Patrol events are generating well, but an unique bppm event is generating for "Number of Matches Per Scan Cycle" parameter

    Jun 29, 2016 12:41
  3. Marcus Karlsson

    Please clarify the difference between Read from last offset and Use existing configuration.

    They both have the same/similar description " Log file reads from the last offset" / "Log file is read from the last offset" In fact the correct description for "Use existing configuration" is given in Truesight it uses the setting of /PMG/CONFIG/instanceName/actInitialReadEOF, if that is not set it reads from end of file.

    Oct 24, 2018 03:27