This trace option determines when various triggered trace
actions occur. Supported actions include turning tracing on and off
for all threads, turning tracing on or off for the current thread,
or producing various dumps.
This trace option does not control what is traced. It controls
only whether the information that has been selected by the other trace
options is produced as normal or is blocked.
Each clause of the
trigger option can be
tpnid{...},
method{...},
or
group{...}. You can specify multiple clauses
of the same type if required, but you do not need to specify all types.
The clause types are as follows:
- method{<methodspec>[,<entryAction>[,<exitAction>[,<delayCount>[,<matchcount>]]]]}
- On entering a method that matches <methodspec>,
the specified <entryAction> is run. On leaving
a method that matches <methodspec>, the specified <exitAction> is
run. If you specify a <delayCount>, the actions
are performed only after a matching <methodspec> has
been entered that many times. If you specify a <matchCount>, <entryAction> and <exitAction> are
performed at most that many times.
- group{<groupname>,<action>[,<delayCount>[,<matchcount>]]}
- On finding any active tracepoint that is defined as being in trace
group <groupname>, for example Entry or Exit,
the specified action is run. If you specify a <delayCount>,
the action is performed only after that many active tracepoints from
group <groupname> have been found. If you specify
a <matchCount>, <action> is
performed at most that many times.
- tpnid{<tpnid>|<tpnidRange>,<action>[,<delayCount>[,<matchcount>]]}
- On finding the specified active <tpnid> (tracepoint
ID) or a <tpnid> that falls inside the specified <tpnidRange>,
the specified action is run. If you specify a <delayCount>,
the action is performed only after the JVM finds such an active <tpnid> that
many times. If you specify a <matchCount>, <action> is
performed at most that many times.
Actions
Wherever an action must be specified,
you must select from these choices:
- abort
- Halt the JVM.
- coredump
- See sysdump.
- heapdump
- Produce a Heapdump. See Using Heapdump.
- javadump
- Produce a Javadump. See Using Javadump.
- jstacktrace
- Examine the Java stack of
the current thread and generate auxiliary tracepoints for each stack
frame. The auxiliary tracepoints are written to the same destination
as the tracepoint or method trace that triggered the action. You can
control the number of stack frames examined with the stackdepth=n option.
See stackdepth=<n>. The jstacktrace action
is available from Java 6 SR 5.
- resume
- Resume all tracing (except for threads that are suspended by the
action of the resumecount property and Trace.suspendThis() calls).
- resumethis
- Decrement the suspend count for this thread. If the suspend count
is zero or below, resume tracing for this thread.
- segv
- Cause a segmentation violation. (Intended for use in debugging.)
- sleep
- Delay the current thread for a length of time controlled by the sleeptime option.
The default is 30 seconds. See sleeptime=nnn|aaams|bbbs.
- snap
- Snap all active trace buffers to a file in the current working
directory. The file name has the format: Snapnnnn.yyyymmdd.hhmmssth.ppppp.trc,
where nnnn is the sequence number of the snap file
since JVM startup, yyyymmdd is the date, hhmmssth is
the time, and ppppp is the process ID in decimal
with leading zeros removed.
- suspend
- Suspend all tracing (except for special trace points).
- suspendthis
- Increment the suspend count for this thread. If the suspend-count
is greater than zero, prevent all tracing for this thread.
- sysdump (or coredump)
- Produce a system dump. See Using system dumps and the dump viewer.
Examples
- To start tracing this thread when it enters any method in java/lang/String,
and to stop tracing the thread after exiting the method:
-Xtrace:resumecount=1
-Xtrace:trigger=method{java/lang/String.*,resumethis,suspendthis}
- To resume all tracing when any thread enters a method in any class
that starts with "error":
-Xtrace:trigger=method{*.error*,resume}
- To produce a core dump when you reach the 1000th and 1001st tracepoint
from the "jvmri" trace group.
Note: Without <matchcount>,
you risk filling your disk with coredump files.
-Xtrace:trigger=group{staticmethods,coredump,1000,2}
If using the trigger option generates
multiple dumps in rapid succession (more than one per second), specify
a dump option to guarantee unique dump names. See Using dump agents for more information.
- To trace (all threads) while the application is active; that is,
not start up or shut down. (The application name is "HelloWorld"):
-Xtrace:suspend,trigger=method{HelloWorld.main,resume,suspend}
- To print a Java stack
trace to the console when the mycomponent.1 tracepoint
is reached:
-Xtrace:print=mycomponent.1,trigger=tpnid{mycomponent.1,jstacktrace}
- To write a Java stack
trace to the trace output file when the Sample.code() method
is called:
-Xtrace:maximal=mt,output=trc.out,methods={mycompany/mypackage/Sample.code},trigger=method{mycompany/mypackage/Sample.code,jstacktrace}