vttrace(1)vttrace(1)NAMEvttrace - Visual Threads trace utility
SYNOPSISvttrace [-hf] [-a] [-l] [-c calls] [-m MaxTraceSize] [-o file]
[-e {all|sched|once|system|key}] [-d {all|sched|once|system|key}]
program [argument...]
DESCRIPTION
The vttrace command creates a trace file representing the pthreads
activity of the specified program during its execution. This trace
file can then be analyzed by Visual Threads using the Play Trace
File... option available from the File menu. With the exception of any
dynamic interactions such as invoking the debugger, or changing data
collection options as the program executes, trace files support the
full analysis capabilities of Visual Threads.
On Tru64 UNIX systems, you can use vttrace in conjunction with the vti
command to generate a trace file that contains information about
unguarded data, other violations detected by vti,or data locality anal‐
ysis on NUMA systems. When using the vti command, specify the program
as vti, include the -run option, any other desired vti options, and the
-prog program option followed by any arguments to the program being
traced. Also see the description of the -l option for information about
data locality analysis. When you replay a trace file created by vttrace
with vti, you may need to add the original source directory of the pro‐
gram into the Setup/Source Directories window in order to get source
correlation during the replay.
For more information about trace files, see the Visual Threads online
Help.
OPERANDS
program
File name of a fully linked shared or nonshared executable to be
traced. This program should be compiled with the -g or -gn option
(n>=1) to supply the best interpretation by Visual Threads. If the
default symbol table level (-g0) is used, line number information,
static procedure names, and file names are unavailable. Inlined
procedure calls are also unavailable.
argument
All arguments following the program name are considered to be argu‐
ments needed by the traced program to execute the procedures,
lines, and instructions of interest. Multiple arguments can be
specified.
OPTIONS-a Analyze the program and produce a trace file of only relevant
events necessary to recreate any Visual Threads analysis alarms
relating to the Deadlock or Programming Errors rule categories.
This option causes fewer events to be captured into the output
trace file. A program that deadlocks or that appears to hang can be
forced to generate the trace file and exit by typing a Ctrl-C char‐
acter in the terminal window running vttrace. If the program
causes a Visual Threads deadlock.deadlock analysis alarm, a trace
file will automatically be genetated and the program will be forced
to terminate. The output trace file can then be analyzed by Visual
Threads to identify the same alarms as a complete trace file.
-c calls
Sets the maximum number of calls collected and saved into the trace
file at each event. If no -c option is specified, the default max‐
imum callstack elements collected is 5.
-d {all|sched|once|system|key}
Disables collection of various event types. Repeat the -d option
for each event type to be disabled. Multiple -e and -d options
evaluated from left-to-right. (See Notes below, also.)
-e {all|sched|once|system|key}
Enables collection of various event types. Repeat the -e option
for each event type desired. By default system and sched are col‐
lected. Multiple -e and -d options evaluated from left-to-right.
Notes: Each of these event types has a corresponding toggle in the
Visual Threads Option dialog on the Data Collection tab. In par‐
ticular, the system option corresponds to the Visual Threads option
"Collect events for all system runtime library internals" toggle.
If system internal events are not collected, you should only ana‐
lyze the file with the corresponding "Collect events for all system
runtime library internals" toggle disabled (it is disabled by
default), to avoid spurious errors due to inconsistent treatment.
-f Generate a trace file for each child process forked by the program.
One trace file is created for the parent process and each child
process that is forked as long as it is linked against the pthreads
library libpthread.so. By default, the generated trace files are
named program.pid.trc. If you want to specifically name the files
using the -o option, be sure to include %d as a part of the file‐
name which will be replaced with the pid of the traced process.
Otherwise, the trace events from both parent and child go to the
same file, which then cannot be analyzed by Visual Threads.
-h Displays usage summary message.
-l On a NUMA machine running Tru64 UNIX, include data locality infor‐
mation in the resultant trace file. This option can only be used
in conjunction with the vti command, and cannot be used with the -a
option. Since this option requires vti to instrument and analyze
every machine instruction load and store in thie application, this
operation can be time consuming, especially for applications which
are CPU-intensive. By default, data locality information will be
collected for system libraries as well as the application, so it's
recommended that you also use the -d system option for somewhat
better performance, particularly if you don't need data locality
information about system libraries.
-o file
Sets the name for the output trace file. If omitted the default
file name is program.trc, or program.pid.trc if also using the -f
option. Use %d within the filename to specify that the filename
should be uniquely named with the pid of the traced process (par‐
ticularly important when also specifying the -f option).
-m MaxTraceFile
Sets the maximum size for a single trace file. When the trace file
reaches the largest power of two less than MaxTraceFile, tracing is
disabled. By default MaxTraceFile is specified in bytes. You can
specify MaxTraceFile in either kilobytes or megabytes by appending
the letter k for kilobytes or the letter m for megabytes. This
option cannot be used with the analysis option -a.
EXAMPLES
To generate a trace file called primes.trc in the working directory
from the primes example program use the following command:
% vttrace /usr/examples/VisualThreads/primes
To generate a trace file called phil.trc in the working directory from
the phil example program but only capture alarm generating events, use
the following command. When phil deadlocks, the trace file will be
written and the program will be terminated automatically.
% vttrace-a /usr/examples/VisualThreads/phil
On Tru64 UNIX systems, to generate a trace file called /tmp/p.trc from
the phil example program (which includes unguarded data analysis) use
the following command:
% vttrace-a-o /tmp/p.trc vti -run-prog /usr/examples/Visu‐
alThreads/phil
On Tru64 UNIX systems, to generate a trace file called lc.trc from a
local copy of the primes example program, and include data locality
analysis on just the application, use the following command:
% vttrace-o lc.trc -l -d system vti -run -prog ./primes
EXIT STATUS
If the -a option is used, the exit status from vttrace represents the
number of analysis errors found. Otherwise, the exit status is zero.
FILES
program.trc
Trace file produced by program.
RELATED INFORMATION
HP-UX Commands: VisualThreads(1), X(1), gdb(1), pthread(3T).
Linux Commands: VisualThreads(1), X(1X).
Tru64 UNIX Commands: VisualThreads(1), vti(1), ladebug(1), pthread(3),
X(1X).
vttrace(1)
