vxtrace(1M)															       vxtrace(1M)

NAME

       vxtrace - trace operations on volumes

SYNOPSIS

       vxtrace [-aeEls ] [-b buffersize] [-c eventcount]
	      [-d outputfile] [-f inputfile] [-g diskgroup]
	      [-k buffersize] [-m millisec_delay]
	      [-o objtype [,objtype]...]  [-t timeout]
	      [-w waitinterval] [name | device]...

DESCRIPTION

       The  vxtrace  utility  prints  kernel  error  or  I/O trace event records on the standard output or writes them to a file in binary format.
       Binary trace records written to a file can be read back and formatted by vxtrace as well.

       If no arguments are specified, vxtrace reports either all error trace data or all I/O trace data on all virtual disk devices.   With  error
       trace  data, it is possible to select all accumulated error trace data, to wait for new error trace data, or both (the default).  Selection
       can be limited to a specific disk group, to specific types of Veritas Volume Manager (VxVM) kernel I/O  objects,  or  to  particular  named
       objects or devices.

       Under  heavy  loads,  the  kernel  may discard one or more records before they can be reported to vxtrace.  Even though the contents of the
       records are lost, the kernel keeps track of the number of lost records and reports this to vxtrace.  as a record.   vxtrace  displays  this
       record  indicating  that  records  were	lost.  You can increase the size of the kernel buffer using the -k buffersize option to reduce the
       likelihood of the kernel discarding records.

OPTIONS

       -a	 Appends to the outputfile instead of truncating it.  By default, the output file is truncated.

       -b buffersize
		 Sets the size of the buffer used by vxtrace when it obtains trace records from the kernel, or from a file when the -f	option	is
		 specified.   The buffer size is specified as a standard Veritas Volume Manager length (see vxintro(1M)).  The default buffer size
		 is 8K.

       -c eventcount
		 Accumulates at most eventcount events and then exits.	The timeout and eventcount options can be used together.

       -d outputfile
		 Writes (dumps) binary trace data to the specified output file.

       -e	 Selects new error trace data.	The default is to select I/O trace data.

       -E	 Selects pre-existing error trace data.  This can be combined with -e to get both pre-existing trace data and new trace data.

       -f inputfile
		 Reads binary trace data from the specified input file, instead of from the Veritas Volume Manager kernel.

       -g diskgroup
		 Selects objects from the specified disk group.  The disk group can be specified either by disk group ID or by	disk  group  name.
		 With  no  name  or  device  arguments, all appropriate objects in the disk group are selected.  With the name argument, diskgroup
		 specifies the disk group that contains the named configuration record.

       -k buffersize
		 Sets the kernel I/O trace buffer size.  The Veritas Volume Manager kernel allocates a private kernel  space  to  buffer  the  I/O
		 trace	records  for each vxtrace command.  The default buffer size is 8K bytes.  Some trace records may be discarded if the trace
		 buffer is too small.  This option can be used to set a larger or a smaller kernel trace buffer size.  The buffer size	is  speci-
		 fied  as  a  standard Veritas Volume Manager length (see vxintro(1M)).  Depending on the Veritas Volume Manager kernel configura-
		 tion, usually only a maximum buffer size of 1 megabyte is granted.

       -l	 Long format.  Prints all available fields for all tracing records, instead of a subset of the available fields.  The  default	is
		 to use the short format.

       -m millisec_delay
		 Pauses vxtrace for the specified period to allow more records to accumulate.

       name | device
		 If name or device are specified, Veritas Volume Manager kernel objects of the requested types are selected if they are associated
		 with the configuration records or virtual disk devices indicated by those arguments.

       -o objtype [,objtype]...
		 Selects object based on the objtype option arguments.	Multiple types of objects can be specified with one or several -o options.
		 The possible object selection types are:

		 all | ALL Selects all possible virtual disk devices, kernel objects, and physical disks.

		 dev | logical
			   Selects virtual disk devices.

		 disk | physical
			   Selects Veritas Volume Manager physical disks.

		 log	   Selects all log objects.

		 logplex   Selects RAID-5 log plexes.

		 logsd	   Selects DRL (dirty region logging) or RAID-5 log subdisks.

		 logvol    Selects DRL or RAID-5 log volumes.

		 m | mv | mirror
			   Selects mirrored volume kernel objects.

		 p | pl | plex
			   Selects striped or concatenated plex kernel objects.

		 rl | rlink
			   Selects  RLINK  kernel  objects.  If an RVG (replicated volume group) is specified, all RLINKs associated with that RVG
			   are selected.

		 s | sd | subdisk
			   Selects subdisk kernel objects.

		 v | vol | volume
			   Selects mirrored or RAID-5 volume kernel objects.

       -s	 Specifies using synchronous writes to the outputfile instead of asynchronous writes.  Asynchronous writes is the default.

       -t timeout
		 Accumulates trace data for at most timeout seconds, then exits.

       -w waitinterval
		 If vxtrace waits for waitinterval seconds without receiving any new events, prints waiting...	to allow scripts to  wake  up  and
		 process previously accumulated events.  This is useful for processing errors.	The waiting...	message does not count as an event
		 for the purposes of the -c option.

ARGUMENTS

       Arguments specify configuration record names, or physical or virtual disk device nodes (by device path).  If no object types were  selected
       with  the -o option, only trace records corresponding to the indicated configuration records or devices are selected; otherwise, objects of
       the requested types are selected if they are associated in any way with the named configuration record or device.

       If a name argument does not match a regular configuration record, but does match a disk access  record,	the  indicated	physical  disk	is
       selected.  Physical disks can also be selected by the disk media record name.

       By  default,  name  arguments  are searched for in the default disk group (defaultdg) unless a disk group is specified using the -g option.
       The disk group for any individual name argument can be overridden using the form:

	      diskgroup/recordname

       Note: When reading trace data from a file with the -f option, association information is not available.

EXAMPLES

       To trace all physical disk I/Os, enter:

	      vxtrace -o disk

       To trace virtual disk device I/Os to the device associated with volume testvol, use either of the commands:

	      vxtrace -g testdg -o dev testvol
	      vxtrace /dev/vx/dsk/testdg/testvol

       To trace all log subdisks associated with volume testvol, enter:

	      vxtrace -g testdg -o logsd testvol

       To trace all log objects, enter:

	      vxtrace -o log

       To accumulate ten seconds worth of trace data for disk04 and then format that data, use:

	      vxtrace -t 10 -d /tmp/tracedata disk04
	      vxtrace -l -f /tmp/tracedata

       To read error trace data into a script for processing, using ten second pauses to generate mail messages, use the command:

	      vxtrace -leE -w 10 | while read ...

FILES

       /dev/vx/trace

SEE ALSO

       vxintro(1M), vxstat(1M), vxtrace(7)

VxVM 5.0.31.1							    24 Mar 2008 						       vxtrace(1M)