Index for Section 8

Alphabetical listing for V

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

OPTIONS
  The following options are recognized:

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

  -c  Prints current event log records, which depict recent past events.

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

  -e eventlist
      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:

      io  Traces I/O events.  This trace may produce extensive output and
	  should be used with care.

      error
	  Traces I/O errors and error recovery operations.

      all Traces everything.  As with io, this trace can produce excessive
	  output.

      logical
	  Traces logical events only (in other words, requests to the logical
	  volume devices). This option is valid only for output filtering.

      none
	  Clears appropriate trace masks.

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

  -t timeout
      Reports event log records for the next timeout seconds.  If reading
      events from a regular file, this option is ignored.

  -d tracefile
      Dumps the unformatted event log records collected from the
      /dev/volevent device into tracefile rather than formatting them to
      standard output.

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

  -S eventlist
      Sets the system default trace mask.  This mask is adopted by any
      volumes for which no mask currently exists.

  -l  Lists the events in the trace masks for the specified volumes, or for
      all volumes if none are specified.

  -L  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
  /dev/volevent
      Default device to which events are logged.


SEE ALSO
  volintro(8), volstat(8)