*** UNIX MANUAL PAGE BROWSER ***

voltrace(8) System Manager's Manual voltrace(8) 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 ... ] DESCRIPTION The /usr/sbin/voltrace -L 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 vol- umes 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 exist- ing 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 op- tions, but they list rather than set the appropriate trace masks. 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 unformat- ted file tracefile rather than from the /dev/volevent device. Presum- ably, 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 out- put. Traces logical events only (in other words, requests to the logi- cal 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 filter- ing. 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 de- fault trace mask. OUTPUT FORMAT The formatted output produced by voltrace (without the d option) con- tains one line per event log record. In general, the output is differ- ent 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 follow- ing 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 (such as an I/O re- quest 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 vol- ume 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 exam- ple, 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 guaran- teed 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 ex- ecution 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: sum- mary 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 oper- ation fails. A nonzero exit code is not a complete indicator of the problems encountered, but rather denotes the first condition that pre- vented further execution of the utility. See volintro(8) for a list of standard exit codes. FILES Default device to which events are logged. RELATED INFORMATION Commands: volintro(8), volstat(8) delim off voltrace(8)