Patrol LogMgmt

BMC PATROL Knowledge Module for Log Management User Guide
Supporting
BMC PATROL Knowledge Module for Log Management 2.6
October 2010
www.bmc.com
Contacting BMC Software

You can access the BMC Software website at http://www.bmc.com. From this website, you can obtain information about the company, its products, corporate offices, special events, and career opportunities.
United States and Canada

Address BMC SOFTWARE INC 2101 CITYWEST BLVD HOUSTON TX 77042-2827 USA Telephone 713 918 8800 or 800 841 2031 Fax 713 918 8000
Outside United States and Canada

Telephone (01) 713 918 8800 Fax (01) 713 918 8000
Copyright 2007, 20092010 BMC Software, Inc. BMC, BMC Software, and the BMC Software logo are the exclusive properties of BMC Software, Inc., are registered with the U.S. Patent and Trademark Office, and may be registered or pending registration in other countries. All other BMC trademarks, service marks, and logos may be registered or pending registration in the U.S. or in other countries. All other trademarks or registered trademarks are the property of their respective owners. Linux is the registered trademark of Linus Torvalds in the U.S. and other countries. Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners. UNIX is a registered trademark of The Open Group. BMC Software considers information included in this documentation to be proprietary and confidential. Your use of this information is subject to the terms and conditions of the applicable End User License Agreement for the product and the proprietary and restricted rights notices included in this documentation.
Restricted rights legend

U.S. Government Restricted Rights to Computer Software. UNPUBLISHED -- RIGHTS RESERVED UNDER THE COPYRIGHT LAWS OF THE UNITED STATES. Use, duplication, or disclosure of any data and computer software by the U.S. Government is subject to restrictions, as applicable, set forth in FAR Section 52.227-14, DFARS 252.227-7013, DFARS 252.227-7014, DFARS 252.227-7015, and DFARS 252.227-7025, as amended from time to time. Contractor/Manufacturer is BMC SOFTWARE INC, 2101 CITYWEST BLVD, HOUSTON TX 77042-2827, USA. Any contract notices should be sent to this address.
Customer support
You can obtain technical support by using the BMC Software Customer Support website or by contacting Customer Support by telephone or e-mail. To expedite your inquiry, see Before contacting BMC.
Support website
You can obtain technical support from BMC 24 hours a day, 7 days a week at http://www.bmc.com/support. From this website, you can
s s s s s s s
read overviews about support services and programs that BMC offers find the most current information about BMC products search a database for issues similar to yours and possible solutions order or download product documentation report an issue or ask a question subscribe to receive proactive e-mail alerts when new product notices are released find worldwide BMC support center locations and contact information, including e-mail addresses, fax numbers, and telephone numbers
Support by telephone or e-mail

In the United States and Canada, if you need technical support and do not have access to the web, call 800 537 1813 or send an e-mail message to customer_support@bmc.com. (In the subject line, enter SupID:yourSupportContractID, such as SupID:12345). Outside the United States and Canada, contact your local support center for assistance.
Before contacting BMC

Have the following information available so that Customer Support can begin working on your issue immediately:
s
product information product name product version (release number) license number and password (trial or permanent)
operating system and environment information machine type operating system type, version, and service pack or other maintenance level such as PUT or PTF system hardware configuration serial numbers related software (database, application, and communication) including type, version, and service pack or maintenance level
s s s
sequence of events leading to the issue commands and options that you used messages received (and the time and date that you received them) product error messages messages from the operating system, such as file system full messages from related software
License key and password information

If you have questions about your license key or password, contact BMC as follows:
s
(USA or Canada) Contact the Order Services Password Team at 800 841 2031, or send an e-mail message to ContractsPasswordAdministration@bmc.com. (Europe, the Middle East, and Africa) Fax your questions to EMEA Contracts Administration at +31 20 354 8702, or send an e-mail message to password@bmc.com. (Asia-Pacific) Contact your BMC sales representative or your local BMC office.
Contents
Chapter 1 BMC PATROL KM for Log Management features and functionality 13 13 14 16 18 19 21 21 22 22 23 23 24 25 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applications and icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 2 Menu commands summary
LOG application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOGT application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced Features in the LOGT application menu. . . . . . . . . . . . . . . . . . . . . . . . . LOGMON application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PMGDEBUG application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PMGCONVERT application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Chapter 3 Parameter summary
Parameter summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Parameter defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Chapter 4 Monitoring log files 31
Configuring the PATROL KM for Log Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Adding an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Overview of dialog boxes to configure instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Add File for Label: instanceName dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Configure Search Criteria: instanceName: Define Search Criterion dialog box. . . 38 Configure Search Criteria: instanceName: Override Default Settings dialog box . 40 Configure Search Criteria: instanceName: Summary dialog box. . . . . . . . . . . . . . . 42 Change File for Label: instanceName dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Monitoring text files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Monitoring a text instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Monitoring scripts, named pipes, or binary files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Example for monitoring a script file on UNIX: Monitoring a file system for zerobyte files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Example for monitoring a script file on Windows: Monitoring updates to an antivirus package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Monitoring XML files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 How XML monitoring works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Contents
Monitoring an XML log instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Incremental scanning of an XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Rules for entering XML search strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Viewing search criteria for an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Modifying search criteria for an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Customizing event messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Stopping and starting the monitoring of the default log file . . . . . . . . . . . . . . . . . . . . . 69 Monitoring files in Unicode format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Stopping the monitoring of a file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Scanning a monitored file from the beginning. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Monitoring a file for a particular string. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Monitoring a file for multiple search criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Using regular expressions to create a search criterion to match multiple words. 77 Generating an alarm based on file age . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Generating an alarm based on file size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Generating an alarm when the time stamp of a file changes . . . . . . . . . . . . . . . . . . . . . 82 Generating an alarm when the permissions of a file change . . . . . . . . . . . . . . . . . . . . . 82 Generating an alarm when a number of matches is found over a period of polling cycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Generating a custom event when a search string is found in the file . . . . . . . . . . . . . . 85 Example: Creating a custom event message that displays when a service fails to initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Example: Creating a custom event origin that displays the event origin according to Macros specified in the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Generating and nullifying an alarm based on dual-search strings . . . . . . . . . . . . . . . . 88 Generating an alert after a specified number of strings have been found . . . . . . . . . . 89 Sending a notification when a string has been matched. . . . . . . . . . . . . . . . . . . . . . . . . 90 Creating a blackout period for KM event generation . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Scheduling file monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Defining limits to search a block of lines containing a match string . . . . . . . . . . . . . . 94 Retaining old log file instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Retaining the log file instance during configuration changes . . . . . . . . . . . . . . . . . . . . 96 Using the PATROL Configuration Manager to configure the PATROL KM for Log Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Plug-in actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 PATROL KM for Log Management configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 99 Chapter 5 Defining Recovery Actions 103
Configuring recovery actions for a log file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Responding to recovery actions that require confirmation . . . . . . . . . . . . . . . . . . . . . 105 Appendix A Accessing Menu Commands, InfoBoxes, and Online Help 107
Accessing KM Commands and InfoBoxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Accessing online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Appendix B Regular Expressions 111
Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conventions for using Regular Expressions with PATROL Objects . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Appendix C PATROL Agent Configuration Variables
113 114 114 114 117 118 118 131 132 135
Managing configuration variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PATROL KM for Log Management configuration variables . . . . . . . . . . . . . . . . . . . Using the /PMG/CONFIG/instanceName/actPatterns pconfig branch. . . . . . . Using the /PMG/CONFIG/instanceName/actSearchList pconfig variable . . . . Appendix D Migrating Data to Version 2.x
Migrating data from the PATROL KM for Log Management version 1.x. . . . . . . . . 136 Migrating data from LogSpring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137 Chapter E Troubleshooting 139 140 140 140 141 141 142 142 143 144 147
Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading the PMGDEBUG application class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling and disabling PATROL KM for Log Management debugging . . . . . . Enabling and disabling log file, script, and binary file debugging . . . . . . . . . . . Enabling named pipe debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General information to gather before calling BMC Software Support. . . . . . . . . . . . Diagnostic questions to answer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Information to capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Information to gather if the problem is related to memory and CPU utilization. . . Index
Contents
Figures
PATROL KM for Log Management application class hierarchy . . . . . . . . . . . . . . . . . 17
Figures
10
Tables
PATROL KM for Log Management applications, icons, and descriptions . . . . . . . . 18 Accessing online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19 LOG menu summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 LOGT menu summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 LOGT submenu summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22 LOGMON menu summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 PMGDEBUG menu summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23 PMGCONVERT menu summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 PATROL KM for Log Management parameter summary . . . . . . . . . . . . . . . . . . . . . . 26 PATROL KM for Log Management parameter defaults . . . . . . . . . . . . . . . . . . . . . . . . 28 Add File for Label: instanceName dialog box field descriptions . . . . . . . . . . . . . . . . . . 35 Configure Search Criteria: instanceName: Define Search Criterion dialog box field descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Configure Search Criteria: instanceName: Override Default Settings dialog box field descriptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Configure Search Criteria: instanceName: Summary dialog box field descriptions . . 42 Change File for Label: instanceName dialog box field descriptions . . . . . . . . . . . . . . . 43 Built-in macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 New Instance dialog boxes and fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Configure Size Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Schedule Log Scan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100 Accessing KM Commands and InfoBoxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Accessing online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109 Regular Expression characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 Configuration variables for PATROL KM for Log Management . . . . . . . . . . . . . . . 118
Tables
11
12
Chapter
BMC PATROL KM for Log Management features and functionality

1
This chapter provides you with a brief overview of the BMC PATROL Knowledge Module for Log Management (PATROL KM for Log Management) component. This chapter presents the following topics: Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Application class hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Applications and icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 14 16 18 19
Overview
The BMC PATROL Knowledge Module for Log Management (PATROL KM for Log Management) contains the knowledge that PATROL uses to monitor and manage log files in your environment. This product is a PATROL Knowledge Module, which is a set of files containing knowledge in the form of menu commands, application classes, parameters, and recovery actions that PATROL uses when monitoring the application instances and their associated components. The PATROL KM for Log Management monitors text log files, scripts, named pipes, binary files, and XML files in your environment. The KM provides the capability to monitor the space used by all monitored log files and to search log files for specific text strings and alarm when such strings are found. The KM also can automatically spawn recovery actions that can clear log files or back up and clear log files.
Chapter 1 BMC PATROL KM for Log Management features and functionality
13
Features
Features
The PATROL KM for Log Management allows you to
s
select logs to be monitored, including: log files that have not yet been created text, script, named pipe, binary files, and XML files log files with dynamic log file names
monitor log files for: size, growth rate, and age content state (WARN, ALARM) numeric comparisons change in permissions and timestamp
temporarily stop log monitoring during system maintenance by using external control flags set multiple schedules for multiple polling cycles per log file generate alerts when: a monitored log file is no longer present a text string or regular expression is discovered within a log file log file exceeds a specified size log file reaches a specified age log file permission changes log file timestamp changes a log file is inactive beyond a specified duration a number of matches is found over a period of polling cycles
alert a specific person or group based on a matched string in the log file view error strings found in the last log update that caused alert and all entries that match that error string from the last log update.
14
Features
configure log searches to: ignore subsequent alerts for a specified number of polling cycles if the search finds a matching string or regular expression in a log file override an ignored alert if the search finds a matching string or regular expression more than n times before the ignore setting is completed specify the number of log scan cycles after which a WARN or ALARM state is automatically changed to OK include part of or all of the text from the log in the event message text use NOT and AND statements with the text strings or regular expressions to narrow the log search monitor text log files by using multiple search criteria including overriding of default settings for a search criterion monitor XML files by using multiple search criteria ignore case-sensitivity for text files
use regular expressions to create: an exclude alert string that prevents alarms and warnings from occurring by filtering out messages in the log that match specified alarm or warning strings use regular expressions to create an exclude to warn alert string that interprets message text that matches alarm strings and moves the text into a warning
generate one of the following automated recovery actions when a log file exceeds an acceptable size or growth rate: clear and back up log files delete files run in attended and unattended modes reset log alerts which occur as a result of updated text in the log file that matches a specified alert string
For information about configuring and using the PATROL KM for Log Management, see Chapter 4, Monitoring log files. Also, see the PATROL Knowledge Module for Log Management online Help for information about using the features of this product.
15
Application class hierarchy

The PATROL products are organized hierarchically. At the top level of the hierarchy is the computer instance. Beneath it are the PATROL KM for Log Management application classes object. Application classes may contain instances, but not all application classes have instances or parameters. Figure 1 on page 17 illustrates the basic hierarchy of the PATROL KM for Log Management.
16
Figure 1
PATROL KM for Log Management application class hierarchy
17
Applications and icons
Applications and icons

Table 1 contains information about each application in the PATROL KM for Log Management. For information about parameter icons, refer to the documentation for your console. Table 1 Icon PATROL KM for Log Management applications, icons, and descriptions Definition
contains instances of the LOGT application class for every monitored log file All parameters for the LOG application class do not have icons and are used internally by the PATROL KM for LOG Management. LOG contains instances of the LOGMON application class and contains log search string information
LOGT each LOGMON application class instance represents a monitored log file LOGMON parameters monitor log files for s error level s file size s growth rate s whether a defined search string exists s status s change in file size s change in time stamp of the file s change in permissions on the file allows you to enable and disable KM debugging. This application class appears under the host instance in the PATROL MainMap only when the PMGDEBUG.km application is loaded. There is no icon for this application class. PMGDEBUG If you have upgraded from the PATROL KM for Log Management version 1.x to version 2.x, this application class allows you to convert definitions from version 1.x format to 2.x format. This application class appears under the host instance in the PATROL MainMap only when the PMGCONVERT.km application is loaded. There is no icon for this application class.
LOGMON
PMGCONVERT
18
Help
Help
Help describes the function of the currently displayed window or dialog box and the use of its elements. Table 2 on page 19 provides information about how to access Help from each console.
NOTE
If you are trying to access Help from a UNIX console, see the PATROL Installation Reference Manual for specific instructions about installing and setting up a browser in the UNIX environment.
Table 2
Console
Accessing online Help (Part 1 of 2)

To access product Help From the console menu bar, choose Help => Help Topics. In the Help Topics window, double-click PATROL Knowledge Modules. In the submenu, double-click PATROL KM for Log Management. To access application class Help If you have a developer connection to the agent, double-click an application class in the KM tab of the console. From the Application Properties dialog box, click the Help tab. Then click Show Help. To access parameter Help
s
PATROL Console for Microsoft Windows Servers
Right-click a parameter icon and choose Help On from the pop-up menu. Double-click a parameter icon; click the ? icon or Help button in the parameter display window. Double-click a parameter in the KM tab of the console; from the properties dialog box, click the Help tab and then click Show Help.
PATROL Console for UNIX
Right-click the PATROL KM for Log Management application icon and choose KM Commands => Product Help. From the console menu bar, choose Help On => Knowledge Modules.
Choose Attributes => Application Classes and double-click the application name. Click Show Help in the Application Definition dialog box.
Right-click a parameter icon and click Help On.
19
Help
Table 2
Console

To access product Help From the console menu bar, choose Help => Help Topics. In the Contents tab, click the name of your product. To access application class Help In the Operator tab of the navigation pane, select an application icon and press F1. To access parameter Help In the Operator tab of the navigation pane, select an application icon and press F1.
PATROL Central Operator - Windows Edition
PATROL Central Operator - Web Edition
In the upper right corner of In the tree view, right-click In the tree view, right-click an application class and a parameter and choose PATROL Central, click Help. Help and choose PATROL choose Help. KM Help. In the PATROL Central Web Edition KM Help window, click the name of your product.
20
Chapter
Menu commands summary

This chapter summarizes the application menus and menu commands for the PATROL Knowledge Module for Log Management component. The application menu content is provided in a table for each of the application classes. This chapter describes KM menu commands only. The KM help system provides further details about these menu commands. For descriptions of PATROL Console menu commands, see the appropriate PATROL user guide for your console. This chapter presents the following topics: LOG application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . LOGT application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Advanced Features in the LOGT application menu. . . . . . . . . . . . . . . . . . . . . . . . . LOGMON application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PMGDEBUG application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PMGCONVERT application menu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 22 22 23 23 24
LOG application menu

The LOG application class menu has the following menu commands: Table 3 LOG menu summary (Part 1 of 2) Action
displays a dialog box that allows you to add new LOG application instances that you want to monitor displays a dialog box that allows you to specify the flag file directory location on your system forces a refresh of the LOG collector parameters
Menu Command
Add Instance Identify Flag Directory
Read Logs
Chapter 2 Menu commands summary
21
LOGT application menu
Table 3
LOG menu summary (Part 2 of 2) Action

displays a dialog box that allows you to enable and disable default log monitoring enables you to specify the number of old LOGMON instances that you want to keep
Menu Command
Enable/Disable Default Log Monitoring Product Configuration
LOGT application menu

The LOGT application class menu has the following menu commands: Table 4 LOGT menu summary Action
enables you to modify the monitoring properties and default search criteria settings enables you to add, delete, and modify a search criterion enables you to delete a LOGT instance from the list of monitored instances enables you to view the configured search criterion for an instance displays the advanced features submenu options and their dialog boxes that allow you to configure a LOGT instance
Menu Command
Modify => Default Settings Modify => Search Criteria Delete Instance Report Configuration Advanced Features
Advanced Features in the LOGT application menu

The Advanced Features menu command of the LOGT application menu displays the following submenu commands: Table 5 LOGT submenu summary (Part 1 of 2) Action
displays a dialog box that allows you to manually prevent the KM from generating events for a file for a specified period of time displays a dialog box that allows you to define recovery actions that occur when the monitored file exceeds a specified size displays a dialog box that allows you to schedule scanning on a weekly basis and also define multiple schedules for weekdays including adding different schedules for each day
Menu Command
Configure Log Monitoring Blackout
Configure Size Action Schedule Log Scan
22
LOGMON application menu
Table 5
LOGT submenu summary (Part 2 of 2) Action

displays a dialog box that allows you to configure an alarm when the size of the monitored file exceeds a specified threshold displays a dialog box that allows you to define limits to search a block of lines containing a match string This option is not available if you are monitoring an XML file.
Menu Command
Configure Alarm Multiline Search
LOGMON application menu

The LOGMON application class menu has the following menu commands: Table 6 LOGMON menu summary Action
displays a dialog box that allows you to display a specified number of lines in the log file resets the error level to OK
Menu Command
Log Browser Reset Error Level
PMGDEBUG application menu

NOTE
The PMGDEBUG application appears under the host instance in the PATROL MainMap only when the PMGDEBUG.km application is loaded. For more information about the LOG KM Debug application, see Loading the PMGDEBUG application class on page 140.
The PMGDEBUG application class menu has the following menu commands: Table 7 PMGDEBUG menu summary (Part 1 of 2) Action
If Enable Reader Debug is selected in the Debug Configuration dialog box from the Configure Debug menu option, the Dump Reader State menu option causes the KM to dump the current state of the log files (excluding pipes) to the ReaderLog.txt file on the managed system. For more information see, Enabling and disabling log file, script, and binary file debugging on page 141.
Menu Command
Dump Reader State
Chapter 2 Menu commands summary
23
PMGCONVERT application menu
Table 7
PMGDEBUG menu summary (Part 2 of 2) Action

If Enable Pipe Reader Debug is selected in the Debug Configuration dialog box from the Configure Debug menu option, the Dump Pipe Reader State menu option causes the KM to dump the status of the named pipes to the pipeReaderLog.txt file on the managed system. For more information see, Enabling named pipe debugging on page 141. displays the Debug Configuration dialog box that allows you to enable and disable debugging for files, binaries, and named pipes, as well as enable KM debugging. For more information about each type of debugging, see Loading the PMGDEBUG application class on page 140.
Menu Command
Dump Pipe Reader State
Configure Debug
PMGCONVERT application menu

NOTE
The PMGCONVERT application appears under the host instance in the PATROL MainMap only when the PMGCONVERT.km application is loaded. For more information about the LOG Convert application, see
The PMGCONVERT application class menu has the following menu commands: Table 8 PMGCONVERT menu summary Action
converts LogSpring entries to a PATROL KM for Log Management 2.x compatible format converts PATROL KM for Log Management version 1.0 data to a PATROL KM for Log Management version 2.x compatible format
Menu Command
LogSpring Convert Convert 1.0 to 2.0 Definition
24
Chapter
Parameter summary
This chapter provides a summary of parameters for the PATROL KM for Log Management. Refer to the PATROL user guide for your console for additional information about the different types of parameters and their functions. See the PATROL KM for Log Management online Help system for details about KM-specific parameters. This chapter presents the following topics: Parameter summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Parameter defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
Chapter 3
Parameter summary
25
Parameter summary
Parameter summary
The PATROL KM for Log Management has various parameters that provide statistical information about resources, operating status, and performance. Table 9 lists each application class and its associated parameters. The table also provides information that you can use when selecting or reviewing the appropriate parameters used in monitoring the PATROL KM. See Table 10 on page 28 for the default values each parameters. Table 9 Parameter
LOG Application Class LOGMainColl LOGMainCollP2 LOGMainCollP3 used internally by the PATROL KM for LOG Management application for normal priority scan. This parameter has no icon. used internally by the PATROL KM for LOG Management application for medium priority scan. Has no icon. used internally by the PATROL KM for LOG Management application for low priority scan. This parameter has no icon. used to set OK, WARN, or ALARM status based on criteria specified for the log file definition. Threshold values are: 1 = OK 2 = WARN 3 = ALARM If the threshold of a search criterion is breached, this parameter displays the number of matches of that search criterion as annotated text. WARNING: Do not change the default thresholds of this parameter. Doing so prevents the KM from functioning correctly. LOGFileSize displays the file size of monitored files. The log file size limit is 2 GB. Note: If this parameter is inactive, the value of the LOGGrowthRate parameter will be inaccurate. displays the status of the monitored files. The parameter goes into an alarm state when the file size of the monitored file exceeds the specified threshold. The values for this parameter are: 0 = OK 1 = ALARM Note: This parameter is active only if the KM is configured for alarm based on the file size of the monitored file.
PATROL KM for Log Management parameter summary (Part 1 of 2) Description
LOGMON Application Class LOGErrorLvl
LOGFileSizeStatus
LOGFileTimestampStatus displays the status of the monitored files. The parameter goes into an alarm state when the time stamp of the monitored file changes. The values for this parameter are: 0 = OK 1 = ALARM Note: This parameter is active only if the KM is configured for alarm based on the time stamp of the monitored file.
26
Parameter summary
Table 9 Parameter
PATROL KM for Log Management parameter summary (Part 2 of 2) Description
LOGFilePermissionStatus displays the status of the monitored files. The parameter goes into an alarm state when the permissions of the monitored file change. The values for this parameter are: 0 = OK 1 = ALARM Note: This parameter is active only if the KM is configured for alarm based on the permissions of the monitored file. LOGGrowthRate displays the growth rate of the log file to graph changes in the size of the log file over time, calculated by the change of the LOGFileSize parameter over time. Note: If the LOGFileSize parameter is inactive, the value of LOGGrowthRate will be inaccurate. displays the string that matched the regular expression defined in the log search It also displays the summary of the number of matches found for all the search criteria. LOGMONRecoveryColl LOGSearchString used internally by the PATROL KM for LOG Management application.This parameter has no icon. displays the total number of search string matches found for all the search criteria during the last scanning cycle. A value of 0 indicates that no matches were found. displays the status of the monitored log file: s 0 = Missing or unknown s 1 = OK s 2 = Modified s 3 = Read Error s 4 = Inactivity/Error s 5 = Missing Message Error s 6 = File Growth Rate Exceeded s 7 = Invalid File If the default account of the PATROL Agent does not have read access to a file, the LOGStatus parameter is set to a value of 3 (Read Error). If there is an error while scanning the XML file because of reasons such as invalid XML syntax, the value of this parameter is set to 7 (Invalid File). On UNIX systems, you can change the permission of the pmgpipereader binary file to the setuid root, which is owned by the root account with the 6755 permission. You can also change the permission of the file or add the default account of the PATROL Agent to a user account that has the permission to read the file. LOGT Application Class The LOGT application class has no parameters.
LOGMatchString
LOGStatus
Chapter 3
Parameter summary
27
Parameter defaults
Parameter defaults
Table 10 on page 28 lists default values for parameters. Interpret the column headings as follows. Depending on the type of parameter, some information is not applicable. A description of each parameter and its properties is available in Table 9 on page 26.
NOTE
All PATROL KM for Log Management parameters are active by default.
Column heading Information included under column heading

Type Alarm 1 Alarm 2 Scheduling Icon Units History Level specifies whether the parameter is a Standard, Consumer, or Collector parameter specifies the thresholds for the first alarm This information is not applicable to Collectors. specifies the thresholds for the second alarm This information is not applicable to Collectors. specifies the time interval in the poll cycle specifies whether the icon is a graph, gauge, or text box specifies the type of unit in which the parameter output is expressed, such as a percentage, a number, or bytes specifies the length of time that history is retained
Table 10
PATROL KM for Log Management parameter defaults (Part 1 of 2) Scheduling
Alarm1
Alarm2
Parameter
LOGErrorLvl LOGFileSize LOGFileSizeStatus
consumer consumer consumer
2=WARN und. 1=ALARM 1=ALARM 1=ALARM und. NA NA NA NA NA
3=ALARM und. NA NA NA und. NA. NA NA NA NA
NA NA NA NA NA NA 2 min 10 min 30 min NA 10 min
graph graph Boolean Boolean Boolean graph none none none text NA
level bytes NA NA NA bytes/min NA NA NA strings NA
LOGFileTimestampStatus consumer LOGFilePermissionStatus consumer LOGGrowthRate LOGMainColl LOGMainCollP2 LOGMainCollP3 LOGMatchString LOGMONRecoveryColl consumer collector collector collector consumer collector
28
Units
Type
Icon
Parameter defaults
Table 10
PATROL KM for Log Management parameter defaults (Part 2 of 2) Scheduling
Alarm1
Alarm2
Parameter
LOGSearchString LOGStatus
consumer consumer
und. 0=ALARM
und. 3-7=ALARM
und. NA
graph graph
matches status
Chapter 3
Parameter summary
Units
29
Type
Icon
Parameter defaults
30
Chapter
Monitoring log files

This chapter presents the following topics: Configuring the PATROL KM for Log Management . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Overview of dialog boxes to configure instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Adding an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Overview of dialog boxes to configure instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Add File for Label: instanceName dialog box. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 Configure Search Criteria: instanceName: Define Search Criterion dialog box . 38 Configure Search Criteria: instanceName: Override Default Settings dialog box. . 40 Configure Search Criteria: instanceName: Summary dialog box. . . . . . . . . . . . . . 42 Change File for Label: instanceName dialog box . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 Monitoring text files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Monitoring a text instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 Monitoring scripts, named pipes, or binary files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Example for monitoring a script file on UNIX: Monitoring a file system for zerobyte files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Example for monitoring a script file on Windows: Monitoring updates to an antivirus package. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 Monitoring XML files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 How XML monitoring works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Monitoring an XML log instance. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Incremental scanning of an XML file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 Rules for entering XML search strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Viewing search criteria for an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Modifying search criteria for an instance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Customizing event messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67 Stopping and starting the monitoring of the default log file. . . . . . . . . . . . . . . . . . . . . 69 Monitoring files in Unicode format. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 Stopping the monitoring of a file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Stopping the monitoring of a file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 Scanning a monitored file from the beginning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Monitoring a file for a particular string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 Monitoring a file for multiple search criteria. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 Using regular expressions to create a search criterion to match multiple words 77 Searching a file for two or more complex messages . . . . . . . . . . . . . . . . . . . . . . . . 78
Chapter 4 Monitoring log files 31
Configuring the PATROL KM for Log Management
Generating an alarm based on file age . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 Generating an alarm based on file size . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 Generating an alarm when the time stamp of a file changes . . . . . . . . . . . . . . . . . . . . . 82 Generating an alarm when the permissions of a file change . . . . . . . . . . . . . . . . . . . . . 82 Generating an alarm when a number of matches is found over a period of polling cycles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83 Generating a custom event when a search string is found in the file . . . . . . . . . . . . . . 85 Example: Creating a custom event message that displays when a service fails to initialize. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87 Example: Creating a custom event origin that displays the event origin according to Macros specified in the configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88 Generating and nullifying an alarm based on dual-search strings . . . . . . . . . . . . . . . . 88 Generating an alert after a specified number of strings have been found . . . . . . . . . . 89 Sending a notification when a string has been matched. . . . . . . . . . . . . . . . . . . . . . . . . 90 Creating a blackout period for KM event generation . . . . . . . . . . . . . . . . . . . . . . . . . . . 91 Scheduling file monitoring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93 Defining limits to search a block of lines containing a match string . . . . . . . . . . . . . . 94 Retaining old log file instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95 Retaining the log file instance during configuration changes . . . . . . . . . . . . . . . . . . . . 96 Using the PATROL Configuration Manager to configure the PATROL KM for Log Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 Plug-in actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97 PATROL KM for Log Management configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Configuring the PATROL KM for Log Management

The appropriate operating system KM (PATROL KM for UNIX and Linux or the PATROL KM for Microsoft Windows) must be loaded for the PATROL KM for Log Management to function. Once loaded, the PATROL KM for Log Management application classes appear beneath the OS KM instance on the BMC PATROL MainMap. For each file, the KM monitors:
s s
the file size (using the LOGFileSize parameter) the growth rate (using the LOGGrowthRate parameter)
By default, the PATROL KM for Log Management monitors the Agent error log. You can configure the KM to monitor additional files. The PATROL KM for Log Management supports the following file types:
32
Adding an instance
Text files The KM monitors text files only if they have changed since the last scan, and the KM scans only the information that was added since the last scan. However, you can configure the KM to always monitor from the beginning of the text file. Scripts You can use the PATROL KM for Log Management to monitor the output of any script, program, or batch file. The KM executes the specified script, program, or batch file each scan cycle. The resulting output is treated as a log file and then monitored for a specified string or the absence of a specified criterion. For example, you can check network connectivity with other computers on the network by writing a script to ping various computers and output an error message for the ones that appear to be down, then create a log definition to monitor for the error message.
Named pipes Named pipes are opened and kept open for reading. The KM reads the data from the pipe a line at a time and accumulates the data in a secondary log file, which is scanned like a normal log file. It reads only the latest data on each scan. However, you can configure the KM to read all the data on each scan. Binary files These files are read with a user-specified filter program. The filter program outputs to a secondary log file, which is monitored like a normal log file. Binary files are only read if they have been modified since the last scan. XML files These files are only read if they have been modified since the last scan, and the KM scans only the information that was added since the last scan. However, you can configure the KM to always monitor from the beginning of the XML file.
Adding an instance
The PATROL KM for Log Management allows you to configure and monitor different types of log files. To configure and monitor a log file instance, you need to add the instance.
To add an instance 1 Access the LOG application menu as described in Appendix A, Accessing Menu
Commands, InfoBoxes, and Online Help.
2 Select Add Instance.
Chapter 4 Monitoring log files
33
Overview of dialog boxes to configure instances
3 In the Add Instance dialog box, enter a label for the file that you want to start
monitoring. The icon label must be 50 characters or less and cannot contain any spaces.
4 Click Accept.
The Add File for Label dialog box appears that enables you to configure the instance. For more information, see Add File for Label: instanceName dialog box on page 34.
NOTE
To access this dialog box, use the PATROL Central Operator - Windows Edition, PATROL Central Operator - Web Edition, or a PATROL Console in Developer mode. Alternatively, you can use the PATROL KM for Log Management PATROL Configuration Manager plug-in as described in Using the PATROL Configuration Manager to configure the PATROL KM for Log Management on page 97.
Overview of dialog boxes to configure instances

You can define and modify the monitoring properties, default search criterion, and multiple individual search criterion for an instance by using the following dialog boxes:
s s s s
Add File for Label: instanceName Configure Search Criteria: instanceName: Define Search Criterion Configure Search Criteria: instanceName: Override Default Settings Configure Search Criteria: instanceName: Summary
Add File for Label: instanceName dialog box

You can define the monitoring properties and default settings for the search criteria for an instance by using the Add File for Label: instanceName dialog box. Table 11 on page 35 describes each field in the dialog box.
34
Table 11
Item
Add File for Label: instanceName dialog box field descriptions (Part 1 of 4)
Description Enter the full path including the name, of the instance that you want to search and monitor (900-byte limit). The PATROL Agent default account must be able to read this file. Regular expressions in log file names are supported. Universal Naming Convention (UNC) paths are also supported. For example: \\servername\share. You can also use an asterisk (*) to indicate one dynamic directory. For example, if the monitored log is located at C:\Program files\DBA runlog\ddmmyyyy\ABC.log (where ddmmyyyy represents the date), you can set up the KM to monitor the log file by entering the following path and filename: C:\Program files\DBA runlog\*\ABC.log You can search upto three levels using asterisks. For example, /etc/*/*/*/a*.log
File/Pipe Name text box
Logical Name text box
Enter the logical name for the LOGMON instance that you want to monitor, which appears in the event manager. The instance logical name is stored in the pconfig variable located at /PMG/CONFIG/label/actLogicalName. An event is generated with the logical name and the file name of the instance. If you do not specify a logical name, the pconfig variable remains blank.
Contains Environmental Variables check box
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 file path are resolved. Otherwise, the file is treated as a pure file name. For example, if you enter %HOME%/log.txt in the File/Pipe Name text box and select this check box, the KM substitutes the path defined by %HOME%. If the box is unchecked, the KM tries to find a path called %HOME%.
File Type radio buttons Filter Program text box Always Read at Beginning check box
Select either file type you want from the Text File, Script, Named Pipe, XML File or Binary File type options. If the file type is Binary File, specify a filter program to read the monitored binary. Select this check box if you want the product to read the file from the beginning in each polling cycle, rather than only the information added since the last time the file was scanned. If you do not select this check box, the product reads only the text that was added since the last time file was scanned.
File Disposition radio buttons Generate ALARM if file not modified in check box
If multiple files match the file name (for example, if you use a regular expression), select whether you want to monitor only the Latest file or All of the files. Select this check box if you want the LOGMON instance to generate alarm if the monitored file is not modified after a specific interval.
35
Table 11
Item
Description When the Generate ALARM if file not modified check box is selected, use this text box to specify the time in minutes after which an alarm will be generated if the file is not modified.
minutes text box
Default Settings for Search Criteria: This section allows you to define search criteria settings at the global level. These are the default settings and are common to all the search criteria, unless you override them for a search criterion in the Configure Search Criteria: instanceName: Override Default Settings dialog box. Threshold # 1 text box Enter the minimum number of text or XML search string matches in a polling cycle required to generate 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. State list Select one of the states that the KM will exhibit when the Threshold-Match Count value is reached: None, OK, Warn, or Alarm. For example, if you want the KM to go into alarm state if the search string is found 3 times in the monitored file, then you would set the value of Threshold # 1: Match Count to 3 and select Alarm from the State list. Enter the minimum number of text or XML 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; x represents the minimum number of text string matches, and y represents the total number of polling cycles. State list Custom Event Message text box Select the state that the KM will exhibit when the Threshold# 2 Match Count value is reached: None, OK, Warn, or Alarm. (optional) Enter the message that you want displayed in the events when your search string conditions are satisfied. For more information, see Customizing event messages on page 67. 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 Table 16 on page 68. Ignore duplicate events for next ... minutes text box Specify an interval in minutes during which the product does not generate an event after the first match and its corresponding event. After the specified time elapses, the search criteria generate an event for the next match.
Threshold # 2 text box
36
Table 11
Item
Description Enter the number of lines that you want to be displayed when a match is found. For example, if you want to determine when a disk is full and where the disk is mounted, enter Error: Disc Full as the search string and 2 as the value of Number of Lines in Log Entry. When a disk is full, a message similar to the following one is displayed 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.
Number of Lines in Log Entry text box (Not applicable for an XML instance)
Nullify Alarm/Warn String text box (Not applicable for an XML instance)
Enter 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 search string is found. You must specify atleast one search criterion (in the Configure Search Criteria: instanceName 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). For example, if you specify 'Alarm up' in the String1 text box of the search criteria and 'Alarm down' in the Nullify Alarm/Warn String text box, the KM goes into 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.
Once closing root-tag is found, Delete instance after minutes text box (Applicable only for an XML instance)
Specify an interval in minutes during which the product should not delete an instance even if the closing root-tag is found. After the specified time elapses, the product will delete the instance for which the closing root-tag is found.
Return to OK if no match If the KM goes into an alarm or a warning state because the search string is found on next scan check box found and you want the KM state to return to OK if the search string is not found on the next scan, select this check box.
37
Configure Search Criteria: instanceName: Define Search Criterion dialog box
Table 11
Item
Description Select the priority at which you want the log file to be scanned:
s
Scan Priority list
Normal is associated with the LogMainColl collector. 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. Next button Click this button to continue configuring the instance and define the search criterion in the Configure Search Criteria: instanceName: Define Search Criterion dialog box. Click this button to close the dialog box.
Cancel button

Click Next in the Add File for Label: instanceName dialog box to display the Configure Search Criteria: instanceName: Define Search Criterion dialog box, which allows you to configure an individual search pattern while adding an instance. You can also modify the search criterion using this dialog box. Table 12 describes the properties available in the Configure Search Criteria: instanceName: Define Search Criterion dialog box. Table 12
Item File Name label
Configure Search Criteria: instanceName: Define Search Criterion dialog box field descriptions (Part 1 of 3)
Description Displays the log file name that will be monitored against the multiple regular expressions that you provided
Search Criterion: This section allows you to define and modify search criterion settings for an individual search criterion.
38
Table 12
Item
Description Enter an identification label for the search criterion. This must be unique for a text or XML instance. You can use the same search identifier in other text or XML instances, but not in the same text or XML instance. You can only use aplhanumeric characters such as a-z, A-Z, 0-9, and up to a maximum of 20 characters. This label appears in the Search list and helps you identify and modify the search criterion.
Search Identifier text box
Not check box (Not applicable for an XML instance)
Select this check box to find the log file text line that does not contain the search string specified in the String1 text box. If you want to find the files that do contain the search string in the String1 field, ensure that this check box is not selected.
String1 text box
For a text instance, enter the first search string or the regular expression for the first search string that you want to search in the text instance (4096-byte limit). For an XML instance, 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 on page 63. You can also enter multiple search patterns in this text box. Each search pattern must be a valid regular expression. You need to enclose each search pattern in parentheses ({ }). For example, you can enter {Pattern1} {Pattern2} {Pattern3}. For information about regular expressions, see Appendix B, Regular Expressions. 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, PATROL generates an alarm. Note: BMC does not recommend performing the following actions:
s
Entering multiple search patterns in the String1 text box and selecting the Always Read At Beginning check box in the Add File for Label: instanceName dialog box simultaneously. Entering a single search pattern in the String1 text box. The KM might not generate any alarm in that case. For example, if you enter {Job Started}, the KM might not generate an alarm.
39
Configure Search Criteria: instanceName: Override Default Settings dialog box
Table 12
Item
Description Select this check box to find all files that do not contain the search string in the String2 text box. If you want to find the files that contain the search string in the String2 field, ensure that this check box is not selected.
Not check box (Not applicable for an XML instance)
String2 text box (Not applicable for an XML instance) First Number text box (Not applicable for an XML instance) Op list (Not applicable for an XML instance) Begin token text box (Not applicable for an XML instance) End token text box (Not applicable for an XML instance) Op list (Not applicable for an XML instance) Second Number text box (Not applicable for an XML instance) Next button
(optional) Enter the search string or the regular expression for the second search string that you want to search in the text instance (4096-byte limit). Enter a number to specify a starting position of a search range in the matched file. Select an operator.
Enter a valid beginning token value.
Enter a valid ending token value.
Select an operator.
Enter a number to specify an ending position of a search range in the matched file line. Click this button to continue configuring the instance and override the default settings for a particular search criterion in the Configure Search Criteria: instanceName: Override Default Settings dialog box.

The Configure Search Criteria: instanceName: Override Default Settings dialog box allows you to override the default search criterion settings for an instance that you have defined in the Add File for Label: instanceName dialog box. In addition, you can modify the search criterion using this dialog box. Table 13 on page 41 describes the properties available in the Configure Search Criteria: instanceName: Override Default Settings dialog box.
40
Table 13
Item
Configure Search Criteria: instanceName: Override Default Settings dialog box field descriptions (Part 1 of 2)
Description Displays the search identifier that helps you identify a search criterion. This label appears in the search list.
Search Identifier label
Override default setting check box Threshold # 1 text box
Select this check box to override the default setting for the search criterion that you have specified in the Add file for Label: instanceName dialog box. Enter the number of search string matches that must occur before generating a specified state. For example, if the Match Count field value is 3, the text search string must occur 3 times in the monitored file before the KM goes into the state specified by the State list. This threshold overrides the default threshold value specified in the Add file for Label: instanceName dialog box, if you select the Override default setting check box.
State list
Select the state that you want the product to exhibit when the ThresholdMatch Count value is reached: None, OK, Warn, or Alarm. For example, if you want the KM to go into an alarm if the search string is found 3 times in the monitored file, then you would set the value of Threshold # 1: Match Count to 3 and select Alarm from the State list. This state overrides the default state specified in the Add file for Label: instanceName dialog box, if you select the Override default setting check box.
Threshold # 2 text box
If you want the KM to exhibit a second state when a different number of search strings occurs, enter the number of matched search strings in this text box. Threshold # 2 should always be higher than Threshold # 1. For example, if you set the Threshold # 1 Match Count to alarm when 3 occurrences of the search string are found and you want the KM to warn when 1 occurrence of the search string is found, enter 1 in the Threshold # 2: Match Count text box. This threshold overrides the default threshold specified in the Add file for Label: instanceName dialog box, if you select the Override default setting check box.
State list Custom Event Message text box
Select the state that the KM will exhibit when the Threshold# 2 Match Count value is reached: None, OK, Warn, or Alarm. Enter the message that you want to get displayed when the search criteria are satisfied. For more information, see Customizing event messages on page 67. This message overrides the default message provided in the Add file for Label: instanceName dialog box.
41
Configure Search Criteria: instanceName: Summary dialog box
Table 13
Item
Configure Search Criteria: instanceName: Override Default Settings dialog box field descriptions (Part 2 of 2)
Description Specify the customized origin for events. 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 about built-in macros, see Table 16 on page 68. This origin overrides the default origin provided in the Add File for Label: instanceName dialog box.
Custom Event Origin text box
Ignore duplicate events for next ... Minutes text box
Specify an interval in minutes during which the product does not generate an event after the first match and its corresponding event After the specified time elapses, the search criteria generate an event for the next match.
Generate ALARM when pattern not found within ..Polling Intervals text box Next button
Specify the number of polling intervals, after which an alarm should be generated if the search pattern is not found within those polling intervals. Click this button to see the summary of all search criterion defined for an instance in the Configure Search Criteria: instanceName: Summary dialog box. For more information, see Configure Search Criteria: instanceName: Summary dialog box..
Configure Search Criteria: instanceName: Summary dialog box

The Configure Search Criteria: instanceName: Summary dialog box lists a summary of search criterion defined for an instance using search identifiers. You can use this dialog box to add, modify, or delete a search criterion for the instance. Table 14 on page 42 describes the properties available in the Configure Search Criteria: instanceName: Summary dialog box. Table 14
Item Search list
Configure Search Criteria: instanceName: Summary dialog box field descriptions (Part 1 of 2)
Description Displays the entered search criteria. It also displays whether a search criterion is valid or invalid. Each search string added gets appended to the list of search strings. The product populates the search strings in the list with every update. Note: The Validity column in the Search list is not applicable for the XML instances.
Add radio button
Select this option to add a new search criterion to the Search list.
42
Change File for Label: instanceName dialog box
Table 14
Item
Configure Search Criteria: instanceName: Summary dialog box field descriptions (Part 2 of 2)
Description Select this option to delete a search criterion from the Search list. Select this option to view and modify a search criterion from the Search list. Select this check box if you want to revert all changes made in this dialog box and use the original search list. Updates the search list with the addition, modification, or deletion of a search criterion. Click this button to finish the configuration process.
Delete radio button Modify radio button Discard changes check box Update button Finish button

The Change File for Label: instanceName dialog box allows you to change the monitoring properties and the default search criterion settings for an existing log instance that you are monitoring. Table 15 describes the properties available in the Change File for Label: instanceName dialog box. Table 15
Item File/Pipe Name text box
Change File for Label: instanceName dialog box field descriptions (Part 1 of 4)
Description Displays the full path, including the name, of the text instance that you want to search and monitor (900 byte limit) The BMC PATROL Agent default account must be able to read this file.
Logical Name text box
Specify the logical name for the LOGMON instance that you want to monitor The instance logical name is stored in the pconfig variable located at /PMG/CONFIG/label/actLogicalName. An event is generated with the logical name and the file name of the instance. If you do not specify a logical name, the pconfig variable remains blank.
Contains Environmental Variables check box
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 file path are resolved. Otherwise, the file is treated as a pure file name. For example, if you enter %HOME%/log.txt in the File/Pipe Name text box and select this check box, the product substitutes the path defined in %HOME%. If the check box is cleared, the product tries to find a path called %HOME%.
File Type options Filter Program text box
Select a file type. If the file type is Binary File, enter the filter program to read the monitored binary.
43
Table 15
Item
Description When a file is modified, the KM reads the file from its beginning in each polling cycle. If you do not select this check box, the KM reads only the text that was added since the last time file was scanned. If multiple files match the file name (for example, if you use wildcard characters), select Latest to monitor only the most recent file or All to monitor all the files. Select this check box if you want the LOGMON instance to go into an alarm state if the monitored file is not modified periodically. If you have selected the Generate ALARM if file not modified in check box, specify the time in minutes after which an alarm must be generated if the file is not modified.
Always Read at Beginning check box File Disposition options
Generate ALARM if file not modified in check box minutes text box
Default Settings for Search Criteria: Specify the default settings for a search criterion (described in the following rows). These settings can be overridden by the individual search criterion defined in the Configure Search Criteria: instanceName: Override Default Settings dialog box. Threshold # 1 text box Displays the number of search string matches that must occur before producing a specified state For example, if the Match Count field value is 3, the search string must occur 3 times in the monitored file before the KM goes into the state specified by the State list. State list Specify the state that the KM will exhibit when the Threshold-Match Count value is reached: None, OK, Warn, or Alarm For example, if you want the KM to go into alarm if the search string is found 3 times in the monitored file, set the value of Threshold # 1 to 3 and select Alarm from the State list. Threshold # 2 text box If you want the KM to exhibit a second state when a different number of search strings occurs, enter the number of matched search strings in this text box. For example, if you set the Threshold # 1 to alarm when 3 occurrences of the search string are found and you want the KM to warn when 1 occurrence of the search string is found, enter 1 in the Threshold # 2 text box. Specify the state that the KM will exhibit when the Threshold# 2 value is reached: None, OK, Warn, or Alarm (optional) Specify the message text that you want to be displayed when your search string conditions are satisfied For more information, see Customizing event messages on page 67. 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. 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 Table 16 on page 68.
State list Custom Event Message text box
44
Table 15
Item
Description Specify an interval in minutes during which the product does not generate an event after the first match and its corresponding event After the specified time elapses, the search criteria generate an event for the next match.
Ignore duplicate events for next ... minutes text box
Number of Lines in Log Entry text box (Not applicable for an XML instance)
Specify the number of lines that you want to be displayed when a match is found For 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, a message similar to the following one is displayed 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 text box (Not applicable for an XML instance)
Displays 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 an alarm state when any of the search criteria is found in the monitored file and nullifies the alarm when the nullify string is found. You must specify atleast one search string in the String1 text box (in the Configure Search Criteria: instanceName 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). For example, if you specify Alarm up in the String1 text box of the search criteria 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. The alarm is nullified when Alarm down is found in the monitored file.
Once closing root-tag is found, Delete instance after minutes text box (Applicable only for an XML instance)
Specify an interval in minutes during which the product should not delete an instance even if the closing root-tag is found. After the specified time elapses, the product will delete the instance for which the closing root-tag is found.
Return to OK if no match If the KM goes into an alarm or a warning state because the search string is found on next scan check box found and you want the KM state to return to OK if the search string is not found on the next scan, select this check box.
45
Monitoring text files
Table 15
Item
Description Displays the priority level at which you want the text instance to be scanned:
s
Scan Priority list
Normal is associated with the LogMainColl collector. 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. Accept button Cancel button Click this button to save the properties and close the dialog box. Click this button to close the dialog box.
Monitoring text files

Using the PATROL KM for Log Management, you can monitor text log instances for a particular string, strings, or multiple patterns. You can configure the KM to always monitor from the beginning of the file, in case the file has been modified.
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 PATROL KM for Log Management PATROL Configuration Manager plug-in as described in Appendix C, PATROL Agent Configuration Variables.
To monitor a text instance 1 Access the LOG application menu as described in Appendix A, Accessing Menu
2 Select Add Instance.
46
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: instanceName dialog box,
enter the full path and file name for the file you want to monitor.
NOTE
s
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 Appendix B, Regular Expressions.
s s
6 Enter a logical name for the LOGMON instance that you want to monitor, which
appears in the event manager.
7 Select the Contains Environmental Variables 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 Beginning check 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.
47
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: A 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.
B 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.
C 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.
D (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 on page 67.
E 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 Table 16 on page 68. For more information, see Generating a custom event when a search string is found in the file on page 85 and Generating an alarm based on file age on page 80.
48
F 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 on page 66.
14 In the Number of Lines in Log Entry text 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.
49
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. 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
s
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 on page 66. You can also modify individual search criterion for an instance after you configure the instance. For more information, see To modify individual search criterion for an instance on page 67.
20 In the String1 text box, enter one of the following:

s
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 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.
50
NOTE
BMC does not recommend performing the following actions:
s
Entering multiple search patterns in the String1 text box, and selecting the Always Read At Beginning check box in step 10 on page 47 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 on page 48 through step F on page 49.
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:
s
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 on page 72 or Monitoring a file for multiple search criteria on page 77.
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 Appendix A, 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 on page 104.
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 on page 93.
52
Monitoring scripts, named pipes, or binary files
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.
Monitoring scripts, named pipes, or binary files

PATROL KM for Log Management enables you to monitor scripts, named pipes, and binary files along with the text and XML files. The output of these files is processed as for the text files. You can configure these files in the same way as a text instance. While configuring a script, named pipe, or binary file, you need to specify the appropriate file path in the File/Pipe Name text box and select the appropriate File Type option in the Add File for Label: instanceName dialog box. For more information, see Add File for Label: instanceName dialog box on page 34 and Monitoring a text instance on page 46.
Example for monitoring a script file on UNIX: Monitoring a file system for zero-byte files
This example describes how you can use the script output monitoring feature of the PATROL KM for Log Management to monitor a UNIX file system for files with a size of zero bytes. As this example shows, you can find either all the zero-byte files on the file system or just zero-byte files of a particular type.
53
Example for monitoring a script file on UNIX: Monitoring a file system for zero-byte files
To monitor a file system for zero-byte files 1 Write a script called find_zero_size_files that contains the following lines:
s
To find all zero-byte files, include these lines:
#!/bin/sh find $dir -size 0c -exec echo 0-byte file found: {} \; 2>/dev/null
To find zero-byte files of type *.js, *.html, and *.gif, include these lines:
# !/bin/sh
find /tmp -name "*.js" -size 0c -exec echo 0-byte file found: {} \; 2>/dev/null find /tmp -name "*.html" -size 0c -exec echo 0-byte file found: {} \; 2>/dev/null find /tmp -name "*.gif" -size 0c -exec echo 0-byte file found: {} \; 2>/dev/null
2 Access the LOG application menu as described in Appendix A, Accessing Menu

3 Select Add Instance. 4 In the Add Instance dialog box, enter a label for the script output, such as ZeroFiles.
The log icon label must be 50 characters or less and cannot contain any spaces.
5 Click Accept. 6 In the Add File for Label: instanceName dialog box, enter the full path to the
find_zero_size_files script, in the File/Pipe Name text box. Arguments are not
supported.
7 In the File Type options, select Script. 8 Define the default settings for the search criterion. 9 Click Next. 10 In the Configure Search Criteria: instanceName: Define Search Criterion dialog box,
in the Search Criterion area, enter an identification label for the search criterion in the Search Identifier text box.
11 Enter 0-byte file found: as String1. 12 Click Next. 13 In the Configure Search Criteria: instanceName: Override Default Settings dialog
box, click Next.
54
Example for monitoring a script file on Windows: Monitoring updates to an anti-virus package
14 In the Configure Search Criteria: instanceName: Summary dialog box, click Finish.
The Configure Search Criteria: instanceName: Summary dialog box closes and the PATROL KM for Log Management starts monitoring the script output that you added. The KM alarms if any zero-byte files are found on the file system.
Example for monitoring a script file on Windows: Monitoring updates to an anti-virus package
This example describes how you can use the script output monitoring feature of the PATROL KM for Log Management to monitor a Windows file system to determine whether updates have been made successfully to an anti-virus package.
To monitor anti-virus package updates 1 Write a batch file called C:\ProgramFiles\Local\VirusUpdate.bat that downloads the
updates to an anti-virus package. If the batch file runs successfully, it outputs, <current time and date> Download Successful and if it fails, it outputs <current time and date> Download Failed.
2 Access the LOG application menu as described in Appendix A, Accessing Menu

3 Select Add Instance. 4 In the Add Instance dialog box, enter a label for the anti-virus update file, such as
antivirus_update.
The log icon label must be 50 characters or less and cannot contain any spaces.
5 Click Accept. 6 In the Add File for Label: instanceName dialog box, enter
C:\ProgramFiles\Local\VirusUpdate.bat in the File/Pipe Name text box.
7 In the File Type options, select Script. 8 Define the default settings for the search criterion. 9 In the Threshold # 1 text box of the Add File for Label: instanceName dialog box,
enter 1.
10 From the State list, select Alarm. 11 Click Next.

Monitoring XML files
12 In the Configure Search Criteria: instanceName: Define Search Criterion dialog box,
in the Search Criterion area, enter an identification label for the search criterion in the Search Identifier text box.
13 In the String1 text box, enter Failed. 14 In the Configure Search Criteria: instanceName: Override Default Settings dialog
box, if you do not want to custom-define the search criterion, ensure that you do not select the Override default setting check box.
15 Click Next. 16 In the Configure Search Criteria: instanceName: Summary dialog box, click Finish.
When the log collector runs, the script runs the VirusUpdate.bat batch file and generates an error if it finds the string Failed in the output.
Monitoring XML files

PATROL KM for Log Management enables you to do the following:
s
Monitor the valid XML files with the following encodings:

s
s s
UTF-8 (This is the default encoding. If you do not specify the encoding for an XML file, it is assumed to be UTF-8). LATIN1 (English)
Configure searching and monitoring of the element content from the XML file against the specified elements (also called as tags).
NOTE
s
Use of the XML file search feature assumes that you have a working knowledge of XML file constructs and terminology. The KM only supports monitoring of the element content. It does not support monitoring of element attributes. To configure the search and monitor functions, you must use a BMC PATROL Console for UNIX or Microsoft Windows in Developer mode, a BMC PATROL Central console, or the PATROL KM for Log Management PATROL Configuration Manager plug-in.
56
How XML monitoring works
How XML monitoring works

You can provide multiple search criteria involving the same or different elements with respective expressions for a single XML instance. The KM parses the search criteria, and uniquely stores elements with their respective search patterns in a hierarchical order that you provided in the input. Therefore, it is very important to provide the same hierarchy for all search criteria for an XML instance; otherwise the search may not return expected results. The KM optimizes the XML search such that it executes search patterns, if any, for each element in the XML file, only once. It optimizes the XML search such that it executes duplicate search patterns for an element across different search criteria, only once. The KM evaluates the search criterion for a match upon reaching the closing tag of the first element in the input. The valid arithmetic expression is evaluated for each search criteria. Hence, it is important to provide the parent element when there is more than one element present in the search criterion, with an expression between them. When the search criterion is successful, the KM displays the matched content for all elements of that search criterion in the LOGMatchString parameter. If the provided regular expression does not match some element and yet the search criterion results in success, the product returns a string such as (not found) for such elements. It notifies you that though the search criterion matched, the respective search pattern did not match for the element. This can happen when there is an OR operation. Once the KM scans the whole file successfully, it generates events, if any, for each search criterion.
Monitoring an XML log instance

You can define multiple search criteria for an XML instance. Each of the search criteria can have a search identifier, XML search string, thresholds with their states, custom events, and so on.
57
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 script to monitor by using the PATROL KM for Log Management PATROL Configuration Manager plug-in as described in Appendix C, PATROL Agent Configuration Variables.
To monitor an XML instance 1 Access the LOG application menu as described in Appendix A, Accessing Menu
2 Select Add Instance. 3 In the Add Instance dialog box, enter a label for the XML 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 Add File for Label: instanceName dialog box, in the File/Pipe Name text box,
enter the full path and file name for the XML 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. For more information about using regular expressions, see Appendix B, Regular Expressions.
6 Specify a logical name for the LOGMON instance that you want to monitor, which
appears in the event manager.
7 Select the Contains Environmental Variables 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 XML file path are resolved. Otherwise, the XML file is treated as a pure file name.
8 Select XML File as the File Type option. 9 (Optional) To always read the log file from the beginning, rather than the portion
of the file that has been added since the last time the file was read, select the Always
Read at Beginning option.
58
10 (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 file disposition option to monitor all of the files.
11 Select the Generate ALARM if file not modified in check box if you want the KM to
generate an alarm if the file is not modified after a specific interval.
12 In the Minutes text box, specify the time after which an alarm will be generated if
the file is not modified.
13 (Optional) In the Default Settings For Search Criteria section, specify the default
search criterion as follows:
A Enter the Match Count for Threshold # 1 and # 2 and select a State. The selected
state option does not occur until the threshold count has been satisfied.
B In the Custom Event Message text box, define how you want the product to
respond when a search criteria is satisfied. The custom event must consist of string literals and the elements in the XML search string. For a detailed explanation and an example, see Customizing event messages on page 67. For more information, see Generating an alarm based on file age on page 80.
C In the Custom Event Origin text box, specify the 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.xmlFileName.
D 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 on page 66.
14 In the Once closing root-tag is found, Delete instance after minutes text box, enter the
number of minutes after you want to delete the instance if the closing root tag is found.
15 Select the Return to OK if no match found on next scan check box 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.
16 From the Scan Priority list, select a scan priority: Normal, Medium, or Low.
59
17 Click Next. 18 (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
s
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 on page 66. You can also modify individual search criterion for an instance after you configure the instance. For more information, see To modify individual search criterion for an instance on page 67.
19 In the String1 text box, enter the search string in one of the following formats:
s
A 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 on page 63. Search pattern (s). Each search pattern should be a valid regular expression. Enclose each pattern in parentheses ({}).
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. The KM will not generate any alarm if you specify only a single pattern in the String1 text box.
NOTE
BMC does not recommend performing the following actions:
s
Entering multiple search patterns in the String1 text box and selecting the Always Read At Beginning check box in step 9 on page 58 simultaneously. Entering a single search pattern in the String1 text box. The KM might not generate an alarm in this case. For example, {<Node1>attribute value</Node1>}
60
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 on page 72.
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 PATROL history. If you did not specify a search string, this message is benign.
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 on page 59 through step D on page 59.
22 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 multiple search patterns are not found within those polling intervals.
23 Click Next. 24 In the Configure Search Criteria: instanceName: Summary dialog box, do one of the
following:
s
To add 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.
25 Select the Discard changes option if you want to revert all changes made in this
dialog box and use the original Search list.
26 Click Finish. 27 (Optional) Access the LOGT application menu as described in Appendix A,
Accessing Menu Commands, InfoBoxes, and Online Help.
28 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.
61
Incremental scanning of an XML file
For more information, see To configure a recovery action for a log file based on file size on page 104.
29 (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 on page 93.
Incremental scanning of an XML file

PATROL KM for Log Management supports the incremental scanning of an XML file and generates events for the matched content in every polling cycle, irrespective of the presence of the closing root tag. While scanning an XML file, the product stores the offset of the last-closed second level tag. The product resumes scanning the updated portion of the file in the subsequent polling cycle. You can configure an XML instance to read the file from the beginning at all times, by selecting the Always read at beginning check box on the Add File for Label: instanceName dialog box. If you configure the instance to always read at the beginning, the product scans the entire file and generates events in each polling cycle. If the Always read at beginning check box is not selected, the product scans only the updated portion of the file. The product stores the offset of the last-closed second level tag. The product resumes scanning the updated portion of the file in the subsequent polling cycle.
NOTE
If you have configured an instance by using an version 2.6.00 or earlier versions of the product,
s s
The Always read at beginning check box is unchecked. When BMC PATROL Agent restarts, the file is scanned from the beginning for the first time because there are no previous offsets available.
62
Rules for entering XML search strings

Adhere to the following rules while configuring XML search strings.
s
The XML element (tag) name must contain only supported string literals. You cannot use regular expressions in the element name. However, you can use valid regular expressions in the element content to match the element content, as shown below:
s s s
<level>ERROR\|INFO\|SEVERE</level> <class>com.bmc.*</class> <pid>.*</pid>
You must provide an element name in an XML search string in the same hierarchy as that of the file that you want to monitor. You must use the <bmc_reg_ex> element to differentiate the OR such as |, AND such as &, and parentheses such as ( and ) regular expressions only, between elements as follows:
s s s
<bmc_reg_ex>&</bmc_reg_ex> <bmc_reg_ex>|</bmc_reg_ex> <bmc_reg_ex>(</bmc_reg_ex>
The sequence of special characters makes the combination of elements a regular expression. Following is an example of an XML file with element structure:
<rec> <vm>log_server</vm> <ts>2008-06-20 11:34:42.253 CEST</ts> <level>INFO</level> <class>com.bmc.log.XmlReader</class> <method>loadCeb</method> <ctx> <pid>WLSStartUpUser</pid> <appid>System</appid> <cname>StartUpManager</cname> <reqid>0</reqid> <sesid>NOSESSIONID</sesid> </ctx> <msg> <![CDATA[ *** Test message. ***]]> </msg> </rec>
63
The following examples show valid/invalid search strings:

s
Search String:
<rec><vm>log_server</vm></rec>
This search string returns all instances of the <vm> element contents as log_server.
s
Search string with the .* regular expression:
<rec><class>com\.bmc\.log\.XmlReader.*</class></rec>
This search string returns instances of the <class> element that begin with com.bmc.log.XmlReader.
s
Search string with the OR condition in the element content:
<rec><ctx><pid>anonymous\|A288796</pid></ctx></rec>
This search string returns instances of the <pid> element whose content is anonymous or A288796.
s
Search string with the OR regular expression:
<rec><level>INFO</level><bmc_reg_ex>|</bmc_reg_ex><ctx><pid> WLSStartUpUser</pid></ctx></rec>
This search string uses an OR operator to return instances of the <level> element whose content is INFO or instances of the <pid> element whose content is WLSStartUpUser and which is within the <ctx> element.
NOTE
The <level> and <ctx> elements are at the same level in the hierarchy and <pid> is a child of <ctx>, so <pid> must appear after <ctx> in the search string.
Search string with the AND regular expression:
<rec><method>unknown</method><bmc_reg_ex>&</bmc_reg_ex><ctx> <pid>anonymous</pid></ctx></rec>
This search string uses the AND operator to return instances of the <method> element whose content is unknown and instances of the <pid> element whose content is anonymous and which is within the <ctx> element.
64
Search string with OR and AND regular expressions:
<rec><vm>log_server</vm><bmc_reg_ex>|</bmc_reg_ex><level>SEVERE </level><bmc_reg_ex>&</bmc_reg_ex><class>com.bmc.log.XmlReader </class></rec>
This search string returns matches based on the precedence of AND over OR.
s
Search string with OR, AND, and parentheses regular expressions:
<rec><vm>log_server.*</vm><bmc_reg_ex>&</bmc_reg_ex><level> ERROR\|SEVERE</level><bmc_reg_ex>&</bmc_reg_ex><ctx><bmc_reg_ex> (</bmc_reg_ex><appid>logKM.*</appid><bmc_reg_ex>|</bmc_reg_ex> <cname>StartUpManager</cname><bmc_reg_ex>)</bmc_reg_ex></ctx> <bmc_reg_ex>|</bmc_reg_ex><msg>.*</msg></rec>
You can combine the expression between elements and the regular expression provided for element content. You can provide complex expressions between elements involving only &, |, (, and ). The expression that you obtain by replacing the search pattern for each element with 1 or 0 (matched or not matched) should be a valid arithmetic expression; if not, the respective search criterion is discarded from the search. This search string returns matches based on the result of the arithmetic expression.
s
Hierarchy in the search criteria: In an XML instance, all the search criteria must have the same hierarchy. The following shows an invalid hierarchy: Criteria 1:
<rec><vm>.*</vm></rec>
Criteria 2:
<ctx><pid>.*</pid></ctx>
If Criteria 1 and 2 are provided for the same XML instance they may not return expected results. However, they would return appropriate results if they are under two separate instances. Following are the examples for valid hierarchy: Criteria 1:
<rec><vm>.*</vm></rec>
65
Viewing search criteria for an instance
Criteria 2:
<rec><ctx><pid>.*</pid></ctx><rec>
s
Invalid search string:
<*pid>.*java.*</*pid>
The above search string is invalid because the element name contains a regular expression.
Viewing search criteria for an instance

You can view the search patterns of the configured search criterion for an instance. You can view the following attributes of the search criteria:
s s
Search identifier of a search criterion Search pattern of a search criterion
To view the configured search criteria for an instance 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Report Configuration.
Modifying search criteria for an instance

You can view and modify, if required, already defined search patterns and the properties of an individual search criterion. You can modify the search patterns for text as well as XML instances from an already defined search list.
To modify the default search criterion settings for an instance 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Modify => Default Settings.
66
Customizing event messages
3 In the Change File for Label: instanceName dialog box, make the required changes.
For information about the Change File for Label: instanceName dialog box, see Change File for Label: instanceName dialog box on page 43.
4 Click Accept. To modify individual search criterion for an instance 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Modify => Search Criteria.

The defined search criteria for the instance is displayed.
3 In the Configure Search Criteria: instanceName: Summary dialog box, select the
search criterion that you want to modify and select the Modify option. For more information about this dialog box, see Configure Search Criteria: instanceName: Summary dialog box on page 42.
4 Click Update. 5 In the Configure Search Criteria: instanceName: Define Search Criterion dialog box,
modify the search criterion and click Next. For more information about this dialog box, see Configure Search Criteria: instanceName: Define Search Criterion dialog box on page 38.
6 In the Configure Search Criteria: instanceName: Override Default Settings dialog

box, make the required changes and click Next. For more information about this dialog box, see Configure Search Criteria: instanceName: Override Default Settings dialog box on page 40.
For more information about this dialog box, see Configure Search Criteria: instanceName: Summary dialog box on page 42.

You can customize messages that are displayed in events. The message must consist of string literals and the elements provided in the search string. For a text instance, the message can contain only string literals and built-in macros.
Built-in macros
You can use built-in macros to customize messages for text as well as XML instances.
Table 16 describes the built-in macros supported by the KM. Table 16

Macro %FILENAME %SEARCHID% %INSTANCE% %APPCLASS% %PARAMETER% %LOGICALNAME% %x %x-%y
Built-in macros
Description displays the log file name. displays the search identifier. displays the name of the LOGMON instance. displays the class name of the text instance. displays the parameter name related to the text instance. displays the logical name. displays the xth element from the matched string in an XML instance, where x is an element. displays the x through y columns from the matched string in a text instance, where x and y are numbers.
Elements
The custom event displays only the element content or attribute values that are present in the search string. Thus, a custom event message is a subset of the search string result. Thus, %x displays content of the xth element when there is a match from the respective search string. For example, suppose that the XML search string is as follows:
<rec><vm>log_server</vm><level>SEVERE</level><class>com.bmc.log.XmlReader </class></rec>
To get the content of the <vm> element in the event, the custom event should include %1, where %1 is substituted with the content of the second element (that is, <vm>). Thus, %1 corresponds to the <vm> element, %2 corresponds to the <level> element, and %3 corresponds to the <class> element and so on. The value increments with every element that is provided with some regular expression to match. You can also specify a range of elements by using %x-%y, where x and y are numbers. The %x-%y includes the content of all the elements ranging from x to y, including both x and y, in the respective event. To include the content of all the elements from the match string, you can provide %1- in the custom event message.
String Literals
You can also add constant string literals in the custom event message. For example, you could use the following text:
The book name is %1.
68
Stopping and starting the monitoring of the default log file
Stopping and starting the monitoring of the default log file

By default, the PATROL KM for Log Management monitors the PATROL Agent error log.
Before you begin

To stop or start monitoring the default log file 1 Access the LOG application menu as described in Appendix A, Accessing Menu
2 Select Enable/Disable Default Log Monitoring. 3 In the Default Log Monitoring dialog box, to stop monitoring of the default log file,
clear the Enable Default Log File Monitoring check box. If you want to start monitoring the default log files, ensure that the Enable Default Log File Monitoring check box is selected.
NOTE
The Default Monitoring dialog box only enables and disables monitoring of the log file that the PATROL KM for Log Management monitors by default. This dialog box does not control monitoring of log files that you add to the list of monitored files. To add or remove log files from the list of monitored files, see Stopping the monitoring of a file on page 70.
Monitoring files in Unicode format

Using the PATROL KM for Log Management, you can monitor files in Unicode format. The Unicode file format is recognized by using BOM characters. Depending on the encoding format such as UTF8, UTF16 BE (big endian), or UTF16 LE (little endian), the file is monitored. Configuring files in the Unicode format is similar to configuring text files in PATROL KM for Log Management. Set up a log file for monitoring as described in Monitoring text files on page 46.
69
Stopping the monitoring of a file
Before you begin

Limitations
PSL, PATROL Agent, and PATROL Console do not support the Unicode file format. Thus, the KM is unable to monitor or accept match strings in multibyte characters. If the data contains a multibyte character set, there is data loss. The KM displays the result in the ASCII format. The KM monitors a file with the ASCII character set and that uses the UTF 8 or UTF 16 encoding format. It does not search a file with multibyte character set nor display a match string.
Stopping the monitoring of a file

If you want to stop monitoring a file, you must remove the undesired files from the list of monitored files.
Before you begin

To stop monitoring a file 1 Access the LOGT application menu as described in Appendix A, Accessing Menu
2 Select Delete Instance. 3 In the confirmation dialog box, click Yes.

PATROL KM for Log Management no longer monitors that log file.
70
Scanning a monitored file from the beginning
WARNING
When a monitored file is discovered or created and later deleted from the system, the LOGMON instances continue to be created with the ALARM status. However, if you manually remove the files and restart PATROL Agent, the LOGMON instances are no longer created for the deleted files.
Scanning a monitored file from the beginning

You can configure PATROL KM for Log Management to read from the beginning of the text file that is being monitored. The PATROL KM for Log Management reads the monitored file from the beginning in the following scenarios:
s
during the initial monitoring scan of the file when the Always Read at Beginning check box in the Add File for Label: instanceName dialog box is selected However, the file is scanned only if the size of the file changes after the last scan, thus resulting in change in the time stamp of the file.
when the size of the monitored file reduces when the monitored file is a script when monitoring a file configured with regular expressions that has the File Disposition option. PATROL scans the newly created or discovered files that match the search criteria from the beginning. This includes a file that was previously scanned and superseded by a new file, and later modified, so that the file becomes the Latest file.
when the Modify => Default Settings or Modify => Search Criteria menu command is selected and the /PMG/CONFIG/updateOnConfigChange pconfig variable does not exist or is set to 0. This causes PATROL to read the monitored file from the beginning in the next scan.
71
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:
s s s s s s
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 Appendix B, 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.
NOTE
BMC does not recommend entering a single search pattern. The KM might not generate any alarm in this case.
Before you begin

72
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: A On the Add File for Label: instanceName dialog box, click Next to go to the
Configure Search Criteria: instanceName: Define Search Criterion dialog box.
B 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 Appendix B, 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 processes on page 76. 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.
73
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:
s s s s
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:
s s s s s s
less than, < greater than, > equal, = less than or equal, <= greater than or equal, >= not equal to, !=
op2 can be one of these operators:

s s
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 on page 46.
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:
74
1 On the Add File for Label: instanceName dialog box, click Next to navigate to the
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
on page 46.
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: A On the Add File for Label: instanceName dialog box, click Next to go to the
B 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 on page 63.
4 Click Next and fill out or modify the rest of the dialog box fields as described in
Monitoring an XML log instance on page 57.
75
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:
<?xml version="1.0" encoding="UTF-8"?> <rec> <pid>12345</pid> <appid>System</appid> <level>ERROR</level> <procname>StartUpProcess</procname> <pid>WLSStartUpUser</pid> <reqid>0</reqid> <sesid>SESSIONID</sesid> </rec>
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 on page 63.
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 on page 57.
76
Monitoring a file for multiple search criteria
Monitoring a file for multiple search criteria

PATROL KM for Log Management provides the ability to search files for multiple criteria. The Configure Search Criteria: instanceName dialog box contains fields to define search criteria and for entering search strings. If you need to search a file for more than two strings, you can either use regular expressions to increase the number of strings the KM searches for, or you can create multiple instances of the same log file that search for multiple messages.
Using regular expressions to create a search criterion to match multiple words

You can use regular expressions to search for multiple, discreet words in a log file. For example, you may want to search a log file for the following stringsError, Warning, or Severe.
Before You Begin

Creating a search criterion for multiple words

To set up a single search criterion to find multiple words 1 On the Configure Search Criteria: instanceName: Define Search Criterion dialog
box, in the String1 text box, enter the words you want to search the log file for, separated by a backslash (\) followed by a vertical bar (|). For example, if you want to match any line in the log file that contains any combination of the words Error, Warning, or Severe, you would enter the search string as follows:
Error\|Warning\|Severe
77
Searching a file for two or more complex messages

The simplest way to search for multiple complex strings is to create multiple search criteria for a file. Even though the Configure Search Criteria: instanceName dialog box contains only two string fields, you can search for multiple strings in a single log file by creating one log definition per discreet search string. Each defined search string is represented by an instance of the LOGT application and contains one or more instances of the monitored file. If you want to monitor for multiple messages related to the CPU, DISK, memory, or other functions, you would create a log definition for each message rather than attempting to search for multiple messages using one definition.
Example: Monitoring the PATROL Agent Error log

The PATROL KM for Log Management monitors the PATROL Agent Error log by using two log definitions labeled PAgentLog_Warn and PAgentLog_Alarm. As an example of how you can use two definitions to monitor a single file, this section illustrates the process of setting up these two log definitions for the PATROL Agent error log. The PAgentLog_Warn definition is configured to search for any of the following messages in the agent error log:
s s s s
remaining for PATROL license to expire Not authorized connect agent Please check parameter history for corruption PatrolAgent-E-EFORK: Couldn't fork a new process
If any of these strings are found in the agent error log, the KM generates a WARN event.
To set up the PAgentLog_Warn definition 1 Access the LOG application menu as described in Appendix A, Accessing Menu
2 Select Add Instance. 3 In the Add Instance dialog box, enter PAgent_Warn in the Enter Label for New File to
be Added text box.
4 Click Accept. 5 In the Add File for Label: instanceName dialog box, enter
$PATROL_HOME/log/PatrolAgent-hostname-port_number.errs in the File/Pipe Name
text box.
78 BMC PATROL Knowledge Module for Log Management User Guide
6 Select Text File as the File Type option. 7 Click Next. 8 On the Configure Search Criteria: instanceName dialog box: Define Search
Criterion, define a unique identification label for the search criterion.
9 In the String1 field, enter the following string:

$remaining for PATROL license to expire$\|$Not authorized connect agent$|$Please check parameter history for corruption$\|$PatrolAgent-E-EFORK: Couldn't fork a new process$
box, do the required changes and click Next.
Now add the log file definition for PAgentLog_Alarm. The PAgentLog_Alarm definition is configured to search for any of the following messages in the agent error log:
s s s s s s
found inconsistencies PatrolAgent-W-EINTERNAL: PatrolAgent is running low on memory PatrolAgent: not superuser Please check parameter history for corruption runqSchedPolicy is now set to 9 Detected during operation readRec.fseek
If any of these strings are found in the agent error log, the KM generates an ALARM event.
To set up the PAgentLog_Alarm definition 1 Access the LOG application menu as described in Appendix A, Accessing Menu
2 Select Add Instance. 3 In the Add Instance dialog box, select Text Instance and enter PAgent_Alarm in the
Enter Label for New File to be Added text box.
4 Click Accept.
79
Generating an alarm based on file age
5 In the Add File for Label: instanceName dialog box, enter

$PATROL_HOME/log/PatrolAgent-hostname-port_number.errs in the File/Pipe Name
text box.
6 Select the file type option, Text File. 7 Click Next. 8 On the Configure Search Criteria: instanceName: Define Search Criterion dialog
box, define a unique identification label for the search criterion.
9 In the String1 text box, enter the following string:

$found inconsistencies$\|$PatrolAgent-W-EINTERNAL: PatrolAgent is running low on memory$\|$PatrolAgent: not superuser$\|$Please check parameter history for corruption$\|$runqSchedPolicy is now set to 9$\|$Detected during operation readRec.fseek$
box, do the required changes and click Next.
PATROL adds the log file to the list of monitored log files.
Generating an alarm based on file age

If a file has not been modified within a specified period of time, you can configure the PATROL KM for Log Management to generate an alarm.
Before you begin

80
Generating an alarm based on file size
To configure the KM to alarm based on file age 1 Depending on whether you are adding a new log file to be monitored or changing
an existing log file, access the either of the following, as described in Add File for Label: instanceName dialog box on page 34 and Change File for Label: instanceName dialog box on page 43.
s s
Add File for Label: instanceName dialog box Change File for Label: instanceName dialog box
2 Select the Generate ALARM if file not found in check box. 3 In the Minutes text box, enter the number of minutes for which you want the file to
be unchanged before the KM goes into alarm.
text instance on page 46 or Monitoring an XML log instance on page 57.
Generating an alarm based on file size

You can configure the PATROL KM for Log Management to generate an alarm when the size of the monitored file exceeds a specified threshold.
Before you begin

To configure the KM to alarm based on file size 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Advanced Features => Configure Alarm. 3 In the Configure Alarm dialog box, select the Generate Alarm if file size exceeds
threshold in kilobytes check box, and specify the file size at which you want an
alarm to be generated.
4 Click OK.
81
Generating an alarm when the time stamp of a file changes
Generating an alarm when the time stamp of a file changes

You can configure the PATROL KM for Log Management to generate an alarm when the time stamp of the monitored file changes.
Before you begin

To configure the KM to alarm when the time stamp of a file change 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Advanced Features => Configure Alarm. 3 In the Configure Alarm dialog box, select the Generate Alarm if file timestamp is
changed check box.
4 Click OK.
PATROL displays the LogFileTimeStampStatus parameter in the console.
Generating an alarm when the permissions of a file change

You can configure the PATROL KM for Log Management to generate an alarm when the permissions of the monitored file change.
Before you begin

82
Generating an alarm when a number of matches is found over a period of polling cycles
To configure the KM to alarm when the permissions of a file change 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Advanced Features => Configure Alarm. 3 In the Configure Alarm dialog box, select the Generate Alarm if file permissions are
changed check box.
4 Click OK.
PATROL displays the LogFilePermissionStatus parameter in the console.
You can specify default settings of an alarm for all search criteria and override these settings for an individual search criterion while adding an instance. For more information, see Monitoring a text instance on page 46. You can also modify the default settings and individual search criterion for an existing instance.
To modify the default settings for generating an alarm when a number of matches is found over a period of polling cycles for an existing instance 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Modify => Default Settings. 3 In the Change File for Label: instanceName dialog box, in the Threshold text box, set
the threshold for the number of matches per the number of polling cycles separated by a colon (:). Select the state for breaches of that threshold from the State list.
EXAMPLE
If the threshold value is 10:5, 10 matches must occur over a period of 5 polling cycles before the KM goes into the state specified in the State list.
83
4 Click Accept. NOTE

This feature is not available if you are monitoring an XML file.
To specify the individual search criterion for generating an alarm when a number of matches is found over a period of polling cycles for an existing instance 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Modify => Search Criteria.

The defined search criteria for the instance is displayed.
3 In the Configure Search Criteria: instanceName: Summary dialog box, select the
search criterion that you want to modify and select the Modify option. For more information about this dialog box, see Configure Search Criteria: instanceName: Summary dialog box on page 42.
4 Click Update. 5 In the Configure Search Criteria: instanceName: Define Search Criterion dialog box,
modify the search criterion and click Next. For more information about this dialog box, see Configure Search Criteria: instanceName: Define Search Criterion dialog box on page 38.
6 In the Configure Search Criteria: instanceName: Override Default Settings dialog

box, make the required changes and click Next. For more information about this dialog box, see Configure Search Criteria: instanceName: Override Default Settings dialog box on page 40.
For more information about this dialog box, see Configure Search Criteria: instanceName: Summary dialog box on page 42.
84
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:
s s s s
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-.
NOTE
If you want to have the % character appear in the message, enter %%. For example, entering Disk %3 is %5 %% full displays the 3rd and 5th strings in the match line, such as Disk /dev/sd0 is 45 % full.
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 on page 76.
NOTE
If you do not create a custom event message, you will still receive the standard event generated by the LOGErrorLvl parameter when your search string is found.
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.
85
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 on page 67.
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: instanceName dialog box on page 34 and Change File for Label: instanceName dialog box on page 43.
s s
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 Entry text 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;
86
Example: Creating a custom event message that displays when a service fails to initialize
NOTE
s
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
Example: Creating a custom event message that displays when a service fails to initialize
This example shows you how to create a custom event message to display the following event message when a service fails to initialize:
GX6 component <ITD> failed initializing service it_execd,. See logfile \var\opt\GX6\log\it_execd.log, for details.
The sample log file entry looks similar to this (with the exception that a real log file entry would fit on one line):
"20030508_124352 <ITD> ExecInitialize failed (szServicesEntry: it_execd, szAccessControlList:\opt\GX6\etc\it_execd.acl, szLogFile: \var\opt\GX6\log\it_execd.log, usllSrv: 7)"
87
Example: Creating a custom event origin that displays the event origin according to Macros specified in the
To create the custom event message, in the Custom Event Message text box, enter:
GX6 component %2 failed initializing service %6. See logfile %10 for details.
Example: Creating a custom event origin that displays the event origin according to Macros specified in the configuration
This example shows you how to create a custom event origin to display the event origin according to macros specified in the configuration. If you create an instance such as inst1 with a search identifier, id1:
%APPCLASS%.%INSTANCE%.%SEARCHID%
The LOGGeneral and NOTIFY_EVENT Event Class will display the following Event Origin:
LOGMON.inst1PN0.id1
For more information about built-in macros, see Built-in macros on page 67.
Generating and nullifying an alarm based on dual-search strings

You can configure the PATROL KM for Log Management to generate an alarm based on two search strings. You can configure dual search for a text instance so that the PATROL KM for Log Management goes into the alarm state when the first string is found in the monitored file and then nullifies the alarm when the second string is found.
Before you begin

88
Generating an alert after a specified number of strings have been found
To configure the KM to alarm based on dual-search strings for a text instance 1 Depending on whether you are adding a new log file to be monitored or changing
an existing log file, access the either of the following, as described in Add File for Label: instanceName dialog box on page 34 and Change File for Label: instanceName dialog box on page 43.
s s
2 Enter the nullify search string in the Nullify Alarm/Warn String text box. 3 If you are in the Add File for Label: instanceName dialog box, click Next to navigate
to the Configure Search Criteria: instanceName: Define Search Criterion dialog box and enter the first search string in the String1 text box. The PATROL KM for Log Management goes into an alarm state when the first string (for example, Alarm up) is found in the monitored file and nullifies the alarm when the second string (for example, Alarm down) is found.
Generating an alert after a specified number of strings have been found

The PATROL KM for Log Management generates alerts based on a specified number of lines that contain search strings or numeric comparisons in a monitored file. For example, you could configure the KM to search for the string Corrupt and specify that the KM should generate an alarm if the KM finds four lines containing the word Corrupt in a single scan of the monitored file. You could also configure the KM to generate a warning if the string is found twice and an alarm if the string is found more than four times. If the string is not found on a successive scan of the file, you can configure the KM to return to an OK state.
Before you begin

You must be using the PATROL Central Operator - Windows Edition, PATROL Central Operator - Web Edition, PATROL Console in Developer mode, or the PATROL KM for Log Management PATROL Configuration Manager plug-in.
89
Sending a notification when a string has been matched
To generate an alert after a specified number of string or numeric occurrences 1 Depending on whether you are adding a new log file to be monitored or changing
an existing log file, access the Add File for Label: instanceName dialog box or the Change File for Label: instanceName dialog box, respectively as described in Add File for Label: instanceName dialog box on page 34 and Change File for Label: instanceName dialog box on page 43.
2 In the Threshold # 1 text box, enter the number of lines in which the string or
numeric comparison must occur per scan before an alert is generated.
3 In the associated State list, choose the type of alert that you want the KM to
generate when the number of strings or numeric comparisons exceeds the value in the Threshold # 1 field.
4 (Optional) In the Threshold # 2 field, enter the number of lines in which the string or
numeric comparison must occur per scan before another type of alert is generated.
5 (Optional) In the associated State list, choose the type of alert that you want the KM
to generate when the number of strings or numeric comparisons exceeds the value in the Threshold # 2 field.
6 (Optional) Select the Return to OK if no match found on next scan check box to return
the KM to an OK state if the string is not found on the next scan of the monitored file.
Sending a notification when a string has been matched

If you are using the PATROL KM for Log Management in conjunction with the PATROL KM for Event Management, you can send an event, email, page or other notification when the PATROL KM for Log Management goes into alarm. The following example is a ruleset that you could use in the PATROL KM for Event Management to capture the data from LOGMatchString for the instance and deliver this information in a notification when the LOGErrorLvl parameter of the LOGMON application class goes into Warn or Alarm for any PATROL KM for Log Management definition.
PATROL_CONFIG "/AS/EVENTSPRING/LOGMON/__ANYINST__/LOGErrorLvl/arsAction" = { REPLACE = "6" }, "/AS/EVENTSPRING/LOGMON/__ANYINST__/LOGErrorLvl/arsCmdType" = { REPLACE = "PSL" }, "/AS/EVENTSPRING/LOGMON/__ANYINST__/LOGErrorLvl/arsCommand" = { REPLACE = "__udefvar__=get(\"/LOGMON/\".__instance__.\"/LOGMatchString/value\");" }
90
Creating a blackout period for KM event generation
For detailed instructions on configuring notification, see the PATROL Knowledge Module for Event Management User Guide.

PATROL Knowledge Module for Log Management allows you to configure the KM to temporarily stop generating events for the purpose of backing up the file or some other action that might cause the PATROL KM for Log Management to alarm temporarily. There are two methods that you can use to do this.
s
To programmatically suspend event generation for a file, you can direct a process to write the label for that file into a flag file. When the files label is written to the flag file, the KM stops generating events for that file. To start generating events for those files when the process is complete, direct the process to remove the labels from the flag file. The PATROL KM for Log Management provides a default flag file named PMGSuspend. This file is located in $PATROL_HOME on UNIX or %PATROL_HOME% on Windows. If you move the PMGSuspend flag file to another directory or create a new flag file, you must redirect the PATROL KM for Log Management to the new flag file or flag file location as described in To direct the KM to a new flag file or flag file location: on page 92.
To suspend event generation for a period of time, use the PATROL KM for Log Management interface as described in To suspend KM event generation for a specified time period. For example, if you are monitoring a backup application for tape write errors and you know that these errors usually occur in large amounts as the drive retries, then you can use this feature to prevent generating events during the time the drive is retrying unless the number of errors exceeds a defined limit.
To suspend KM event generation for a specified time period 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Advanced Features => Configure Log Monitoring Blackout. 3 In the Configure Log Monitoring Blackout dialog box, enter the number of minutes
that you want to temporarily stop monitoring the selected file.
91
4 (Optional) If you want the PATROL KM for Log Management to go into alarm if a
certain number of events occur during the blackout period, select the Override if errors exceed count check box and enter the maximum number of events that can occur during the blackout period before the KM goes into alarm.
5 Click OK.
The PATROL KM for Log Management immediately suspends generating events for the file until the specified number of minutes has passed or the specified number of errors has occurred. You can manually add the /PMG/CONFIG/suspendAll configuration variable to suspend all the instances configured under the PATROL KM for Log Management. You can enter the following values for this variable: s 1= suspends all the instances s any value other than 1 = removes suspension from all the instances When using the KM interface, the suspendAll variable and the PMGSuspend flag file take precedence over the Suspend KM event generation for a specified time period option.
To direct the KM to a new flag file or flag file location: 1 Access the LOG application menu as described in Appendix A, Accessing Menu
2 Select Identify Flag Directory. 3 In the Identify Flag Directory dialog box, enter the full path to the directory where
the flag file is located. The flag file directory must meet the following requirements:
s s s
The directory must exist on the system. The PATROL default account must have read permissions on the directory. On UNIX, do not use the /tmp directory as the log file directory. Many UNIX systems clear the /tmp directory upon system reboot.
4 Click Apply.
92
Scheduling file monitoring
Scheduling file monitoring

The KM scans files at each polling cycle (every two minutes by default), continuously. You can define the KM to schedule scans on a weekly basis and multiple schedules for weekdays including adding different schedules for each day. If you want to only scan files for a particular time period each day, you can schedule the KM to scan files starting at a specific time of day for a specified duration. For example, you can configure the KM to start scanning a file every day at 09:00:00 for a duration of three hours. During the specified time, the KM scans the file, ending the scan at 12:00:00. It scans the file every two minutes during the specified time period. While monitoring the latest log file, when the KM discovers a new log file during a polling cycle, it monitors the earlier log file as well as the new file discovered during that polling cycles.
To schedule a file scan 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Advanced Features => Schedule Log Scan. 3 In the Schedule Log Scan dialog box, enter the time of day that you want to start
monitoring in the Start Time of Day text box. (Use a 24-hour clock.)
4 In the Scheduled Duration text box, enter the length of time that you want the scan
to run in hours, minutes, and seconds.
5 Select one or more of the Sunday, Monday, Tuesday, Wednesday, Thursday, Friday,
Saturday, All Weekdays check boxes depending on the day(s) of the week when you want to schedule a log scan. All Weekdays allows you to define a schedule on a
daily basis.
6 (Optional) If you want the KM to go into alarm if the string is not matched during
the specified scan time, select the Generate Alert if no Match Found at Scan End check box.
7 (Optional) If you want to enter the actual end time of the schedule instead of the
scheduled duration, select the Consider Scheduled Duration as Scheduled End time check box. This is global to all schedules.
8 Click Add to add the defined schedule to List Scheduled Log. 9 Click Delete to delete a schedule from List Scheduled Log. 10 Click Update to execute the Add and Delete operations and update the list of
scheduled log files.
Defining limits to search a block of lines containing a match string
To hold the scheduled list, use the PMG/CONFIG/label/actSchedlList configuration variable. To set the specified duration to be considered as the End time, use the PMG/CONFIG/label/actDurAsEndTime configuration variable. You must add these variables manually. If you are modifying an existing LOG application instance that was created using PATROL KM for Log Management 2.4.20 or earlier, you must convert the old format of the scheduled log scanning to the new format. This deletes the PMG/CONFIG/label/actResetCount, PMG/CONFIG/label/actStart, and PMG/CONFIG/label/actDur configuration variables, and creates the PMG/CONFIG/label/actSchedlList and PMG/CONFIG/label/actDurAsEndTime configuration variables. However, the KM creates only the PMG/CONFIG/label/actSchedlList and PMG/CONFIG/label/actDurAsEndTime variables under the following circumstances:
s
You configure the scheduled log scan for a new LOG application instance with version 2.5.00 or later of the PATROL KM for Log Management. You modify a LOG application instance created using version 2.4.20 or earlier of the product, which does not have a scheduled log scan.
PATROL KM for Log Management scans the file every day at the specified time for the specified duration.
Defining limits to search a block of lines containing a match string

PATROL KM for Log Management enables you to define a block of lines that should be returned as the output when a match string is found in that block. You can specify start and end delimiter strings to define the block. The KM then works in the multiline mode, and does not perform a regular search string operation. The following scenarios can occur in the multiline mode:
s
If the KM finds the start delimiter, it continues to search for the match string and the end delimiter. After it locates the match string and the end delimiter, it displays the strings between the start delimiter the end delimiter. If the KM finds the start delimiter in one polling cycle and the end delimiter in a subsequent polling cycle, the KM starts reading the file from the offset where it found the last start delimiter. If the KM finds the match string and reaches the end of the file (EOF) before it locates an end delimiter, the KM assumes that the end delimiter had been found.
94
Retaining old log file instances
To enable multiline searching 1 Access the LOGT application menu for the instance as described in Appendix A,
2 Select Advanced Features => Multiline Search. NOTE

The Multiline Search option is not available while monitoring an XML file.
3 In the Multiline Search dialog box, in the Start Delimiter text box, specify the
starting point in the monitored file from which you want to start searching a match string.
4 In the End Delimiter text box, specify the ending point in the monitored file at
which you want to stop searching the match string.
5 Click Accept.
The KM validates the data and performs searches in the multiline mode. If you have not entered valid data, the KM displays an error. To define the maximum multiline block size, use the
/PMG/CONFIG/logmonInstance/actMaxRecordSize configuration variable.
To define the maximum multiline block sent to the event message, use the
/PMG/CONFIG/logmonInstance/actMaxReturnedRecordSize configuration variable.
For information about these variables, see Table 23 on page 118.
Retaining old log file instances

PATROL KM for Log Management allows you to specify the number of old log instances to retain and perform an action when a monitored log instance is deleted.
To specify product configuration for old instances 1 Access the LOG application menu as described in Appendix A, Accessing Menu
2 Select Product Configuration.
95
Retaining the log file instance during configuration changes
3 In the Product Configuration dialog box, enter the number of old log instances that
you want to retain, plus 1 for the latest log instance. By default, the value in the Number of Old Instances text box is 1, which refers to the the latest log instance retained.
4 Select an action that you want the KM to take when a monitored log is deleted.
By default, the KM generates an alarm when a monitored text log is deleted.
Retaining the log file instance during configuration changes

PATROL KM for Log Management deletes a log file instance when the configuration of the log file instance changes. To retain the log file instance, you must manually add the /PMG/CONFIG/updateOnConfigChange configuration variable, and specify the value of this variable as 1. For information about the /PMG/CONFIG/updateOnConfigChange variable, see Table 23.
WARNING
This variable only works with log files in the text format.
For information about how to add configuration variables to the Agent Configuration utility, see Managing configuration variables on page 118.
To retain the log file instance during configuration changes to the log file 1 Create the /PMG/CONFIG/updateOnConfigChange configuration variable
manually.
WARNING
If the /PMG/CONFIG/updateOnConfigChange configuration variable is not added manually, the log file instance is deleted on a configuration change.
2 Specify the value of the configuration variable as 1.

The log file instance is retained, and the changes made to the log file templates are sent to pmgreader during the next log scan. PATROL KM for Log Management scans the log file by using the updated configuration from the last read point of the log file in the earlier scan.
Using the PATROL Configuration Manager to configure the PATROL KM for Log Management
Using the PATROL Configuration Manager to configure the PATROL KM for Log Management
The PATROL Configuration Manager includes the Log KM Configuration Plug-in, which allows you to configure the Log KM to monitor specific log files without using a PATROL Console.
Plug-in actions
The Log KM Configuration Plug-in interacts with PATROL Configuration Manager based upon the task that you are performing. When adding rulesets to establish and configure monitoring, you use the Agent tree view pane. When updating or deleting rulesets, you use the RuleSets tree view pane.
Adding/specifying object instances to monitor

Configuring PATROL to monitor aspects of an application involves creating an instance for the object being monitored, such as a log file, and establishing a ruleset. This procedure is initiated in the Agent tree view pane.
To add an object instance 1 In the Agent tree view pane, click and select an agent. 2 Right-click the agent and select Log KM Configuration => Log Files. 3 In the configuration dialog box that the configuration manager displays, click Add. 4 In the dialog box for creating instances, type the required information in the
appropriate fields, as described in Table 17. Table 17
Fields New Instance Label Monitored Filename
New Instance dialog boxes and fields

Description Enter a descriptive name (as you want it to appear in PATROL) that identifies the log that you want to monitor. Enter the path and filename of the log that you want to monitor.
5 Click OK.
97
Plug-in actions
6 Select each tab and provide the relevant information in the configuration dialog
box. For more information about the Log KM Configuration dialog box, see Add File for Label: instanceName dialog box on page 34 and Change File for Label: instanceName dialog box on page 43.
7 Click Apply to save your changes and leave the dialog box open, or OK to save the
changes and close the dialog box.
Updating monitored object instances

Changing how PATROL monitors aspects of an application involves editing a ruleset. This procedure is initiated in the RuleSet tree view pane.
1 In the RuleSet tree view pane, expand the RuleSet folder. 2 Navigate to the backup ruleset of the agent whose object instance monitoring you
want to update. Expand PCM => backup => backup_container => agent => ccyymmdd-hhmmss_ruleset.
3 Right-click the ruleset and select Log KM Configuration => Log Files. NOTE
If no object instances have been added for monitoring, the menu command is inactive. For more information about adding an object instance for monitoring, see Adding/specifying object instances to monitor on page 97.
4 In the configuration dialog box that the configuration manager displays, select an
instance from the instance list and click Update.
5 Select the appropriate tab and edit the relevant information in the configuration
dialog box. For more information about the Log KM Configuration dialog box, see Add File for Label: instanceName dialog box on page 34 and Change File for Label: instanceName dialog box on page 43.
6 Click Apply to save your changes and leave the dialog box open, or OK to save the
changes and close the dialog box.
98
PATROL KM for Log Management configuration
Deleting monitored object instances

Stopping PATROL from monitoring aspects of an application involves deleting a ruleset. This procedure is initiated in the RuleSet tree view pane.
1 In the RuleSet tree view pane, expand the RuleSet folder. 2 Navigate to the backup ruleset of the agent whose object instance monitoring that
you want to update. Expand PCM => backup => backup_container => agent => ccyymmdd-hhmmss_ruleset.
3 Right-click the ruleset and select Log KM Configuration => Log Files. NOTE
If no object instances have been added for monitoring, the menu command is inactive. For more information about adding an object instance for monitoring, see Adding/specifying object instances to monitor on page 97.
4 In the configuration dialog box that the configuration manager displays, select an
instance from the instance list.
5 Click Delete. 6 Click Apply to save the deletion and leave the dialog box open, or OK to save the
deletion and close the dialog box.

The purpose of the Log KM Configuration Plug-in is to configure the PATROL KM for Log Management to monitor specific log files.
s
The General tab specifies a log or set of logs that you want to monitor. For the PATROL KM for Log Management to monitor the desired log, the log must meet all the criteria specified in this dialog box. The Configure Log Monitoring Blackout tab suppresses alerts that occur within a short span of time and may all have the same root cause. This option enables PATROL to take action and resolve the problem before an alert is issued. However, it provides a mechanism for monitoring the problem and if it persists, generating an alert. The Configure Size tab specifies an automated recovery action when the log file being monitored meets or exceeds a designated size.
99
The Schedule Log tab specifies when and for how long PATROL scans the specified log files. This schedule recurs every 24 hours.
Before you begin

You must have set up a PATROL object to monitor a log file.
To configure log monitoring from PATROL Configuration Manager 1 Add a new PATROL object instance to monitor a log file as described in
Adding/specifying object instances to monitor on page 97 or select a ruleset created to monitor a log file as described in Updating monitored object instances on page 98.
2 Select an instance from the Log Instance List. 3 Select the General tab and specify the log file and the messages for which you want
generate alerts. For descriptions of the process properties used to define the criteria, see Add File for Label: instanceName dialog box on page 34.
4 Select the Configure Log Monitoring Blackout tab and specify under what conditions
alerts can be generated. For descriptions of the process properties used to define the criteria, see Add File for Label: instanceName dialog box on page 34.
5 Select the Configure Size Actions tab and specify a recovery action for PATROL to
perform when a monitored log file attains a certain size. Table 18 describes the process properties used to define the criteria. Table 18
Field Limit Action Run Attended
Configure Size Actions

Description specifies a file size limit that, when exceeded, initiates a recovery action specifies the recovery action to take when the file size limit is exceeded specifies a mode for running the recovery action
File Size Recovery Action
6 Select the Schedule Log Scan tab and determine when and for how long PATROL
must actively monitor this file. Table 19 describes the process properties used to define the criteria. Table 19
Field Start
Schedule Log Scan (Part 1 of 2)

Description Using a 24-hour clock, select the hour, minute, and second at which you want the scan to begin every day.
100
Table 19
Field Duration
Schedule Log Scan (Part 2 of 2)

Description Select how long (in hours, minutes, seconds) you want PATROL to scan the designated logs.
Generate Alert if no Select this option if you want to be notified if none of the Match Found at Scan End contents of the logs match the strings that you provided.
7 Click Apply to save the settings. 8 Click OK.

PATROL Configuration Manager saves your changes and closes the dialog box.
9 Apply the configuration changes.

s
If you are adding a new object instance for monitoring (working in the Agent tree view pane), click Apply to apply the ruleset and begin monitoring. If you are updating an object instance for monitoring, (working in the RuleSet tree view pane) assign the updated rulesets to the desired agent(s), and then click Apply to apply the ruleset and begin monitoring with the new settings.
Chapter 4
Monitoring log files
101
102
Chapter
Defining Recovery Actions

This chapter presents the following topics: Configuring recovery actions for a log file. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103 Responding to recovery actions that require confirmation . . . . . . . . . . . . . . . . . . . . . 105
Configuring recovery actions for a log file

The PATROL KM for Log Management allows you to define recovery actions when a log file reaches a specified size. The available recovery actions for log files are:
s
reduce the log file to 0 MB by deleting all the messages in the log file when the file reaches the size limit back up the file into the pmg_backup subdirectory located in the same directory as the monitored log file and reduce the log file to 0 MB
The backup file is written to the same directory with an incremental number appended to the log file name each time the file is backed up. For example, the first time that the error_log.txt reaches its size limit, PATROL creates a backup file named error_log.txt1. The next time that it reaches its limit, PATROL creates a backup file named error_log.txt2 and so on.
NOTE
It is recommended that you periodically move the backup files to another location. The PATROL recovery action checks to make sure that the backup file name is not already in use. If hundreds or even thousands of backup files exist in the log directory, PATROL may take some time to complete this recovery action.
Chapter 5 Defining Recovery Actions
103
Configuring recovery actions for a log file
Recovery actions run automatically by default; however, they can be configured to require user confirmation if the Run Attended option button is set to Yes. For more information about recovery actions that run in attended mode, see Responding to recovery actions that require confirmation on page 105.
Before You Begin

s
If you are adding a new log file to be monitored, follow the steps in Monitoring files in Unicode format on page 69. If you want to configure a recovery action for an existing log file, follow the steps in Scanning a monitored file from the beginning on page 71. You must be using the PATROL Central Operator - Windows Edition, PATROL Central Operator - Web Edition, or a PATROL Console in Developer mode.
To configure a recovery action for a log file based on file size 1 Access the LOGT application menu as described in Appendix A, Accessing Menu
2 Select Advanced Features => Configure Size Actions. 3 In the Configure Size Actions dialog box, in the Size Limit text box, enter the
number of bytes that the monitored file must exceed before PATROL executes the recovery action. For example, if the limit is 100 bytes, enter 100 in the Size Limit text box.
4 Select one of the following Action options to specify a recovery action for PATROL
to take when the log file reaches the specified size limit:
s
NothingPATROL continues monitoring the log file but does not attempt to reduce its size. DeletePATROL reduces the log file to 0 MB by deleting all the messages in the log file. Backup and Delete PATROL backs up the existing log file and reduces the log
file to 0 MB.
5 Click Yes or No to indicate whether PATROL should run in the Run Attended
recovery action mode (prompt an operator for confirmation before performing a recovery action). For more information about the Run Attended recovery action mode, see Responding to recovery actions that require confirmation.
104
Responding to recovery actions that require confirmation

If you chose to be prompted for a confirmation before PATROL KM for Log Management performs a recovery action, the KM displays the Run Recovery Action dialog box when the LOGFileSize parameter exceeds the size limit that you established. The dialog box asks you to confirm whether the recovery action should be run on the file. Select Yes to run the recovery action or No to prevent the recovery action from running.
Chapter 5 Defining Recovery Actions
105
106
Appendix
Accessing Menu Commands, InfoBoxes, and Online Help

A
BMC Software offers several PATROL consoles from which you can view a PATROL Knowledge Module (KM). Because of the different environments in which these consoles run, each one uses a different method to display and access information in the KM. This appendix provides instructions for accessing the KM menu commands, InfoBoxes, and online Help on each of the PATROL consoles. See the PATROL KM for Log Management online Help for more detailed information about navigation in the PATROL Consoles. Accessing KM Commands and InfoBoxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 108 Accessing online Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
Appendix A
107
Accessing KM Commands and InfoBoxes

Table 20 provides information about how to access KM commands and InfoBoxes from the various PATROL consoles. Table 20
Console PATROL Console for Microsoft Windows Servers

To access menu commands In either the Desktop tree tab or work area, right-click a computer or application icon and choose KM Commands from the pop-up menu. In the work area, right-click a computer or application icon to display a pop-up menu that contains KM-specific commands. To access InfoBoxes In either the Desktop tree tab or the work area, right-click an application class or parameter icon and choose InfoBox from the popup menu. With the middle mouse button, click an application class or parameter icon.
PATROL Central Operator Windows Edition
In the navigation pane, right-click a In the navigation pane, right-click a PATROL object and choose managed system or application InfoBox from the pop-up menu. icon and choose Knowledge Module Commands from the popup menu. In the tree view area, right-click an In the tree view area, right-click a PATROL object and choose application icon and choose Infobox from the pop-up menu. Knowledge Module Commands from the pop-up menu.
108
Accessing online Help

Table 21 provides information about how to access Help from each console.
NOTE
If you are trying to access Help from a UNIX console, see the PATROL Installation Reference Manual for specific instructions about installing and setting up a browser in the UNIX environment.
Table 21
Console

To access product help From the console menu bar, choose Help => Help Topics. In the Help Topics window, double-click PATROL Knowledge Modules. In the submenu, double-click PATROL KM for Log Management . To access application class help If you have a developer connection to the agent, double-click an application class in the KM tab of the console. From the Application Properties dialog box, click the Help tab. Then click Show Help. To access parameter help
s
PATROL Console for Microsoft Windows Servers
Right-click a parameter icon and choose Help On from the pop-up menu. Double-click a parameter icon; click the ? icon or Help button in the parameter display window. Double-click a parameter in the KM tab of the console; from the properties dialog box, click the Help tab and then click Show Help.
Right-click the PATROL KM for Log Management application icon and choose KM Commands => Product Help. From the console menu bar, choose Help On => Knowledge Modules.
Choose Attributes => Application Classes and double-click the application name. Click Show Help in the Application Definition dialog box.
Right-click a parameter icon and click Help On.
Appendix A
109
Table 21
Console

To access product help From the console menu bar, choose Help => Help Topics. In the Contents tab, click the name of your product. To access application class help
s
To access parameter help

s
PATROL Central Operator - Windows Edition
In the Operator tab of the navigation pane, select an application icon and press F1. In the Operator tab of the navigation pane, right-click an application icon and choose Help.
In the Operator tab of the navigation pane, select a parameter icon and press F1. In the Operator tab of the navigation pane, right-click a parameter icon and choose Help.
In the upper right corner of In the tree view, right-click In the tree view, right-click an application class and a parameter and choose PATROL Central, click Help. Help and choose PATROL choose Help. KM Help. In the PATROL Central Web Edition KM Help window, click the name of your product.
110
Appendix
Regular Expressions
This appendix describes how to use regular expressions in the context of the PATROL KM for Log Management.
NOTE
Regular expression characters are not supported for named pipes.
Not all components of the PATROL KM for Log Management support regular expressions. This appendix lists the components that support regular expressions, defines the regular expression character set for PATROL KM for Log Management, and provides some examples. The following sections appear in this appendix. Characters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Conventions for using Regular Expressions with PATROL Objects . . . . . . . . . . . . . Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Examples. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112 113 114 114 114
Appendix B
Regular Expressions
111
Characters
Characters
You can use the following special characters when creating a regular expression.
NOTE
In the PATROL KM for Log Management, the parenthesis ( ) and pipe | characters are paired with a backslash \. This pairing varies from the standard regular expression character set.
Table 22
Character . (period) * (asterisk)
Regular Expression characters

Description matches any single character matches zero or more instances of the previous pattern item matches one or more instances of the previous pattern item matches zero or one instances of the previous pattern item groups a sub-pattern The repetition and alternation operators apply to the whole proceeding subpattern.
+ (plus sign) ? (question mark) \(\ ) (backslash and parenthesis)
\| (backslash and vertical bar or pipe) [ ] (brackets)
provides an alternative This character functions similarly to a logical OR. delimits a set of characters Ranges are specified as [x-y]. If the first character in the set is ^, then there is a match if the remaining characters in the set are not present.
^ (caret)
anchors the pattern to the beginning of the string This character applies only when first.
$ (dollar sign)
anchor the pattern to the end of the string This character applies only when last.
\& (backslash and ampersand)
connects two or more regular expressions as an AND operator. Regular expressions are connected as (x)\&(y), where x and y are valid regular expressions. The backslash and ampersand character is never used as a regular expression; it is always used and functions only as a connector between two or more regular expressions. You can add multiple regular expressions using the \& operator.
112
Examples
Examples
The following examples illustrate how to use regular expressions.
any two-character string

..matches any two characters
upper and lower case

[Ww]arningmatches Warning or warning.
exclusion
[^a-zA-Z]matches anything except uppercase and lowercase letters.
a character followed by zero or more occurrences of a character

st*matches a string that contains an s followed by zero or more ts.
repeated sequences
$st$+matches a string that has one or more sequences of st.
anything
.*matches anything.
word regardless of case

warning\|Warningmatches warning or Warning.
space or tabs that precede a string

^[ \t]+matches any string that begins with spaces or tabs.
Appendix B
Regular Expressions
113
Conventions for using Regular Expressions with PATROL Objects
Conventions for using Regular Expressions with PATROL Objects

In regular expressions, when specifying PATROL objects (/computer:/application/instance/parameter) or path names (/directory/subdirectory/subdirectory/file), remove the initial slash and substitute dashes for the remaining slashes.
Format
For a file, the format for a regular expression is
directory-subdirectory-subdirectory-file
For a PATROL object, such as a parameter, the format for a regular expression is
computer:-application-instance-parameter
EXAMPLE
The file system /app/oracle/usr would be represented as app-oracle-usr in a regular expression.
Examples
The following examples illustrate how to use regular expressions with PATROL objects and path names.
a directory or object
tmpmatches tmp directory
directories or objects with a similar name

usr[1-9].*matches usr1 through usr9
subdirectories
etc-testmatches directory or file system /etc/test 114 BMC PATROL Knowledge Module for Log Management User Guide
Examples
objects with similar names in object hierarchies

nerd:-DISK-sb[0-9].*matches any disk with a prefix of sb0 through sb9 on the computer nerd PRINTER-.*[Hh]ouston.*matches any printer with the word Houston, capitalized or
in all lowercase, in its name
Appendix B
Regular Expressions
115
Examples
116
Appendix
PATROL Agent Configuration Variables

C
This section describes the PATROL KM for Log Management agent configuration variables that are set in the PATROL Agent. To view these variables, use BMC Softwares PATROL Configuration Manager or the Agent Configuration utility (pconfig, wpconfig, xpconfig).
WARNING
Changing any of these variables can prevent some functions from working properly and can affect your entire installation. Before you change a variable, make a record of the original setting.
This appendix presents the following topics: Managing configuration variables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . PATROL KM for Log Management configuration variables . . . . . . . . . . . . . . . . . . . Using the /PMG/CONFIG/instanceName/actPatterns pconfig branch. . . . . . Using the /PMG/CONFIG/instanceName/actSearchList pconfig variable. . . 118 118 131 132
Appendix C
117
Managing configuration variables
Managing configuration variables

BMC Software recommends that you set and view PATROL Agent configuration variables by using the PATROL Agent Configuration utility or the PATROL Configuration Manager. PATROL Configuration Manager is more convenient because it includes an interface that allows you to create and deploy configurations to multiple PATROL Agents from a central location.
WARNING
The PATROL Agent configuration variables created for any log file definition are created as a block of related configuration variables. Existing blocks must be kept intact. Improperly modifying existing blocks may prevent some functions from working properly and can affect your entire installation.
PATROL KM for Log Management configuration variables

Table 23 lists the PATROL KM for Log Management variable settings. All configuration variables are located in /PMG/CONFIG/log_label. The variables that are
marked as Global in the Global/Instance level column are applicable to all the instances of that file type. The variables that are marked as Instance in the Global/Instance level column are applicable only for the current instance.
Table 23
Configuration variables for PATROL KM for Log Management (Part 1 of 13)

Global /Instance level Instance
Variable name actAtomSize actContainEnv
Required? Description n n number of lines in matching log message indicates whether the monitored file contains environment variables (format: %ENV_VAR%) Valid values are: s 0 = no environment variable expansion takes place s 1 = the monitored file name entered is checked for environment variables. Items enclosed in % are expanded in the variable defined at the PATROL Agent start time or replaced with the string MISSING.
Type integer
Boolean Instance
118
Table 23

Variable name actStart
Required? Description n
Type
start time for timed log file scans, based on a integer 24-hour clock Valid values are 0-86399. The value is calculated with the following formula: Hours*3600+Minutes*60+Seconds For example, a value of 0 = a start time of 00:00:01. Note: If you modify a LOG application instance created using version 2.4.20 or earlier of the product that does not have a scheduled log scan, and convert it to the current format of the scheduled log scanning, this variable gets deleted.
actDelInstInMin
integer the time (in minutes) after which an XML instance should be deleted once the closing root-tag is found. duration (in seconds) for timed log file scans, based on a 24-hour clock Valid values are 0-86399. The value is calculated with the following formula: Hours*3600+Minutes*60+Seconds For example, a value of 10800 = a 3-hour scan duration. Note: If you modify a LOG application instance created using version 2.4.20 or earlier of the product that does not have a scheduled log scan, and convert it to the current format of the scheduled log scanning, this variable gets deleted. integer
Instance
actDur
Instance
Appendix C
119
Table 23

Variable name actResetCount
Type
integer Specify the time interval, in seconds, in between two consecutive schedules. After a schedule begins, the next schedule begins after the number of seconds specified in this variable. The default value set for this variable is 86400 seconds (24 hours). Thus, after a schedule begins, the next schedule starts after 24 hours (24*60*60 seconds). Ensure that the value set in the actResetCount variable is greater than the scheduled duration; otherwise the variable is set to the default value of 86400 seconds. Note: If you modify a LOG application instance created using version 2.4.20 or earlier of the product that does not have a scheduled log scan, and convert it to the current format of the scheduled log scanning, this variable gets deleted.
actLabel actName
y y
user-entered label for this monitor instance name of the file name of the log file, FIFO, and so on, to be monitored The file name can include wildcard characters.
text text
Instance Instance
actNoMatch
indicates whether or not match has been found. Valid values are:
s
Boolean Instance
0 = an event is not generated if no matches are found during the timed scan 1 = an event is generated if no matches are found at the end of a timed scan text integer Instance Instance
actNullifyString actFileType
n y
Add a regular expression to nullify the alarm condition.

s
s s s
Specify the type of monitored log file. Valid values are: 1 = text file 2 = command 3 = pipe 4 = binary file
120
Table 23

Variable name actFileFilter
Required? Description n Specify a filter program. This variable is required when the actFileType variable is set to 4 (when the file type is a binary). This filter program must exist and be executable by PATROL Agent user (on UNIX) when the KM reads the configuration instance. Specify the log file read position indicator. Valid values are:
s
Type
actFileBegin
Boolean Instance
0 = each file scan starts from the position where the previous scan ended (previous EOF) 1 = file is scanned from the beginning each time
actFileTreatment
Specify the log file treatment indicator. This Boolean Instance variable is required when the actFileType variable is set to 1 (when the file type is text). Valid values are: s 1 = monitor latest matching file s 2 = monitor all matching files See actName.
actFileSizeExceeds
integer If the pconfig variable /PMG/CONFIG/actFileSizeExceeds contains the value 1, the parameter is set to alarm when the file size of the monitored file exceeds the value specified in the pconfig variable /PMG/CONFIG/actfileSizeThreshold. The threshold file size of the monitored file integer at which the parameter goes into alarm is stored in the pconfig variable /PMG/CONFIG/actfileSizeThreshold. integer If you set the pconfig variable /PMG/CONFIG/actFileTimestampChange to a value of 1, the parameter is set to alarm when the time stamp of the monitored file changes.
Instance
actfileSizeThreshold
Instance
actFileTimestampChange
Instance
Appendix C
121
Table 23

Variable name actFilePermissionChange
Type
integer If the pconfig variable /PMG/CONFIG/actFilePermissionChange contains the value 1, the parameter is set to alarm when the permissions on the monitored file change. Log file monitoring blackout indicator. Valid values are: s 0 = blackout disabled s 1 = blackout enabled
actAlertEvent
Boolean Instance
actAlertEventTime
integer If the log file is not modified in the last specified minutes, an event is generated and the LOGStatus parameter goes into an alarm state. This variable is required when the value of the actAlertEvent variable is set to 1. Specify a custom event message. This variable is specific to the default setting for a search criterion. text
Instance
actAlertEventMessage
Instance
actAlertEventOrigin
Specify a custom event origin. This variable is specific to the default setting for a search criterion.
text
Instance
actStateEventCount1
Specify the number of monitoring matches per scan before the state change. This variable is only checked if match count is less than actStateEventCount2. This variable is specific to the default setting for a search criterion.
integer
Instance
actStateEventCount2
Specify the number of monitoring matches per scan before the state change. This variable is specific to the default setting for a search criterion. See actStateEventCount1.
integer
Instance
122
Table 23

Variable name actStateEvent1
Required? Description y Specify the state associated with actStateEventCount1. Valid values are:
s s s s
Type integer
1 = No Action 2 = OK 3 = Warn 4 = Alarm
The LOGErrorLvl parameter is set to this value when the threshold for a string match is reached. This variable is specific to the default setting for a search criterion. actStateEvent2 n Specify the state associated with actStateEventCount2. Valid values are as follows:
s s s s
integer
Instance
1 = no action 2 = OK 3 = warn 4 = alarm
The LOGErrorLvl parameter is set to this value when the threshold for a string match is reached. This variable is specific to the default setting for a search criterion. actStateReturnOK n Return to OK indicator. Valid values are: s 0 = KM continues to alert until manually reset s 1 = set LOGErrorLvl/value to 1 if no matches in next scan actScanCount actScanAlert n y Blackout timer in minutes Blackout override enable. Valid values are: s 0 = override feature disabled s 1 = override feature enabled Match count per log file scan to override blackout. integer Instance Boolean Instance Boolean Instance
actScanAlertCount
integer
Instance
Appendix C
123
Table 23

Variable name actSizeLimit
Required? Description n Log file size threshold for size recovery actions. Expressed in bytes. Value of 0 disables size recovery action. Size recovery action indicator. Valid values are: s 1 = no recovery action s 2 = clear log file s 3 = backup and clear log file
Type integer
actSizeAction
integer
Instance
actSizeAttend
Size recovery action indicator. Valid values are: s 1 = run unattended s 2= run interactively
Boolean Instance
actPriority
Specify the monitoring priority. Valid values are: s 1 = normal priority s 2 = medium priority s 3 = low priority
integer
Instance
actTouch
Log configuration change indicator. Valid values are: s 0 = no change s 1 = configuration has been modified
Boolean Instance
actLogicalName
If the instance is a static instance and the logical name is provided through the GUI, the logical name is stored in the pconfig variable /PMG/CONFIG/label/actLogicalName. The LOGMON instance name displays the specified logical name.
text
Instance
124
Table 23

Variable name actXmlValidity
Required? Description enables you to control the values for the LOGStatus parameter Valid values are:
s
Type integer
0 = The LOGStatus parameter is set to 7 if any error is found while scanning the XML file 1 = The LOGStatus parameter is set to 7 only if the XML file contains invalid document structure (non-XML); XML syntax errors are ignored 2 = The LOGStatus parameter is never set to 7
A value of 7 for the LOGStatus parameter refers to an invalid XML file. customEvtMatchCount n integer If set to 1, only one event is generated per search criterion independent of the number of matches found. The generated event contains the total number of matches found and the last matched text for the search criterion. The value is stored in /PMG/CONFIG/customEvtMatchCount. enables the KM to read the log file from the integer last read point in the previous scan when the configuration of the monitored log file changes. The value is stored in the pconfig variable /PMG/CONFIG/updateOnConfigChange. Valid values are: s 0 the log file instance is deleted s 1 the log file instance is not deleted The default behavior of the KM is to destroy and re-create the log file instance and read the log file from the beginning whenever the configuration of the monitored log file changes. If the pconfig variable /PMG/CONFIG/updateOnConfigChange has a value of 1, the instance is not destroyed and the KM reads the file from the last read point in the previous scan. Global
updateOnConfigChange
Global
Appendix C
125
Table 23

Global /Instance level Global
Variable name numOldInstances
Type
integer controls the number of old instances to be monitored when the File Disposition option in the Add File for Label: instanceName dialog box is set to Latest. The value is stored in the pconfig variable /PMG/CONFIG/numOldInstances. The default value for numOldInstances is 1. Specifying a null string for the Number of Old Instances causes the KM to delete this variable and revert to the default of 1. If the File Disposition option in the Add File for Label: instanceName dialog box is set to All, the KM ignores the numOldInstances variable.
actSchedlList actDurAsEndTime
y n
enables you to hold the scheduled list while text scheduling file scanning enables you to set the specified duration to be considered as the End time while scheduling file monitoring
Instance
Boolean Instance
suspendAll
suspends all the instances configured under Boolean Global PATROL KM for Log Management Valid values are: s 0 removes suspension from all the instances s 1 suspends all the instances If you set the /PMG/CONFIG/suspendAll variable to a value of 1, it skips text added during the suspension period. After the period lapses, the KM reads from the end of the file. When using the KM interface, the suspendAll variable and the PMGSuspend flag file take precedence over the Suspend KM event generation for a specified time period option.
126
Table 23

Global /Instance level
Variable name originNameInEM
Type
controls the format of the origin name in the Boolean Global Event Manager. PNn is a suffix used with the LOGMON instance. (For example, if the name of a LOGMON instance is Test, you see TestPN0 and TestPN1 in the Event Manager.) Valid values are: s 0 = uses naming convention with PNn s 1 = uses naming convention without PNn; instead of PNn, the file name is added
fileSizeGrowthLimit
holds the value of the file size growth limit integer in kilobytes. If the KM determines that the difference between the old file size and the new file size is greater than the value in the fileSizeGrowthLimit variable, it does not perform scanning. This feature is applicable only for text files. You can add the /PMG/CONFIG/fileSizeGrowthLimit variable to stop scanning of text files when scalability limits have been reached. Set the value of the variable by using X to indicate the growth limit in kilobytes. The pconfig variable is added globally and is applicable to all the LOGMON instances. If the file size growth is more than the value of the fileSizeGrowthLimit variable, the following actions occur: s scanning is not done for this file during the polling cycle s data added during the polling cycle is skipped from scanning s the LogStatus parameter goes into an alarm and is set with a value of 6 s the offset is set to the end of the file for the next polling cycle
Global
Appendix C
127
Table 23

Global /Instance level Global
Variable name fileScanTimeLimit
Required? Description n limits the amount of time that the KM spends scanning files You need to manually add the /PMG/CONFIG/fileScanTimeLimit variable. You can set its value as 1 to limit the amount of time that the KM spends scanning files. This is a global variable so the time limit set in this variable is split between all of the LOGMON instances. The time allocated for each LOGMON instance is fileScanTimeLimit divided by the total number of LOGMON instances. If the variable is set to a value other than 1, the KM does not limit the time it takes to scan files. If the fileScanTimeLimit variable is set to 1, the total scan time limit is 2 minutes. The KM derives this from the default polling cycle, which is 2 minutes. Therefore, if the total number of LOGMON instances is 4, each instance has a scan time limit of 30 seconds. This polling time is added after the polling cycle starts at 2 minutes. Thus, the maximum time for data collection is 4 minutes. If the fileScanTimeLimit variable is set to anything other than 1, the KM works normally. If the KM is monitoring a large file, and fileScanTimeLimit is set to 1, the KM continues scanning in multiple polling cycles, and the LogStatus parameter is set to a value of 2. If the KM is monitoring a normal size file and completes scanning within the limit, the LogStatus parameter is set to a value of 1.
Type integer
128
Table 23

Global /Instance level
Variable name actIgnoreCase
Required? Description n enables you to make pattern searches that are not case sensitive. To enable this variable, you must add the /PMG/CONFIG/actIgnoreCase variable to the pconfig file and set a value of 1. Valid values are: s 1 = ignore case s 0 or anything other than 1 = casesensitivity is enforced This variable is global and applicable to all the LOGMON instances.
Type
Boolean Global
actMaxRecordSize
enables you to limit or expand the amount of kilobytes of data between the start delimiter and the end delimiter This variable has a default value of 8096. If the KM does not find an end delimiter before 8096 or before it reads 8k of data, it ignores the start delimiter and looks for another start delimiter.
integer
Instance
actMaxReturnedRecordSize n
integer limits the amount of text from the log file that you specify in an event for multiline record. By default, its value is 8096 i.e. 8kb. The value of the actMaxReturnedRecordSize variable should always be less than actMaxRecordSize. determines the position of the file scan when you restart the PATROL Agent. You must add this pconfig variable manually. If you do not define the value of the /PMG/CONFIG/logmonInstance/actInitia lReadEOF pconfig variable, the default value is 0, and the KM scans the file from the offset. Valid values are: s 0 = log file reads from the last offset s 1 = log file reads from the end of the file s 2 = log file reads from the beginning of the file integer
Instance
actInitialReadEOF
Instance
Appendix C
129
Table 23

Variable name searchIdentifierLabel
Required? Description y
Type
Describes the label for a search criterion that text you define. Each time you define a search criterion, this variable is created with the same name as that of the search identifier. This variable is a collection of fields and is created under the /PMG/CONFIG/instanceName/actPatter ns pconfig branch. For more information, see Using the /PMG/CONFIG/instanceName/actPatter ns pconfig branch
actSearchList
stores the entire configuration information of an XML instance For more information, see Using the /PMG/CONFIG/instanceName/actSearch List pconfig variable on page 132.
text
Instance
InstOnFileNotExist
allows an instance to get created on file that Boolean Global does not exist You must add the /PMG/CONFIG/InstOnFileNotExist manually, and set it to a value of 1.
suppressSpaceInMsg
Enables you to suppress multiple consecutive spaces in a custom event message. You need to add this variable manually under the /PMG/CONFIG branch. You can assign one of the following values:
s
Boolean Global
1 = Suppresses multiple consecutive spaces and considers them as a single delimiter 0 (default) = Does not suppress multiple consecutive spaces and considers them as multiple delimiters
130
Using the /PMG/CONFIG/instanceName/actPatterns pconfig branch
Using the /PMG/CONFIG/instanceName/actPatterns pconfig branch

The /PMG/CONFIG/instanceName/actPatterns pconfig branch enables you to define multiple search criteria for a text instance. Each search criterion has a unique identifier (key) and collection of fields (value). The key-value pair represents a search criterion. Each field in a search criterion is separated by the <Ctrl+B> character, as follows: Not<Ctrl+B>string1<Ctrl+B>Not<Ctrl+B>string2<Ctrl+B>threshold# 1<Ctrl+B>state1 <Ctrl+B>threshold# 2<Ctrl+B>state2<Ctrl+B>overrideDefSetting<Ctrl+B> customEventOrigin<Ctrl+B>customEventMsg<Ctrl+B>numRegEx<Ctrl+B> IgnoreDuplicateEventsForMinutes<Ctrl+B>pollingIntrvl In the preceding format, numRegEx refers to a collection of fields that are separated by commas. The fields include:
s s s s s s
firstNum Op1 BeginToken EndToken Op2 SecondNum
Appendix C
131
Using the /PMG/CONFIG/instanceName/actSearchList pconfig variable
For example, you configure search criterion for a text instance through the GUI having the following settings:
s s s s s s
s s s s s s s s
String1 (string1): ERROR\|INFO\|SEVERE String2 (string2): Server.*, Not is selected for String2 Threshold# 1 (threshold# 1): 2 and the corresponding state is WARN Threshold# 2 (threshold# 2): 6 and the corresponding state is ALARM Custom Event Message (customEventMsg): This is a custom event %1-. Custom Event Origin (customEventOrigin): %APPCLASS%.%INSTANCE%.%SEARCHID% First Number (firstNum): 15 Op1 (Op1): >= Begin token (BeginToken): 1 End token (EndToken): 3 Op2 (Op2): > Second Number (SecondNum): 10 Ignore Duplicate Events For Minutes (IgnoreDuplicateEventsForMinutes): 5 Polling Interval (Generate ALARM when pattern not found within polling intervals) (pollingIntrvl): 2
You can configure the preceding search criterion for the text instance by using the following pconfig variable format: 0<Ctrl+B>ERROR\|INFO\|SEVERE<Ctrl+B>1<Ctrl+B>Server.*<Ctrl+B>2<Ctrl+B >3<Ctrl+B>6<Ctrl+B>4<Ctrl+B>1<Ctrl+B>%APPCLASS%.%INSTANCE%.%SEARC HID%<Ctrl+B> This is a custom event %1-<Ctrl+B>15,4,1,3,1,10<Ctrl+B>5<Ctrl+B>2 Using the preceding pconfig variable format, the lines that contain the regular expression, ERROR\|INFO\|SEVERE, and that do not contain the regular expression, Server.*, are matched only if the lines contain a number that is greater than 10 and less than 15 between first and third columns (including both first and third). If the number of matches found is between 2 and 5, WARNING events are generated. If the number of matches is 6 or more, ALARM events are generated. Generated custom events contain the custom event message.

The /PMG/CONFIG/actSearchList pconfig variable stores the configuration information of an XML instance. The configuration information is stored in the form of key-value pairs.
Each field in the variable is separated by the <Ctrl+B> character, as follows: searchId<Ctrl+B>string1<Ctrl+B>threshold# 1<Ctrl+B>state# 1<Ctrl+B>threshold# 2 <Ctrl+B>state# 2<Ctrl+B>customEventMsg<Ctrl+B>IgnoreDuplicateEventsForMinutes <Ctrl+B>overrideDefSetting<Ctrl+B>customEventOrigin<Ctrl+B>pollingIntrvl<Ctrl+B> If an XML instance is configured for multiple search criteria, the preceding format is separated by the <Ctrl+B> character from the next search identifier. For example, an XML instance is configured using the following settings:
s s s s s s s
Search Identifier (searchId): S1 XML Search String1 (string1): <Node1>Error</Node1> Threshold# 1 (threshold# 1): 3 and the corresponding state is WARN Threshold# 2 (threshold# 2): 5 and the corresponding state is ALARM Ignore Duplicate Eevents (IgnoreDuplicateEventsForMinutes): 20 Custom Event Message (customEventMsg): This is a custom event %2-. Custom Event Origin (customEventOrigin): %APPCLASS%.%INSTANCE%.%SEARCHID% Polling Interval (Generate ALARM when pattern not found within polling intervals) (pollingIntrvl): 2
For the preceding settings, the actSearchList variable will store the following value: S1<Ctrl+B><Node1>Error</Node1><Ctrl+B>3<Ctrl+B>3<Ctrl+B>5<Ctrl+B>4<Ctrl +B>This is a custom event %2<Ctrl+B>20<Ctrl+B>0<Ctrl+B> %APPCLASS%.%INSTANCE%.%SEARCHID%<Ctrl+B>2<Ctrl+B> Using the preceding variable format, the Node1 elements containing Error are searched. If the number of matches found is between 3 and 4, WARNING events are generated. If the number of matches is 5 or more, ALARM events are generated. Generated custom events contain the custom event message. Duplicate events are ignored for 20 minutes.
Appendix C
133
134
Appendix
Migrating Data to Version 2.x

This appendix describes how to migrate your PATROL KM for Log Management version 1.x and LogSpring data the latest version of the KM by using the PMGCONVERT.km application class. Migrating data from the PATROL KM for Log Management version 1.x. . . . . . . . . 136 Migrating data from LogSpring. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
Appendix D
135
Migrating data from the PATROL KM for Log Management version 1.x
Migrating data from the PATROL KM for Log Management version 1.x
The PATROL KM for Log Management version 2.x no longer supports search string templates. If you created search string template in the PATROL KM for Log Management version 1.x, you need to update them into PATROL KM for Log Management version 2.x format using the menu command for the PMGCONVERT.km application class.
NOTE
PMGCONVERT.km does not migrate custom event messages.
Before you begin

The PMGCONVERT.km application class is not loaded when you load the LOG.kml file, so you must load PMGCONVERT.km separately.
NOTE
In the Load KMs dialog box, be sure to select All Files in the File Type filter so that you will be able to see the PMGCONVERT.km file.
When PMGCONVERT.km is loaded, a LOG_Convert instance is created under the managed system icon, not under the LOG application class.
To convert search string templates to 2.x format: 1 Access the LOG_Convert application menu as described in Appendix A,
2 Choose Convert 1.0 to 2.0 definition.

Search strings defined in version 1.x of the KM are updated to 2.x format.
136
Migrating data from LogSpring

If you have been using LogSpring, you can use the PMGCONVERT.km to migrate your LogSpring definitions into the PATROL KM for Log Management version 2.x.
Before you begin

The PMGCONVERT.km application class is not loaded when you load the LOG.kml file, so you must load PMGCONVERT.km separately.
NOTE
In the Load KMs dialog box, be sure to select All Files in the File Type filter so that you will be able to see the PMGCONVERT.km file.
When PMGCONVERT.km is loaded, a LOG_Convert instance is created under the managed system icon, not under the LOG application class.
To migrate LogSpring data into the PATROL KM for Log Management version 2.x: 1 Access the LOG_Convert application menu as described in Appendix A,
2 Choose LogSpring Convert.

Your existing LogSpring definitions are migrated into the PATROL KM for Log Management version 2.x.
Appendix D
137
138
Chapter
E
140 140 140 141 141 142 142 143 144
Troubleshooting
This chapter presents the following topics: Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Loading the PMGDEBUG application class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Enabling and disabling PATROL KM for Log Management debugging . . . . . . Enabling and disabling log file, script, and binary file debugging . . . . . . . . . . . Enabling named pipe debugging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . General information to gather before calling BMC Software Support. . . . . . . . . . . . Diagnostic questions to answer. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Information to capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Information to gather if the problem is related to memory and CPU utilization. . .
Chapter E
Troubleshooting
139
Troubleshooting
Troubleshooting
This chapter explains how to gather information that can be used by BMC Software Support when helping you to troubleshoot problems with the PATROL KM for Log Management.
Loading the PMGDEBUG application class

The PMGDEBUG application class (PMGDEBUG.km) is used by BMC Software Support to diagnose problems and issues with PATROL KM for Log Management. The PMGDEBUG.km application class is not loaded when you load the LOG.kml file, so you must load PMGDEBUG.km separately.
NOTE
In the Load KMs dialog box, be sure to select All Files in the File Type filter so that you will be able to see the PMGDEBUG.km file.
When PMGDEBUG.km is loaded, a PMGDEBUG instance is created under the managed system icon, not under the LOG application class.
Enabling and disabling PATROL KM for Log Management debugging

To diagnose issues with the PATROL KM for Log Management, a BMC Software Support representative might ask you to enabling debugging for the KM. This allows you to display debugging information for the PATROL KM for Log Management that would normally be deleted. When debugging for the PATROL KM for Log Management is enabled, the debugging information for the KM is displayed in the system output window.
To enable or disable Log KM debugging 1 Access the PMGDEBUG application menu as described in Appendix A, Accessing
Menu Commands, InfoBoxes, and Online Help.
2 On the Debug Configuration dialog box, to enable debugging, select the Enable KM
Debug check box. To disable debugging, clear the Enable KM Debug check box.
140
Enabling and disabling log file, script, and binary file debugging
3 Click Apply.
In about fifteen minutes (two or three polling cycles) the diagnostic output is displayed in the system output window.
Enabling and disabling log file, script, and binary file debugging
BMC Software Support representatives might also require diagnostics relating to log files, scripts, and binary files with readers when helping you to debug problems with the PATROL KM for Log Management.
To enable or disable log, script, and binary file diagnostics 1 Access the PMGDEBUG application menu as described in Appendix A, Accessing
Menu Commands, InfoBoxes, and Online Help.
2 On the Debug Configuration dialog box, to enable debugging, select the Enable
Reader Debug check box. To disable debugging, clear the Enable Reader Debug
check box.
3 Click Apply.
The diagnostic output is written to the monitored system in the following location:
s s
on UNIX: $PATROL_HOME/../pmg/port_int/readerLog.txt on Windows: %PATROL_HOME%\port_int\readerLog.txt
where port is the port used by the agent and int is an integer (1, 2, or 3) that corresponds to the three LOGMainColl collector parameters.
Enabling named pipe debugging

BMC Software Support representatives might also require diagnostics relating to diagnostics relating to named pipes when helping you to debug problems with the PATROL KM for Log Management.
Chapter E
Troubleshooting
141
General information to gather before calling BMC Software Support
To enable or disable named pipe diagnostics 1 Access the PMGDEBUG application menu as described in Appendix A, Accessing
Menu Commands, InfoBoxes, and Online Help. is displayed.
2 On the Debug Configuration dialog box, to enable debugging, select the Enable
Pipe Reader Debug check box. To disable debugging, clear the Enable Pipe Reader Debug check box.
3 Click Apply.
The diagnostic output is written to the monitored system in the following location:
s s
on UNIX: $PATROL_HOME/../pmg/port_int/readerLog.txt on Windows: %PATROL_HOME%\port_int\readerLog.txt
where port is the port used by the agent and int is an integer (1, 2, or 3) that corresponds to the three LOGMainColl collector parameters.
General information to gather before calling BMC Software Support

If you are not able to solve your problem using one of the troubleshooting methods documented in this book, you may need to call BMC Support for assistance. Before calling BMC Support, answer the following questions and collect the information specified in the following sections.
Diagnostic questions to answer

Before calling BMC Support, be prepared to answer the following questions: 1. What is the version of PATROL KM for Log Management that you are using? 2. Describe the problem you are having. Is the problem consistent or intermittent?
142
Information to capture
3. What method was used to specify the files to be monitored? For example: A. Did you specify the logs to be monitored using the PATROL KM for Log Management interface as documented in Configuring the PATROL KM for Log Management on page 32? B. Have you attempted to generate a set of rules to apply using the PATROL Configuration Manager or pconfig? If so, capture the rule set that is being applied. C. Were the definitions created manually by copying the log file definitions from another Agent that were defined using the using the PATROL KM for Log Management interface? D. Were the log file definitions migrated using PMGCONVERT.km? 4. At what point did you start having these problems? For example, has the problem been happening since you first installed the KM or has it just started happening? If the problem just started happening, is it based on a new or modified configuration?
Information to capture
Before calling BMC Support, capture the following information.
s
PATROL Agent configuration settings (for instructions see Capturing PATROL Agent configuration settings on page 144) error log for the PATROL Agent host UNIX: $PATROL_HOME/log/PatrolAgent-<host>-<port>.errs Windows: %PATROL_HOME%\log\PatrolAgent-<host>-<port>.errs
(UNIX only) output of uname -a command PATROL KM for Log Management diagnostics from PMGDEBUG.km (for instructions, see Troubleshooting on page 140)
Chapter E
Troubleshooting
143
Information to gather if the problem is related to memory and CPU utilization
From the PATROL Agent System Output Window, capture the output for the following:
%DUMP KM_LIST %DUMP CHANNELS %PSLPS %PSL print(get(/LOGT/instances)) %PSL print(get(/LOGMON/instances))
Capturing PATROL Agent configuration settings

Before calling BMC Support, capture your PATROL Agent configuration settings by following these steps:
1 Log in to the computer hosting the PATROL Agent. 2 Access the top-level (Patrol3) directory of the PATROL installation. 3 (UNIX only) Source the PATROL setup script by entering: . ./patrolrc.sh 4 Enter pconfig +get -p agent_port and redirect the output to a file. NOTE
You can also collect this information by using the pconfig utility menus to save the configuration. You can also use the PATROL Configuration Manager to save the configuration rulesets.

If the problem you are experiencing is related to memory growth or utilization or CPU utilization, in addition to answering the questions and gathering the information as specified in General information to gather before calling BMC Software Support on page 142, be prepared to answer the following additional questions before calling BMC Support. 1. How long have you been running this version of the PATROL KM for Log Management? 2. Is the problem demonstrated on one of the pmgreader processes or is it happening on all of the pmgreader processes?
144
3. Has this problem happened since you first installed/upgraded the PKM for Log Management? Did the problem start happening immediately after the installation/upgrade or did it start happening after configuring one or more log files for monitoring? 4. Is the problem happening on all of your computers or is it limited to one or a few computers? If the problem is occurring only on only certain computers, is there anything about those computers that are different from other computers on which the problem does not occur? For example, is one or more of the log files that are being monitored extremely large or does it have a large rate of change? Are you monitoring a larger number of log files on the computers on which the problem is occurring? 5. When is the memory/CPU increasing? Every scan? Whenever a log is written to? Whenever a log is rolling over? 6. Does memory usage jump immediately and remain steady or does memory grow over time? If the memory grows steadily over time, does it reach a certain level and then hold at that level? 7. Does restarting the PATROL Agent have any effect on the problem? For example, if you stop the PATROL Agent, ensure that all the pmgreader processes are stopped, then restart the PATROL Agent, does the high pmgreader memory usage resume? 8. What is the actual CPU/Memory being used?
s
Windows: use the Task Manager UNIX: use the appropriate PS command for your platform
Oracle Solaris: /usr/ucb/ps auxwww RS6000: /bin/ps auxww HP-UX: UNIX95=TRUE; export UNIX95; ps -elf -o
uid,pid,ppid,stime,tty,time,pcpu,vsz,sz,args
Linux: ps auxww Tru64: ps -e -o pid,ppid,user,time,pcpu,pmem,vsz,rss,args Other: ps elf
Chapter E
Troubleshooting
145
146
A B C D E F G H I J K L M N O P Q R S T U V W X Y Z
Index
A
Add File for Label dialog box field descriptions 35 overview 34 age monitoring for files 80 Agent Error log monitored by default 32 stop and start monitoring 69 Agent Error log monitoring (example) 78 alarm generating and nullifying based on dual-search strings 88 alerts based on file age 80 based on file permissions 82 based on file size 81 based on file time stamp 82 based on the number of matches 83 generating after a specified number of strings 89 anti-virus update file monitoring 55 application class description 18 hierarchy 16 icons 18 LOG description 18 LOGMON description 18 LOGT description 18 PMGConvert description 18 PMGDEBUG description 18 application classes icons 18 application menu LOG 21 LOGMON 23 LOGT 22 PMGCONVERT 24 PMGDEBUG 23 attended mode responding to 105
C
capturing, information for support 143 Change File for Label dialog box overview 38 configuration variables warning 117 configure log monitoring PATROL Configuration Manager 100 configuring PATROL KM for Log Management 32 PATROL KM for Log Management with the PATROL Configuration Manager 97 recovery actions 103 configuring a search criterion text file 50, 60 XML file 59 creating customized flag file 92 criteria monitoring for multiple search criteria 77 custom event messages 85 customer support 2 customizing event messages 67 customizing event origin 48 customizing events built-in macros 67 elements 68 string literals 68
D
debugging enabling and disabling for named pipes 141 enabling and disabling for scripts and binaries 141 enabling and disabling for the KM 140 default flag file 91 default monitored file Agent Error log 32 stop and start monitoring 69 Defining a search string text file 73 XML file 75 defining limits searching a block of lines with a match string 94 defining recovery actions 103 deleting a log instance 70
B
binary files enabling debugging for 141 blackout creation for event generation 91 BMC Software Support, gathering information for 142 BMC Software, contacting 2
Index
147
diagnostic questions for troubleshooting 142 dialog boxes Add File for Label overview 34 Change File for Label overview 38 disabling debugging for named pipes 141 for scripts and binaries 141 for the KM 140 documentation for online Help 19 dynamic file names, monitoring 47, 58
H
Help accessing 19 online 19 hierarchy of application class 16
I
icons for application classes 18
E
enabling debugging for named pipes 141 for scripts and binaries 141 for the KM 140 event message example 87 event messages customization 85 event origin example 88 examples creating a custom event message 87 creating a custom event origin 88 monitoring anti-virus update file 55 monitoring for zero-byte files 53 monitoring the PATROL Agent Error log 78 searching for print queue length 74, 76
K
KM configuration variables 117 configuring 32
L
LOG application class description 18 menu 21 parameters 26 Log files monitored by default 69 log monitored by default 32 LOGErrorLvl description 26 not set if search string is not defined 52, 61 LOGFilePermissionStatus description 27 details 28 LOGFileSize description 26 details 28 LOGFileSizeStatus description 26 details 28 LOGFileTimestampStatus description 26 details 28 LOGGrowthRate description 27 details 28 LOGMailColl description 26 LOGMainColl details 28 LOGMainCollP2 description 26 details 28 LOGMainCollP3 description 26 details 28 LOGMatchString
F
features overview 13 file age monitoring 80 file permissions monitoring 82 file size monitoring 103 file time stamp monitoring 82 files monitoring for a particular string 72 scheduling monitoring 93 stop monitoring 70 types monitored by the KM 32 flag file default 91 moving or renaming 92
G
generating alerts based on number of found strings 89 custom event messages 85 generating alerts based on file age 80 based on file permissions 82 based on file size 81 based on file time stamp 82 based on the number of matches 83
148
description 27 details 28 LOGMON application class description 18 menu 23 parameters 26 LOGMONRecoveryColl description 27 details 28 LOGSearchString description 27 details 29 LOGStatus description 27 details 29 LOGT application class description 18 menu 22 parameters 27 deleting 99 updating 98 monitoring over a period of polling cycles 83 moving the flag file 92 multiline searching 95 multiple criteria monitoring for 77 multiple log file definitions 78 multiple strings using multiple log file definitions 78
N
named pipes enabling debugging for 141 notification when a string has been matched 90 numeric comparison example 74, 76
M
memory growth troubleshooting 144 menu LOG application class 21 LOGMON application class 23 LOGT application class 22 PMGCONVERT application class 24 PMGDEBUG application class 23 message example 87 monitoring anti-virus update file 55 delete log instance 70 file age 80 file permissions 82 file size 81 file time stamp 82 files in unicode format 69 files with dynamic names 47, 58 for a particular string 72 for file size 103 for zero-byte files 53 scanning the file from the beginning 71 scheduling 93 stopping 70 XML log instance 57 monitoring a text instance configuring a search criterion 50, 60 monitoring an XML instance configuring a search criterion 59 monitoring default log file starting and stopping 69 monitoring files in unicode format limitations 70 monitoring object instances adding 97
O
online Help 19 origin example 88 overview features 13 overview of Add and Change Log dialog boxes 33
P
PAgentLog_Alarm setting up the definition 79 parameters default settings 28 LOG application class 26 LOGMON application class 26 LOGT application class 27 PATROL Agent Error log monitoring (example) 78 PATROL Configuration Manager using to configure the PATROL KM for Log Management 97 PATROL KM for Event Management using with PATROL KM for Log Management 90 PATROL KM for Log Management configuring with PATROL Configuration Manager 97 using with PATROL KM for Event Management 90 permissions monitoring for files 82 pipes enabling debugging for 141 PMGCONVERT application class menu 24 PMGConvert application class description 18 PMGDEBUG application class description 18 menu 23 PMGSuspend flag file 91 print queue length search 74, 76
Index
149
product support 2 programmatically stopping event generation 91
T
technical support 2 temporarily stopping event generation 91 time stamp monitoring for files 82 troubleshooting CPU utilization 144 diagnostic questions 142 gathering information before calling support 142 information to capture before calling support 143 memory growth 144
Q
questions for diagnosis 142
R
recovery actions responding to 105 regular expressions using in search strings 77 using to monitor dynamic file names 47, 58 renaming the flag file 92 responding to recovery action dialog 105 retaining log file instances log instances during configuration changes 96 old log instances 95 rules specifying XML search strings 63 rulesets for send notification 90
W
warning Agent configuration variables 117 configuration variables 117
X
XML log file monitoring 57 XML monitoring how it works 57 working 57 XML search strings rules 63
S
scheduling file monitoring 93 scripts enabling debugging for 141 search string 52, 61 searching for print queue length 74, 76 searching a block of lines defining limits 94 searching and monitoring XML files 56 sending an email when an event is found 90 size monitoring for files 103 size monitoring for files 81 start monitoring default log file 69 stop monitoring default log file 69 stop monitoring files 70 stopping event generation temporarily 91 strings monitoring for 72 sending notification when found 90 specifying a number before alerting 89 using regular expressions in 77 support information gathering 142 support, capturing information for 143 support, customer 2
Z
zero-byte files monitoring 53
150
Notes
*623571* *623571* *623571* *623571*
*175326*

Patrol LogMgmt

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Patrol LogMgmt

Diunggah oleh

Hak Cipta:

Format Tersedia

BMC PATROL Knowledge Module for Log Management User Guide

Contacting BMC Software

United States and Canada

Outside United States and Canada

Restricted rights legend

Support by telephone or e-mail

Before contacting BMC

License key and password information

BMC PATROL Knowledge Module for Log Management User Guide

Parameter summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Parameter defaults . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Chapter 4 Monitoring log files 31

BMC PATROL Knowledge Module for Log Management User Guide

BMC PATROL Knowledge Module for Log Management User Guide

BMC PATROL Knowledge Module for Log Management User Guide

BMC PATROL Knowledge Module for Log Management User Guide

BMC PATROL KM for Log Management features and functionality

Chapter 1 BMC PATROL KM for Log Management features and functionality

BMC PATROL Knowledge Module for Log Management User Guide

Chapter 1 BMC PATROL KM for Log Management features and functionality

Application class hierarchy

Application class hierarchy

BMC PATROL Knowledge Module for Log Management User Guide

Application class hierarchy

PATROL KM for Log Management application class hierarchy

Chapter 1 BMC PATROL KM for Log Management features and functionality

Applications and icons

Applications and icons

BMC PATROL Knowledge Module for Log Management User Guide

Accessing online Help (Part 1 of 2)

PATROL Console for Microsoft Windows Servers

PATROL Console for UNIX

Right-click a parameter icon and click Help On.

Chapter 1 BMC PATROL KM for Log Management features and functionality

Accessing online Help (Part 2 of 2)

PATROL Central Operator - Windows Edition

PATROL Central Operator - Web Edition

BMC PATROL Knowledge Module for Log Management User Guide

Menu commands summary

LOG application menu

Chapter 2 Menu commands summary

LOGT application menu

LOG menu summary (Part 2 of 2) Action

LOGT application menu

Advanced Features in the LOGT application menu

Configure Size Action Schedule Log Scan

BMC PATROL Knowledge Module for Log Management User Guide

LOGMON application menu

LOGT submenu summary (Part 2 of 2) Action

LOGMON application menu

PMGDEBUG application menu

Chapter 2 Menu commands summary

PMGCONVERT application menu

PMGDEBUG menu summary (Part 2 of 2) Action

PMGCONVERT application menu

BMC PATROL Knowledge Module for Log Management User Guide

PATROL KM for Log Management parameter summary (Part 1 of 2) Description

LOGMON Application Class LOGErrorLvl

BMC PATROL Knowledge Module for Log Management User Guide

PATROL KM for Log Management parameter summary (Part 2 of 2) Description

Column heading Information included under column heading

PATROL KM for Log Management parameter defaults (Part 1 of 2) Scheduling

consumer consumer consumer

2=WARN und. 1=ALARM 1=ALARM 1=ALARM und. NA NA NA NA NA

3=ALARM und. NA NA NA und. NA. NA NA NA NA