Use this Knowledge Script to monitor an ASCII text file for specific strings and messages logged since the last monitoring interval. This Knowledge Script allows you to specify the file name, and a regular expression to identify the string to look for or to exclude. The script scans the ASCII file and reports the matching entries found since the last monitoring period. The script checks for changes to the text file that match the expression you enter; it does not re-scan the entire file at each interval unless it determines that the entire file is new (either because the new file size is smaller or because the cyclic redundancy check indicates there is a new file).
This Knowledge Script reads the entire file to find matching strings the first time it executes. The AsciiLog Knowledge Script tracks the last item read in the file persistently. If the Knowledge Script restarts, it is treated as the first iteration. Because the file it is monitoring has already been read before, the first iteration (that is, after restart), starts reading the file from where the marker stopped before it restarted.
You can configure the script to ignore any ASCII log entries that were generated while the computer was in maintenance mode.
You can also configure the script to perform a cyclic redundancy check (CRC) on the file for the purpose of determining when a file has been replaced rather than appended. If the original file has been replaced by a file of the same size or by a larger file, the CRC exposes that change and cause the script to parse the entire new file.
If the file is recreated between intervals and the file size is smaller than the previous version of the file, the script treats it as a new file and searches it from the beginning.
The script raises an event if the number of lines matching your search criteria exceeds the threshold you set, or if the file is missing.
Scanning a large log, bigger than 1 GB for example, might use more operating system resources than you want this script to use. If that happens, reduce the size of the log.
NOTE:To specify the include and exclude patterns, you need to be familiar with Perl regular expressions. Some information is available in the topic Section 4.1, Creating Filters with Regular Expressions.
You can use this script to monitor any text file the UNIX agent has permission to read. If the UNIX agent runs under a specific user name rather than root, ensure that user account has read permission for the files you want to monitor.
UNIX computer icon
The default interval for this script is Every 30 minutes.
Set the following parameters as needed:
|
Description |
How to Set It |
|---|---|
|
Event? (y/n) |
Set to y to raise events for the ASCII log. The default is y. |
|
Event if log missing? (y/n) |
Set to y to raise an event if the log is missing. The default is y. |
|
Event if log file list changed? (y/n) |
Select y to raise an event if the number of log files changes, for example, if a new file is added. The default is y. |
|
Create event for each matching line? (y/n) |
Select y to raise a new event for each line that meets the event criteria. The default is n, no event is created. |
|
Do you want to limit the number of matching lines returned? (y/n) |
Select y to limit the number of lines from the log file matching the search criteria that is returned from a single job iteration. The default is no. If you are expecting numerous matches, enable this limit. Console performance might be adversely affected by jobs that return a very large number of matches Use the Maximum number of matching lines to return parameter to specify a limit. |
|
Maximum number of matching lines to return |
Enter the maximum number of lines, from 0 to 9999, from the log file matching the search criteria to be returned from a single job iteration. This limit avoids a degradation in performance in cases where many lines match the search criteria. To set a limit here, you must enable the Do you want to limit the number of matching lines returned? parameter. The default is 500 lines. |
|
Parse the log file the first time? (y/n) |
Select y to parse the file for the strings you have identified the first time the script runs. Subsequent iterations of the script measure any differences between this version of the file and any subsequent versions. If you select n, the first iteration of the script reads the file and inserts a marker at the end. Subsequent iterations of the script then measure differences in the script from this point forward. The default is n. |
|
Create events for lines generated during maintenance mode? (y/n) |
Select y to have AppManager report events for ASCII log entries that were created when the computer was in maintenance mode. If you select n, AppManager ignores all ASCII log entries created while the computer is in maintenance mode. The default is y. |
|
Collect data? (y/n) |
Select y to collect data. The script returns the number of lines containing matching strings. The default is no data is collected. |
|
File names to parse (full path, UNIX-like shell pattern matching notation and comma-separated) |
Enter the full path to the file you want to monitor or a regular expression representing the file. You can enter multiple files, comma separated without spaces. An event is created when the file is not found, and when files matching the description are added or deleted since the previous job. For example: /tmp/applog.log,/\/var\/log\/netlog[0-9]/ The UNIX agent must run as an account that has permission to read the file. If you restrict read access on files, you might need to change the account the UNIX agent uses. The default is /etc/hosts. |
|
Maximum number of log files to parse (value 0 equals infinite) |
Enter the maximum number of log files, from 0 to 100, that you want to monitor. This limit avoids a degradation in performance in environments with numerous large log files. Enter 0 if you want all log files monitored. The default is 0, all log files are monitored. |
|
Regular expression specifying the include filter |
Enter a regular expression in Perl, to identify the pattern you want to look for in the text file being monitored. Strings matching the include filter pattern are returned. The default expression, .+, matches all strings. |
|
Optional file with regular expressions specifying the include filter |
If you do not want to enter a regular expression in the Regular expression specifying the include filter parameter, specify the full path to a file containing the regular expression specifying the include filter. |
|
Modifier for the regular expression include filter |
Enter any modifier you want to use to change the behavior of the regular expression. For example, specifying i for this parameter makes the include filter case-insensitive. For more information about writing Perl regular expressions, see Section 4.1, Creating Filters with Regular Expressions. |
|
Regular expression specifying the exclude filter |
Enter a regular expression, in Perl, to identify the pattern you want to exclude from matching in the text file being monitored. Strings with the exclude filter pattern are not returned. Separate multiple commands with commas and no spaces. For information about writing Perl regular expressions, see Section 4.1, Creating Filters with Regular Expressions. |
|
Optional file with regular expressions specifying the exclude filter |
If you do not want to enter a regular expression in the Regular expression specifying the exclude filter parameter, specify the full path to a file containing the regular expression specifying the exclude filter. |
|
Modifier for the regular expression exclude filter |
Enter any modifier you want to use to change the behavior of the regular expression. For example, specifying i for this parameter makes the exclude filter case-insensitive. For information about writing Perl regular expressions, see Section 4.1, Creating Filters with Regular Expressions. |
|
Threshold for matching lines |
Enter the number of times, from 0 to 99999, to detect a line that matches the search criteria before raising an event. The default is 0, which is the first instance that exceeds the threshold and raises an event. |
|
Avoid file permission check on monitored log file? |
Select to Yes to avoid a file permission check on the monitored log file. The default is unselected. |
|
Validate previously scanned lines with CRC? (y/n) |
Select y to perform a cyclic redundancy check on the log file. The default is n. |
|
Maximum number of log files to keep |
Enter the maximum number of log files, from 0 to 9999, to create when the Knowledge Script logs ASCII entries. The default is 10. |
|
Event severity level for threshold crossing |
Set the event severity level, from 1 to 40, for crossing the specified threshold. The default is 5. |
|
Event severity level for all other errors |
Set the event severity level, from 1 to 40, when an error occurs. The default is 10. |
|
Event severity for internal failure |
Set the event severity level, from 1 to 40, to indicate the importance of an event in which this job experienced an internal error. The default is 5. |
|
Enable debugging? |
Set to y to enable debugging. The default is n. |