These options control which individual tracepoints are
activated at runtime and the implicit destination of the trace data.
In some cases, you must use them with other options. For example,
if you specify maximal or minimal tracepoints, the trace data is put
into memory buffers. If you are going to send the data to a file,
you must use an output option to specify the destination filename.
minimal=[!]<tracepoint_specification>[,...]
maximal=[!]<tracepoint_specification>[,...]
count=[!]<tracepoint_specification>[,...]
print=[!]<tracepoint_specification>[,...]
iprint=[!]<tracepoint_specification>[,...]
exception=[!]<tracepoint_specification>[,...]
external=[!]<tracepoint_specification>[,...]
none[=<tracepoint_specification>[,...]]
Note that all these properties are independent of each other and
can be mixed and matched in any way that you choose.
From WebSphere Real Time V2 SR3, you must
provide at least one tracepoint specification when using the minimal, maximal, count, print, iprint, exception and external options.
In some older versions of the SDK the tracepoint specification defaults
to 'all'.
Multiple statements of each type of trace are allowed and their
effect is cumulative. To do this, you must use a trace properties
file for multiple trace options of the same name.
- minimal and maximal
- minimal and maximal trace
data is placed into internal trace buffers that can then be written
to a snap file or written to the files that are specified in an output
trace option. The minimal option records only
the timestamp and tracepoint identifier. When the trace is formatted,
missing trace data is replaced with the characters "???" in the
output file. The maximal option specifies that
all associated data is traced. If a tracepoint is activated by both
trace options, maximal trace data is produced.
Note that these types of trace are completely independent from any
types that follow them. For example, if the minimal option
is specified, it does not affect a later option such as print.
- count
- The count option requests that only a count
of the selected tracepoints is kept. At JVM termination, all non-zero
totals of tracepoints (sorted by tracepoint id) are written to a file,
called utTrcCounters, in the current directory. This information is
useful if you want to determine the overhead of particular tracepoints,
but do not want to produce a large amount (GB) of trace data.
For example, to count the tracepoints used in the default
trace configuration, use the following:
-Xtrace:count=all{level1},count=j9mm{gclogger}
- print
- The print option causes the specified tracepoints
to be routed to stderr in real-time. The JVM tracepoints are formatted
using J9TraceFormat.dat. The class library tracepoints
are formatted by TraceFormat.dat. J9TraceFormat.dat and TraceFormat.dat are
shipped in sdk/jre/lib and are automatically found by the runtime.
- iprint
- The iprint option is the same as the print option,
but uses indenting to format the trace.
- exception
- When exception trace is enabled, the trace
data is collected in internal buffers that are separate from the normal
buffers. These internal buffers can then be written to a snap file
or written to the file that is specified in an exception.output option.
The exception option
allows low-volume tracing in buffers and files that are distinct from
the higher-volume information that minimal and maximal tracing
have provided. In most cases, this information is exception-type data,
but you can use this option to capture any trace data that you want.
This
form of tracing is channeled through a single set of buffers, as opposed
to the buffer-per-thread approach for normal trace, and buffer contention
might occur if high volumes of trace data are collected. A difference
exists in the <tracepoint_specification> defaults
for exception tracing; see Tracepoint specification.
Note: The
exception trace buffers are intended for low-volume tracing. By default,
the exception trace buffers log garbage collection event tracepoints,
see
Default tracing. You can send additional
tracepoints to the exception buffers or switch off the garbage collection
tracepoints. Changing the exception trace buffers will alter the contents
of the
GC History section in any Javadumps.
Note: When exception trace
is entered for an active tracepoint, the current thread id is checked
against the previous caller's thread id. If it is a different thread,
or this is the first call to exception trace,
a context tracepoint is put into the trace buffer first. This context
tracepoint consists only of the current thread id. This is necessary
because of the single set of buffers for exception trace. (The formatter
identifies all trace entries as coming from the "Exception trace pseudo
thread" when it formats exception trace files.)
- external
- The external option channels trace data to
registered trace listeners in real-time. JVMRI is used to register
or deregister as a trace listener. If no listeners are registered,
this form of trace does nothing except waste machine cycles on each
activated tracepoint.
- none
-Xtrace:none prevents the trace engine
from loading if it is the only trace option specified. However, if
other -Xtrace options are on the command line,
it is treated as the equivalent of -Xtrace:none=all and
the trace engine will still be loaded.
If you specify other tracepoints without
specifying -Xtrace:none, the tracepoints are
added to the default set.
Examples
- Default options applied:
java -Xgcpolicy:metronome
- No effect apart from ensuring that the trace engine is loaded
(which is the default behavior):
java -Xgcpolicy:metronome -Xtrace
- Trace engine is not loaded:
java -Xgcpolicy:metronome -Xtrace:none
- Trace engine is loaded, but no tracepoints are
captured:
java -Xgcpolicy:metronome -Xtrace:none=all
- Default options applied, with the addition of
printing for j9vm.209
java -Xgcpolicy:metronome -Xtrace:iprint=j9vm.209
- Default options applied, with the addition of
printing for j9vm.209 and j9vm.210. Note the use of brackets when
specifying multiple tracepoints.
java -Xtrace:iprint={j9vm.209,j9vm.210}
- Printing for j9vm.209 only:
java -Xgcpolicy:metronome -Xtrace:none -Xtrace:iprint=j9vm.209
- Printing for j9vm.209 only:
java -Xgcpolicy:metronome -Xtrace:none,iprint=j9vm.209
- Default tracing for all components except j9vm,
with printing for j9vm.209:
java -Xgcpolicy:metronome -Xtrace:none=j9vm,iprint=j9vm.209
- Default tracing for all components except j9vm,
with printing for j9vm.209
java -Xgcpolicy:metronome -Xtrace:none=j9vm -Xtrace:iprint=j9vm.209
- No tracing for j9vm (none overrides iprint):
java -Xgcpolicy:metronome -Xtrace:iprint=j9vm.209,none=j9vm