Generating a custom event when a search string is found in the file

The PATROL KM for Log Management allows you to generate a custom event when the search string that you defined matches a log file entry. It also allows you to specify a custom event origin. The custom event has the following characteristics:

• Event class -- LOGGeneral
• Event type -- WARN
• Event severity -- 3
• Event origin -- LOGMON.inst.fname, where inst is the user-defined label of the log file and fname is the log file name.

Text entered in the Custom Event Message text box can also be included in the event. Part or all of the matching log entries can be included in the custom event message.

PATROL identifies the words of the message (represented by tokens separated by white space) by their ordinal position in the matched log file line, numbered left to right starting with 1. PATROL identifies word substitution in the custom event message text by using the % character. You can enter ranges of words preceded by a single % (for example, %2-5 would identify tokens 2 through 5 inclusive).

If a log entry contains n lines, the token can span lines. Each End of Line character counts as a token. To include all of the text in the log entry, specify an open-ended range by entering %1-.

For example, you might want to create a custom event message that would display when a service fails to initialize. To see how you would set up a custom event message for this example, see Example: Defining a search string for processes .

Specify a custom origin for the events in the Custom Event Origin text box. If you do not specify an origin, the KM uses the default origin, 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 on built-in macros, see Built-in macros.

Before you begin

You must be using the PATROL Central Operator - Windows Edition, PATROL Central Operator - Web Edition, a PATROL Console in Developer mode, or the PATROL KM for Log Management PATROL Configuration Manager plug-in.

To create a custom event message

1. Depending on whether you are adding a new log file to be monitored or changing an existing log file, access either of the following, as described in Add File for Label - dialog box and Change File for Label - dialog box.
   • Add File for Label: instanceName dialog box
   • Change File for Label: instanceName dialog box
2. In the Custom Event Message text box, enter the text that you want to display when your search string conditions are satisfied.
3. In the Custom Event Origin text box, enter the origin for the events.

4. (Optional) For a text instance, in the Number of Lines in Log Entrytext box, enter the number of lines to include from the log file in the message returned when a search string is found.

   Example

   If you were searching for Disc Full errors, you could configure the KM to return two lines so that when the string Error: Disc Full is found, the KM returns the line matching that string and the next line, in the LOGMatchString 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.

   For example, if you specify that the KM returns four lines when it finds the search string Disc Full, and Disc full occurs in the first and third lines of the file, the KM counts only the first instance of Disc Full as a match.

   • If you want to ensure that all matches are found, leave the Number of Lines in Log Entry field blank.
5. If you want to define custom messages specific to a search criterion, on the Add file for Label: instanceName dialog box, click Next.
6. On the Configure Search Criteria: instanceName: Define Search Criterion dialog box, add a unique identification label in the Search Identifier text box.
7. Enter the required details, and click Next.
8. In the Configure Search Criteria: instanceName: Override Default Settings dialog box, select the Override default setting check box.
9. Specify a custom event message for the search criterion in the Custom Event Message text box.
10. Specify an origin for the events in the Custom Event Origin text box.
11. Fill out or modify the rest of the dialog box fields as described in Monitoring a text instance .