voltrace(1M) Volume Manager Utilities voltrace(1M)
NAME
voltrace - Traces operations on volumes
SYNOPSIS
voltrace [ -nc ] [ -f tracefile ] [ -e eventlist ] [ -t
timeout ] [ -d tracefile ] [ vol ... ]
voltrace -s eventlist [ vol ... ]
voltrace -S eventlist
voltrace -l [ vol ... ]
voltrace -L
DESCRIPTION
The voltrace utility prints formatted event log records and
sets event trace masks.
In the first form, voltrace reads an event log and writes
formatted log entries to standard output. The default event
log is the /dev/volevent device. If no vol operands are
given, then log entries from all volumes in the
configuration database are reported. Otherwise, only
records involving the selected volumes are printed.
If the -s option is used, voltrace sets one or more trace
masks which causes certain volume events to be logged to the
/dev/volevent device. eventlist specifies the set of those
events. If vol operands are specified, then only the trace
masks for those volumes are modified. Otherwise, the
eventlist forms the trace mask for all existing volumes.
See the -e eventlist option below for the list of valid
events. Also, eventlist may be the keyword none. In this
case, the appropriate trace masks are cleared.
With the -S option, voltrace sets the system default trace
mask, which is then used as the trace mask for any volumes
for which a trace mask has not been set.
The -l and -L options are analogous to the -s and -S
options, but they list rather than set the appropriate trace
masks.
OPTIONS
The following options are recognized:
-n Print new event log records rather than reporting on
old ones. This is the default option for reading from
the /dev/volevent device. When reading from a regular
file, this option is ignored.
-c Print current event log records, which depict recent
past events.
-f tracefile
Page 1 (printed 1/21/92)
voltrace(1M) Volume Manager Utilities voltrace(1M)
Read event log records from the unformatted file
tracefile rather than from the /dev/volevent device.
Presumably tracefile was previously created with the -d
option of voltrace.
-e eventlist
Specify a comma-separated list of events to be reported
by voltrace. If this option is not specified, all
events in the log are printed. The event names in
eventlist consist of one of the following keywords:
io Trace I/O events. This trace may produce
voluminous output and should be used with care.
config
Trace configuration change events.
error
Trace I/O errors and error recovery operations.
all Trace everything. As with io, this trace can
produce excessive output.
logical
Trace logical events only (i.e. requests to the
logical volume devices). This option is valid
only for output filtering.
physical
Trace physical events only (i.e. requests passed
to the underlying block device drivers from the
volume manager). This option is valid only for
output filtering.
Note that trace masks must be properly set for voltrace to
print the desired events (for example, voltrace -S io must
be done before all io events can be printed).
-t timeout
Report event log records for the next timeout seconds.
If reading events from a regular file, this option is
ignored.
-d tracefile
Dump the unformatted event log records collected from
the /dev/volevent device into tracefile rather than
formatting them to standard output.
-s eventlist
Set the trace mask for the specified volumes, or for
all volumes if none are specified, so the events given
by eventlist are logged for those volumes.
Page 2 (printed 1/21/92)
voltrace(1M) Volume Manager Utilities voltrace(1M)
-S eventlist
Set the system default trace mask. This mask is
adopted by any volumes for which no mask currently
exists.
-l List the events in the trace masks for the specified
volumes, or for all volumes if none are specified.
-L List the events in the system default trace mask.
OUTPUT FORMAT
The formatted output produced by voltrace (without the -d
option) contains one line per event log record. In general,
the output is different for each of the three event types:
io, config, and error. However, the first three fields of
each line are common to all types and have the form
tick type evnum:
where tick is the number of clock ticks since boot time,
type is the event type, and evnum is the event number.
For physical io event records, the remainder of the line
looks like this:
req reqid v:vol p:plex s:subdisk iot iotype lb block b start
len length tm elapsed
where reqid is the unique transaction number for the I/O.
Both logical and physical trace events for a single
transaction (like an I/O request that gets broken down into
multiple physical requests) have the same reqid. iotype is
the type of I/O; block is the block offset within the
logical request; start is the starting block of the request;
length is the number of bytes for the request; elapsed is
the number of clock ticks required to complete the I/O; and
vol, plex, and subdisk are the names of the volume, plex,
and subdisk, respectively.
For logical io events, the remainder of the line looks like
this:
req reqid v:vol iot iotype lb block b start len length tm
elapsed
where the fields are the same as in the physical event
record, but the block offset, start and length refer to the
logical blocks on the volume device.
For each I/O request, at least two trace records appear in
the log. The logical records is a summary record for the
I/O request (for example, volume write), The rest are
Page 3 (printed 1/21/92)
voltrace(1M) Volume Manager Utilities voltrace(1M)
physical I/O records representing the actual I/O's required
to execute the logical request (for example, writes to
subdisks on 2 plexes). Trace records that belong to the
same I/O request have the same reqid fields. This address
is guaranteed to be a unique number within the normal epoch
bounds.
For config records, the end of the line looks like this:
cmd command rval return errno errno tid trans n1:obj1
ns2:obj2
where command is the ioctl command issued; return is the
return value; errno is the usual errno value; trans is the
transaction id for the execution of the ioctl; and obj1 and
obj2 are the names of the objects acted upon.
error records have two forms analogous to the two io record
forms: summary and physical I/O errors. The output format
of these two forms follow.
Summary:
v:vol req ioreq iot iotype ex except s succp f failp ns
succnp nf failnp
Physical I/O:
v:vol p:plex s:subdisk lb block b start len length res resid
err errno
where resid is the number of bytes of the request not
completed; errno is the usual error value returned via the
application external variable errno; except is the number of
any exception recognized; succp is the number of
participating plexes on which the I/O succeeded; failp is
the number of failed participating plexes; and succnp and
failnp are the successful and failed non-participating
plexes, respectively. The other fields have the same
meanings as they did for io records.
EXIT CODES
The voltrace utility exits with a nonzero status if the
attempted operation fails. A nonzero exit code is not a
complete indicator of the problems encountered, but rather
denotes the first condition that prevented further execution
of the utility. See volintro(1M) for a list of standard
exit codes.
FILES
/dev/volevent
SEE ALSO
volintro(1M), volstat(1M), and volevent(7).
Page 4 (printed 1/21/92)