Content-type: text/html
voltrace - Trace operations on volumes
/usr/sbin/voltrace [-nc] [-f tracefile] [-e eventlist] [-t timeout] [-d tracefile] [vol...]
/usr/sbin/voltrace -s eventlist [vol...]
/usr/sbin/voltrace -S eventlist
/usr/sbin/voltrace -l [vol...]
The following options are recognized:
Prints 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.
Prints current event log records, which depict recent past
events.
Reads 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.
Specifies 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:
Traces I/O events. This trace may produce extensive output
and should be used with care.
Traces I/O errors and error recovery operations.
Traces everything. As with
io, this trace
can produce excessive output.
Traces logical events only (in other words, requests to the
logical volume devices). This option is valid only for output filtering.
Clears appropriate trace masks.
Traces physical events only (in other words, requests passed
to the underlying block device drivers from the Logical Storage 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).
Reports event log records for the next
timeout
seconds. If reading events from a regular file, this option
is ignored.
Dumps the unformatted event log records collected from the
/dev/volevent
device into
tracefile
rather
than formatting them to standard output.
Sets 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.
Sets the system default trace mask. This mask is adopted
by any volumes for which no mask currently exists.
Lists the events in the trace masks for the specified volumes,
or for all volumes if none are specified.
Lists the events in the system default trace mask.
The /usr/sbin/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. The eventlist parameter 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 which 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.
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 two event types, io, and error. However, the first three fields of each line are common to all types and have the following form:
tick type evnum:
The tick field 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
The reqid field is the unique transaction number for the I/O. Both logical and physical trace events for a single transaction (such as an I/O request that gets broken down into multiple physical requests) have the same reqid. The iotypefield 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
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 physical I/O records representing the actual I/O's required to execute the logical request (for example, writes to subdisks on two 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
The command field 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.
The error records have two forms analogous to the two io record forms: summary and physical I/O errors. These two forms have the following formats:
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
The
resid
field 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.
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(8)
for a list of
standard exit codes.
Default device to which events are logged.