Important

   

This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 22.1 for BMC Helix Operations Management. Open link

dump_events utility

Use the dump_events command line utility to extract events from the PEM log, convert them into ASCII format, and write them to a text file.

Note

The dump_events utility does not access the PEM cache and thus does not extract the most recent events.

Every dumped event displays the following information by default:

  • Event ID
  • Status
  • Type
  • Date/time
  • Node
  • Origin
  • Event description
  • Event diary

The following example is an extract of PEM.txt:

Example

15 OPEN STATE_CHANGE Wed Mar 30 09:39:41 1994 palmtree CPU.CPU State Change:OK ALARM Current state is inherited from an alert on global parameter 'CPUCpuUtil'.
16 OPEN STATE_CHANGE Wed Mar 30 09:39:41 1994 palmtree SYSTEM.SYSTEM State Change:OK ALARM Current state is inherited from an alert on global parameter 'SYSCpuUtil'.
17 OPEN STATE_CHANGE Wed Mar 30 09:39:41 1994 palmtree NETWORK.NETWORK State Change:OK warn Current state is inherited from an alert on global parameter 'NETSGetAttr'.
18 OPEN STATE_CHANGE Wed Mar 30 09:39:42 1994 palmtree FILESYSTEM.patrol-doubloon State Change:OK ALARM Current state is inherited from an alert on global parameter 'FSCapacity'.


When you use dump_events, keep  in mind the following limitations and guidelines:

  • Only one copy of dump_events is allowed to be run at a time on a single system. Otherwise the behavior is unpredictable.
  • dump_events must run on the same host as the PATROL Agent because both use the same lock file (circular-file-name.lock ) in the /$<PATROL_HOME>/log directory for UNIX and PEM_<hostname>_<port>.log <PATROL_HOME>\log directory for Windows.
  • dump_events is installed with the agent; the PATROL environment must be set up prior to running it.

The following table shows the directories used by the dump_events utility:

The dump_events utility directory structure 

OSDirectoryDescription
UNIXPATROL_HOME/logThe default location of the lock file, which must be non-NFS mounted.
WindowsPATROL_HOME\log
UNIXHOME/patrolThe default location of the ASCII file PEM.txt.
WindowsHOMEDRIVE\HOMEPATH\patrol

Before you run the dump_events utility

The PATROL environment must be set up prior to running dump_events. You must set the PATROL_HOME environment variable. The following table describes how to define this variable for UNIX and Windows: 

 PATROL_HOME environment variable

Environment variableFor UNIX, run...
For Windows 2000 or later, select...
PATROL_HOME../patrolrc.sh (for Korn and Bourne shell) 

source .patrolrc (for C shell)
Start > Settings > Control Panel > System > Environment; type the variable name (PATROL_HOME), the value (the path), then click Set.
Start > Settings > Control Panel > System > Advance, and click Environment Variables. Click New and type the variable name (PATROL_HOME), the value (the path), then, click OK.

Running the dump_events utility

To run dump_events, type the following command at the command line prompt and press Enter:

dump_events -<options>

Syntax of the dump_events utility

The dump_events utility has the following format:

dump_events

[-s <circular-file-full-name>]
[-d <ASCII-file-full-name>]
[-t <lock-file-dir-name>]
[-m] <printf-fmt-string>
[-f]
[-v]

Options for the dump_events utility

The following table lists and defines the options for the dump_events command line utility:


Options for the dump_events command-line utility

Option

Definition

-s

This option provides the full name of the event log file (circular file) if different than the default.

The default is PATROL_HOME/log/PEM_<host>_3181.log for UNIX and PATROL_HOME\log\PEM_<host>_3181.log for Windows. If you do not provide a directory, the default directory is used.

-d

This option provides the full name of the ASCII dump file if different than the default. The default is HOME/patrol/PEM_<host>_3181.txt. If you do not provide a directory, the default directory is used.

-t

This option provides the directory name of the circular file lock. The default is PATROL_HOME/log for UNIX and PATROL_HOME\log for Windows. If you do not provide a directory, the default directory is used.

-f

This option enables the event-dumping and can be used if a previous dump_events program was stopped.

-m

This option provides a user-defined format for event dump. By default, the event manager uses the print format string equivalent to '%1$s %2$s %3$s %4$s %5$s %6$s %7$s %8$s\n'.

The arguments have the following order:

  1. Event ID (%1$s)
  2. Status (%2$s)
  3. Type (%3$s)
  4. Time (%4$s)
  5. Node (%5$s)
  6. Origin (%6$s)
  7. Desc (%7$s)
  8. Diary (%8$s)


The following escape sequence is recognized in the printf-fmt-string:

  • \n new line
  • \v vertical tab
  • \t tab
  • \r carriage return

-v

Displays version information.

Examples of the dump_events utility

dump_events -m '%8$s %7$s %6$s %5$s %4$s %4$s %3$s %2$s %1$s\n' 

Note the single quotes around the string format. This command dumps event fields in reverse order to the default, as follows:

  1. Diary
  2. Description
  3. Origin
  4. Node
  5. Time
  6. Type
  7. Status
  8. Event ID

dump_events -m '\t%s \t%s \t%s \t%s \t%s \t%s \t%s \t%s\n\n\n' 

This command dumps fields in the default order, separated by tabs. Three new lines separate events.

Troubleshooting the dump_events utility

If the dump_events utility fails, check the following items:

  • The files PEM_<host>_3181.log and PEM_<host>_3181.log.lock on UNIX and PEM_<host>_3181.log-lock on Windows have the correct file privileges.
  • Your environment variables $HOME$PATROL_HOME, and $PATROL_ADMIN are correct.
  • Your lock file directory is not NFS mounted.
Was this page helpful? Yes No Submitting... Thank you

Comments