Content-type: text/html Man page of voltrace

voltrace

Section: Maintenance Commands (8)
Index Return to Main Contents
 

NAME

voltrace - Trace operations on volumes  

SYNOPSIS

/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...]


 

OPTIONS

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.
 

DESCRIPTION

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.
 

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 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.
 

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(8) for a list of standard exit codes.
 

FILES

Default device to which events are logged.
 

SEE ALSO

volintro(8), volstat(8)


 

Index

NAME
SYNOPSIS
OPTIONS
DESCRIPTION
OUTPUT FORMAT
EXIT CODES
FILES
SEE ALSO

This document was created by man2html, using the manual pages.
Time: 02:40:34 GMT, October 02, 2010