D Using the uerf Event Logger

Note
Information about the uerf event logger is provided in this appendix for backward compatibility reasons. The uerf component will be retired in a future release of the Digital UNIX operating system. The replacement event logger is the DECevent utility. For more information about DECevent, see Chapter 14 and dia(8).

Use the uerf command to produce event reports from the binary log file. You must be superuser to use the uerf command. The uerf command accesses events logged to the binary log file, translates them from binary code to ASCII if necessary, and sends them to the output device you specify. The events include error messages relating to the system hardware and the software kernel, as well as information about system status, startup, and diagnostics. The default binary log file is /usr/adm/binary.errlog.

By reviewing the types and the number of events, you can determine the reliability of a system. If a report shows a large number of errors for a particular device, you can determine if a problem exists before the device fails completely. Furthermore, if a failure occurs, the event report provides information on the events that led to the failure.

The uerf command uses the following three data files:

/usr/sbin/uerf.bin - The event information database

/usr/sbin/uerf.hlp - The help file

/usr/sbin/uerf.err - The error message file

The uerf command allows you to specify the source that it uses to generate event reports, to restrict the event selection, and to produce specific output formats. The uerf command has the following syntax:

/usr/sbin/uerf[options . . .]

Without options, the uerf command outputs the contents of the event-log file specified by the *.* entry in the /etc/binlog.conf configuration file. To report on any other event-log file or if there is no *.* entry, you must use the uerf command with the -f option.

Table D-1 describes the uerf command options.

Table D-1: Options to the uerf Command
Option	Description
`-c` class,...	Selects events for the specified classes.
`-D` [disk,...]	Selects events for the specified mscp and SCSI disk devices.
`-f` filename	Specifies the file from which messages are read.
`-h`	Displays help information.
`-H` hostname	Selects events for the specified host system. This option is used if events from multiple systems are being forwarded to the local host.
`-M` [mainframe,...]	Specifies processor event types.
`-n`	Processes events as they occur.
`-o` output	Produces output in either `brief`, `full`, or `terse` format. The default is `brief`.
`-O` [op_events,...]	Selects the specified operating system events.
`-R`	Produces output in reverse chronological order.
`-r` record,...	Selects events for the specified record codes.
`-s` [seq_of_numbers]	Selects events with the specified sequence of numbers.
`-S`	Produces a summary report.
`-t` time	Selects events within the specified time range.
`-T` [tapes,...]	Selects events for TMSCP tape types and SCSI tape devices.
`-u` number	Selects events from the device with the specified unit number.
`-x`	Excludes specified options.
`-Z`	Produces output in hexadecimal format.

To use the uerf command in single-user mode, you must ensure that the file system containing the binary log file and the uerf command data files is mounted.

The line printer spooler is not operational during single-user mode. Therefore, to print a report on a line printer while in single-user mode, you must direct the output to a printer special file as shown in the following example:

# /usr/sbin/uerf > /dev/lp

You can use some options together. For example, the following command produces a report from the /var/admin/logs.old file for the system guitar:

# /usr/sbin/uerf -f /var/admin/logs.old -H guitar

The following example uses the -t and the -o options to display messages for the current day in terse format:

# /usr/sbin/uerf -t s:00 -o terse

The following example shows the default output of the uerf command:

# /usr/sbin/uerf
					uerf version 4.2-011 (118)

************************* ENTRY  1. **************************

----- EVENT INFORMATION -----

EVENT CLASS                    OPERATIONAL EVENT
OS EVENT TYPE           300.   SYSTEM STARTUP
SEQUENCE NUMBER           0.
OPERATING SYSTEM               DEC OSF/1
OCCURRED/LOGGED ON             Tue Jan 11 17:16:18 1994
OCCURRED ON SYSTEM             pearl
SYSTEM ID          x0004000F   CPU TYPE: DEC
                               CPU SUBTYPE: KN15AA
MESSAGE                        Alpha boot: available memory from
                                _0x646000 to 0x6000000
                               DEC OSF/1 X1.2-11  (Rev. 4); Tue Jan
                                _11 17:13:53 EST 1994
                               physical memory = 94.00 megabytes.
                               available memory = 85.48 megabytes.
                               using 360 buffers containing 2.81
                               _megabytes of memory
                               tc0 at nexus
                               scc0 at tc0 slot 7
                               asc0 at tc0 slot 6
                               rz1 at asc0 bus 0 target 1 lun 0 (DEC
                                _   RZ25     (C) DEC 0700)
                               rz2 at asc0 bus 0 target 2 lun 0 (DEC
                                _   RZ25     (C) DEC 0700)
                               tz5 at asc0 bus 0 target 5 lun 0 (DEC
                                _   TLZ06     (C)DEC 0374)
                               asc1 at tc0 slot 6
                               fb0 at tc0 slot 8
                               1280X1024
                               ln0: DEC LANCE Module Name: PMAD-BA
                               ln0 at tc0 slot 7
                               ln0: DEC LANCE Ethernet Interface,
                                _hardware address: 08:00:2b:2c:f6:9f
                               DEC3000 - M500 system
                               Firmware revision: 2.0
                               PALcode: OSF version 1.28
                               lvm0: configured.
                               lvm1: configured.
                               setconf: bootdevice_parser translated
                                _'SCSI 0 6 0 0 300 0 FLAMG-IO' to
                                _'rz3'

************************ ENTRY     2. ****************************

----- EVENT INFORMATION -----

EVENT CLASS                          ERROR EVENT
OS EVENT TYPE               199.     CAM SCSI
SEQUENCE NUMBER               1.
OPERATING SYSTEM                     DEC OSF/1
OCCURRED/LOGGED ON                   Tue Jan 11 18:05:10 1994
OCCURRED ON SYSTEM                   pearl
SYSTEM ID              x0004000F     CPU TYPE: DEC
                                     CPU SUBTYPE: KN15AA
----- UNIT INFORMATION -----

CLASS                      x0005     RODIRECT
SUBSYSTEM                  x0000     DISK
BUS #                      x0000
                           x0020     LUN x0
                                     TARGET x4

D.1 Specifying the Report Source

The following sections describe how to use the uerf command options that allow you to specify the source used to generate event reports.

D.1.1 Selecting the Event Class

Use the uerf command with the -c option to select the specified class of events. The uerf -c command has the following syntax:

uerf-c class

You can specify the following class variables:

Event Class	Description
`err`	Reports hardware-detected and software-detected events.
`maint`	Reports events that occur during system maintenance, such as running the online functional exercisers.
`oper`	Reports information on system status, autoconfiguration messages, device status and error messages, time stamps, and system startup and shutdown messages.

D.1.2 Selecting Disk Events

Use the uerf command with the -D option to select events for the specified disk type (for example, rz55) or disk class (for example, rz). The uerf -D command has the following syntax:

uerf -D [disk . . .]

If you do not specify a disk variable, events for all disks are reported. If you specify more than one disk variable, separate them with commas. For example:

# /usr/sbin/uerf -D rz23,rz24

D.1.3 Selecting Mainframe Events

Use the uerf command with the -M option to select events for the specified mainframe event type. The uerf -M command has the following syntax:

uerf -M [mainframe . . .]

You can specify the following mainframe variables:

Mainframe Events	Description
`cpu`	Reports CPU-related events, such as machine checks.
`mem`	Reports memory-related events, such as single-bit corrected read data (CRD) and double-bit uncorrectable errors.

If you do not specify a mainframe variable, all mainframe events are reported. If you specify more than one mainframe variable, separate them with commas. For example:

# /usr/sbin/uerf -M cpu,mem

D.1.4 Selecting Events As They Occur

Use the uerf command with the -n option to report events as they occur. You can use this option if you run the system exercisers. The uerf -n command has the following syntax:

uerf -n

You cannot specify the -f option with the -n option.

D.1.5 Selecting Operating System Events

Use the uerf command with the -O option to select operating system events such as panics, exceptions, and faults. The uerf -O command has the following syntax:

uerf -O [op_system . . .]

You can specify the following op_system variables:

Operating System Events	Description
`aef`	Arithmetic exception faults
`ast`	Asynchronous trap exception faults
`pag`	Page faults
`pif`	Privileged instruction faults
`pro`	Protection faults
`ptf`	Page table faults
`raf`	Reserved address faults
`rof`	Reserved operand faults
`scf`	System call exception faults
`seg`	Segmentation faults

If you do not specify an op_system variable, all operating system events are reported. If you specify more than one op_system variable, separate them with commas. For example:

# /usr/sbin/uerf -O raf,ptf,ast

D.1.6 Selecting Tape Events

Use the uerf command with the -T option to select events for the specified tape type (for example, tz30) or tape class (for example, tz). The uerf -T command has the following syntax:

uerf -T [[tape]]

If you do not specify a tape variable, events for all tape types and tape classes are reported. If you specify more than one tape variable, separate them with commas. For example:

# /usr/sbin/uerf -T tz 

# /usr/sbin/uerf -T tz31

D.1.7 Generating Reports from Files

Use the uerf command with the -f option to select events from the specified log file instead of the default log file, which is defined by the *.* entry destination in the /etc/binlog.conf file. The uerf -f command has the following syntax:

uerf -f filename

The filename variable specifies the event-log file to use. You must specify the full pathname for the file, for example:

# /usr/sbin/uerf -f /var/adm/binary.old

You cannot specify the -n option with the -f option.

D.1.8 Generating Reports for Hosts

Use the uerf command with the -H option to select events for the specified host system. Use this option if events from remote systems are being forwarded to your local system. The uerf -H command has the following syntax:

uerf -H hostname

D.1.9 Selecting Events by Record Code

Use the uerf command with the -r option to select events with the specified record codes. The -r option offers an alternate way to report specific events, such as disk and tape events. The uerf -r command has the following syntax:

uerf -r record . . .

You can specify the following record variables:

Record code	Hardware-Detected Events
100	CPU machine checks and exceptions
101	Memory errors (soft and hard)
102	Disk errors
103	Tape errors
104	Device controller errors
105	Adapter errors
106	Bus errors
107	Stray interrupts
108	Console events
109	Stack dump
199	CAM (SCSI) events

Record code	Software-Detected Events
201	ci ppd events
202	scs events

Record code	ASCII Messages
250	Informational

Record code	Operational Messages
300	Startup
301	Shutdowns and reboots
302	Panics
350	Diagnostics status

If you specify more than one record variable, separate them with commas. You can also separate record variables with a dash (-) to indicate a sequence of record codes.

The following example produces all system startup messages, including hardware devices configured and their control status register (CSR) addresses:

# /usr/sbin/uerf -r 300

The following example specifies a sequence of records:

# /usr/sbin/uerf -r 100-109

The following example specifies two records:

# /usr/sbin/uerf -r 100,102

D.2 Restricting Events

The following sections describe how to restrict the event selection in the report by specifying a time range, sequence numbers, or a unit number with the uerf command. You can also exclude events from a particular source.

D.2.1 Specifying Sequence Numbers

Use the uerf command with the -s option to select events with the specified sequence numbers. A sequence number is assigned to an event when it is logged. You can use this option to report specific events after viewing the event-log file at your terminal. The uerf -s command has the following syntax:

uerf -s seq_of_numbers

The seq_of_numbers variable specifies the beginning and ending sequence numbers separated by a dash (-). For example:

# /usr/sbin/uerf -s 750-800

Note
Sequence numbers restart when you reboot the system. If the event-log file contains events from before and after a reboot, the file may contain duplicate sequence numbers.

If the -s option is the only uerf command option specified, all events with the specified sequence numbers are reported.

D.2.2 Specifying a Time Range

Use the uerf command with the -t option to select events in the specified time range. The uerf -t command has the following syntax:

uerf -t time

The time variable specifies the start and end of the time range. If you do not use the -t time option, the entire event-log file is used to report events. The time variable has the following syntax:

s:dd-mmm-yyyy,hh:mm:ss e:dd-mmm-yyyy,hh:mm:ss

The dd-mmm-yyyy variable specifies the day, month, and year. The hh:mm:ss variable specifies the hours, minutes, and seconds. You specify the start time after the s: symbol, and you specify the end time after the e: symbol.

The uerf -s command uses the following defaults for the date and time:

The current date
The start time is 00:00:00
The end time is 23:59:59

The following example produces a report that contains all events for the 24-hour period of January 11, 1994:

# uerf -t s:11-jan-1994,00:00:00 e:11-jan-1994,23:59:59

The following command produces a report from the beginning of the event-log file until February 29 of the current year:

# /usr/sbin/uerf -t e:29-feb

The following command produces a report for all events on the current day and year, starting at 1:20 p.m. and ending at the current time:

# /usr/sbin/uerf -t s:13:20

D.2.3 Specifying Unit Numbers

Use the uerf command with the -u option to select events from the disk or tape device unit number. The uerf -u command has the following syntax:

uerf-u number

The number variable specifies the tape or disk unit number. You can use this option only with the -D and the -T options.

D.2.4 Excluding Reported Events

Use the uerf command with the -x option to exclude the specified event source from the report. You can exclude the -c, -D, -M, -O, and -T options from the request. Refer to Section D.1 for more information on event sources. The uerf -x command has the following syntax:

uerf-x [-c] [-D] [-M] [-O] [-T]

The options to be excluded can appear before or after the -x option.

For example, the following command reports all events except disk events and operating system events:

# /usr/sbin/uerf -O -x -o full -D

D.3 Controlling the Report Output

The following sections describe the options that control the report output of the uerf command.

D.3.1 Generating Summary Reports

Use the uerf command with the -S option to produce a summary report. All the uerf source selection options (-c, -D, -M, -O, and -T) support summaries. The default format for summary report output is terse. Refer to Section D.3.2 for more information on output formats.

The following example shows the command and options that generate a terse summary of all events recorded for the day in the log file:

# /usr/sbin/uerf -t s:00 -S

D.3.2 Specifying the Type of Output

Use the uerf command with the -o option to format the report output. The uerf -o command has the following syntax:

uerf -o output

The output variable can be one of the following:

Output Type	Description
`brief`	Reports event information in a short format. This is the default.
`full`	Reports all available information for each event.
`terse`	Reports event information and displays register values but does not translate the events to ASCII.

Usually, the -o full option produces the most event information. However, panic messages and other ASCII messages do not provide more information with the -o full option.

The following example shows the default brief format for a memory event:

# /usr/sbin/uerf -r 101

The following example shows the information produced by full output format for this report, which displays all memory-related events:

# /usr/sbin/uerf -o full -r 101

D.3.3 Generating Reports in Reverse Chronological Order

Use the uerf command with the -R option to report events in reverse chronological order.

The following example causes the uerf command to produce a report that lists all startup messages, beginning with the most recent:

# /usr/sbin/uerf -R -r 300

D.3.4 Displaying Hexadecimal Output

Use the uerf command with the -Z option to output event entries in hexadecimal format.