 |
The information in this document applies only to applications running on the Solaris™ 10 Operating System.
This document describes the DTrace probe provider functionality for Sun Java™ Real-Time System.
This functionality allows real-time developers to observe,
debug, and tune their real-time applications. With the jrts provider,
it is possible to monitor activities from priority updates to
memory area operations, as well as RTGC cycles, all without any modification
to the running application. It is possible to synchronize a DTrace
script with the start of the Java virtual machine, but a DTrace script
can also be launched to monitor an already running virtual machine.
Readme File: Links to all the Java RTS technical documents
Contents
How to Use the Java RTS DTrace Provider
Probes
Probes Related to Schedulables
Probes Related to Memory
Probes Related to Threads
Probes Related to Handlers
Probes Related to Compilation
Probes Related to the RTGC
Probes Related to Classes
Probes Related to the VM
Probes Related to the Application
Supported Platforms
Sample Scripts
Contact Us
How to Use the Java RTS DTrace Provider
First of all, it is strongly recommended to read the DTrace documentation
available here.
The rest of this document assumes that the reader is familiar with
the D language and how DTrace works.
The jrts provider is a statically defined user provider working through the
standard pid provider. To enable a jrts probe to monitor a real-time
virtual machine, the provider name to use is jrts followed by the
process ID of the virtual machine. For instance, to enable the probe
thread-start in the JVM running in process 1245, the clause is written
as follows:
jrts1245:::thread-start
{
/* your action */
}
You can avoid hard coding the pid in the clause by using a variable or a
script argument to store the pid of the targeted VM. In the sample scripts provided
at the end of this document, the variable $target is used to specify the pid
with the -p option on the dtrace command line.
To be able to compile a D script using the jrts provider, the targeted VM must be
running and the probes available. If the Java RTS VM is started with the -XX:+PauseAtStartup
option on the command line, it will stop itself as soon as all the probes are available and
before starting to execute Java code. It will also create a file in the current directory
called vm.paused.<pid_of_the_paused_vm>. You can then launch the compilation
of the D script using the dtrace program. The suspended VM will resume its execution as
soon as the file vm.paused.<pid_of_the_paused_vm> is removed. In the sample scripts provided
below, the file is removed by the scripts themselves using the
BEGIN clause, just after the compilation.
You can also start the Java RTS VM directly from a dtrace command line to avoid pausing the VM at startup.
In this case, use the -c option of dtrace to specify the command to use to launch the VM with your application.
But, as explained above, the jrts provider's probes are not immediately available when the VM starts, so you have
to use the dtrace -Z option to be able to compile your script containing probes not available yet. Those probes
will be activated when the jrts provider is initialized. Finally, your dtrace command will look like this one:
dtrace -s <your_DTrace_script> -Z -c "<vm_launch_command>"
Note that because of the usage of the -Z option, no error message will be printed for
probes still unmatched once the jrts provider is available.
[Contents]
Probes
The probes supplied by the jrts provider are presented here
in eight different sections, depending on the concept they are related to:
Time values:
The time values provided by probes monitor-wait and handler-release-* are
absolute times expressed in nanoseconds. They are based on the same time source
(the Solaris high-resolution clock) as the built-in variable timestamp provided by DTrace.
Thus, time values passed by the jrts provider are comparable with values read from the
timestamp variable.
String values:
A number of probes of the jrts provider have arguments of type char *. These arguments are not
guaranteed to be NULL-terminated arrays of char, but they are always followed by an argument that
provides the size of the array of char. To copy these arrays of char from the process address space to a DTrace
variable, use the copyinstr() function, specifying the address and the size of the array of char.
[Contents]
Probes Related to Schedulables
The schedulable probes are common to all schedulables (threads and handlers).
Their goal is to ease the analysis of the scheduling by providing
additional information about priority changes and blocking.
The monitor-related probes apply to both the Java synchronized statement
and the locks that are defined by the VM for its own critical sections.
Probes
| Probe
| Description
|
priority-change
| This probe is triggered by an explicit priority change
to an RTSJ schedulable. The sched:::change-pri probe
provided by the Solaris kernel is not sufficient
because it does not provide enough information
to make the distinction between explicit priority
changes and boosting/unboosting caused by the
priority inheritance protocol (see the two probes
below). The type of schedulable (a thread or an
instance of AsyncEventHandler) having
its priority modified is specified in args[1].
The possible values for args[1] are shown in
this table.
If the modification applies to a thread,
the thread ID is stored in args[0].
For a handler, args[0] contains the opaque ID for
this handler. The requested new priority is provided
in args[2].
|
priority-boost
| This probe fires when the priority of the thread args[0] is boosted
to the priority args[1] because of a contention on lock args[2].
Every time a thread's priority changes to a priority other than its default
user priority, this probe fires.
A thread's priority can be boosted because this thread holds a lock on a resource that a higher
priority thread needs. Furthermore, if the thread releases the lock, there could still be a
contention with a different thread for a different resource;
in this case, the thread args[0] is boosted to the priority of this
other thread requiring the lock, and this probe fires.
In summary, whenever the new priority is higher than the thread's default user priority,
the new priority is considered as boosted, and this probe is fired.
This is true even if the new priority is lower than the previous priority.
|
priority-unboost
| This probe fires when thread args[0] has its priority
changed back to its default args[1] priority after boosting.
There can be several boosts for a thread before an unboost,
if there is a change in the boosting cause.
|
monitor-contended-enter
| This probe fires when the current thread is trying to enter
a contended monitor. An opaque ID identifying the monitor is
stored in args[0]. The monitor's class name is
provided in args[1], and the name's length in
args[2].
If the monitor is not associated with a Java object,
the args[1] argument is NULL and the args[2] argument is zero.
|
monitor-contended-entered
| This probe fires when the current thread successfully enters the
contended monitor identified by args[0].
The monitor's class name is provided in args[1],
and the name's length in args[2].
If the monitor is not associated with a Java object,
the args[1] argument is NULL and the args[2] argument is zero
|
monitor-contended-exit
| This probe fires when the current thread exits the contended monitor identified
by the args[0] argument.
The monitor's class name is provided in args[1],
and the name's length in args[2].
If the monitor is not associated with a Java object,
the args[1] argument is NULL and the args[2] argument is zero.
|
monitor-wait
| This probe fires when the current thread calls wait() on the monitor identified
by args[0].
The monitor's class name is provided in args[1],
and the name's length in args[2].
If the monitor is not associated with a Java object,
the args[1] argument is NULL and the args[2] argument is zero.
The args[3] and args[4] arguments provide the high 32-bits and low 32-bits of a 64-bit
signed integer containing the wake-up time for the wait() call.
|
monitor-waited
| This probe fires when the current thread completes its call to wait() on the monitor
identified by args[0]. When this probe fires, the current thread owns the
monitor identified by args[0] and is ready to resume its execution.
The monitor's class name is provided in args[1],
and the name's length in args[2].
If the monitor is not associated with a Java object,
the args[1] is NULL and args[2] is zero.
|
monitor-notify
| This probe fires when the current thread calls notify() on the monitor
identified by args[0] and at least one thread is
waiting on this monitor.
The monitor's class name is provided in args[1],
and the name's length in args[2].
If the monitor is not associated with a Java object,
the args[1] is NULL and args[2] is zero.
|
monitor-notifyAll
| This probe fires when the current thread calls notifyAll() on the monitor
identified by args[0] and at least one thread is waiting
on this monitor.
The monitor's class name is provided in args[1],
and the name's length in args[2].
If the monitor is not associated with a Java object,
the args[1] is NULL and args[2] is zero.
|
Arguments
| Probe
| args[0]
| args[1]
| args[2]
| args[3]
| args[4]
|
priority-change
| uintptr_t
| int
| int
| -
| -
|
priority-boost
| int
| int
| uintptr_t
| -
| -
|
priority-unboost
| int
| int
| -
| -
| -
|
monitor-contended-enter
| uintptr_t
| char*
| uintptr_t
| -
| -
|
monitor-contended-entered
| uintptr_t
| char*
| uintptr_t
| -
| -
|
monitor-contended-exit
| uintptr_t
| char*
| uintptr_t
| -
| -
|
monitor-wait
| uintptr_t
| char*
| uintptr_t
| uintptr_t
| uintptr_t
|
monitor-waited
| uintptr_t
| char*
| uintptr_t
| -
| -
|
monitor-notify
| uintptr_t
| char*
| uintptr_t
| -
| -
|
monitor-notifyAll
| uintptr_t
| char*
| uintptr_t
| -
| -
|
Constants
| Value
| Schedulable type |
| 1 |
Thread |
| 2 |
Handler |
[Contents]
Probes Related to Memory
The memory probes are related to the memory areas introduced by the
Real-Time Specification for Java (RTSJ).
The goal of these probes is to help track the changes of the allocation context
of a schedulable, to monitor all the enter/exit operations
performed on a given scoped memory area, and to track immortal memory allocation.
Probes
| Probe
| Description
|
memarea-change
| This probe is triggered every time a thread changes
its current allocation context. The ID of the new allocation
context is provided in args[0]. The type of the new
allocation context is specified in args[1].
The possible values for args[1] are shown
this table.
|
memarea-enter
| This probe tracks all enters to a memory
area. The ID of the memory area being entered
is stored in args[0].The type of the new
allocation context is specified in args[1].
The possible values for args[1] are shown
this table.
|
memarea-exit
| This probe tracks all exits from a memory
area. The ID of the memory area being exited
is stored in args[0].The type of the new
allocation context is specified in args[1].
The possible values for args[1] are shown
this table.
|
scopedmem-creation
| This probe is fired when a new instance of ScopedMemoryArea
is created. An opaque ID identifying the new memory area is
stored in args[0]. The name of the class used
to create the ScopedMemoryArea instance is provided
in args[1] and the name's length in args[2].
args[3] and args[4] are the high 32-bits and
low 32-bits of a 64-bit signed integer containing the maximum size requested
by the application in the ScopedMemory constructor.
args[5] and args[6]
are the high 32-bits and low 32-bits of a 64-bit signed integer
containing the real size of the memory area allocated from the backing store
for this scoped memory area. (Depending on the implementation, this
value can be greater than the size viewed by the application.)
|
scopedmem-first-enter
| This probe tracks the first enter to a scoped memory
area. On a first enter, scopedmem-first-enter is triggered
before memarea-enter. The ID of the memory area being entered
is stored in args[0].
Because of the introduction of the "fireable" status, probe
scopedmem-first-enter() can be fired even if no code really
enters the scope.
|
scopedmem-last-exit
| This probes tracks the last exit from a scoped memory area.
The ID of the memory area being exited is stored in args[0].
The amount of bytes in use in the scope before it was cleaned is
specified in args[1].
The total memory in bytes available in the scope is specified in
args[2].
On an exit, scopedmem-last-exit is triggered after
memarea-exit.
Because of the introduction of the "fireable" status, probe
scopedmem-last-exit() can be fired
even if no code really exits the scope.
|
scopedmem-finalization
| This probe is triggered every time the VM detects that
it has to execute finalizers before clearing a scoped memory area.
The ID of the scoped memory area requiring finalization is stored
in args[0].
|
immortal-alloc
| This probe is fired when immortal memory is allocated.
The number of requested bytes is stored in args[0].
The number of bytes used in immortal memory after completion
of the request is stored in args[1].
The address of the allocated object is available in args[2].
The address values is NULL if the allocation failed.
Note: This probe is reliable only if the command line option
-XX:+RTSJEnableImmortalAllocationProbe is set. If it is not set,
most of the allocations are optimized by the VM and will not
fire the probe. This option is (currently) activated by default.
This may lead to throughput loss during the startup phase.
|
Arguments
| Probe
| args[0]
| args[1]
| args[2]
| args[3]
| args[4]
| args[5]
| args[6]
|
memarea-change
| uintptr_t
| int
| -
| -
| -
| -
| -
|
memarea-enter
| uintptr_t
| int
| -
| -
| -
| -
| -
|
memarea-exit
| uintptr_t
| int
| -
| -
| -
| -
| -
|
scopedmem-creation
| uintptr_t
| char*
| int
| unsigned long
| unsigned long
| unsigned long
| unsigned long
|
scopedmem-first-enter
| uintptr_t
| -
| -
| -
| -
| -
| -
|
scopedmem-last-exit
| uintptr_t
| uintptr_t
| uintptr_t
| -
| -
| -
| -
|
scopedmem-finalization
| uintptr_t
| -
| -
| -
| -
| -
| -
|
immortal-alloc
| uintptr_t
| uintptr_t
| uintptr_t
| -
| -
| -
| -
|
Constants
| Value
| Memory Area Type |
| 1 |
Heap Memory |
| 2 |
Immortal Memory |
| 3 |
Scoped Memory |
[Contents]
Probes Related to Threads
The thread-related probes concern Thread, RealtimeThread,
and NoHeapRealtimeThread instances.
Going further than thread start and end, they provide information about
periodic execution and interruption (Asynchronous Transfer of Control, or ATC).
Probes
| Probe
| Description
|
thread-period-change
| This probe is triggered when a thread's period is modified
(not when this change takes effect). The thread's ID is
stored in args[0]. args[1] and
args[2] are the high 32-bits and low
32-bits of a 64-bit signed integer containing the value of the new
period. This probe also fires when the thread's release policy is
changed from periodic to aperiodic. In this case, args[1] and
args[2] are equal to zero.
|
thread-deschedule-periodic
| This probe fires when deschedulePeriodic() is performed on the thread
identified by args[0]. If the deschedulePeriodic()
method is invoked on a non-periodic thread or thread not alive, the
method has no effect and the probe doesn't fire.
|
thread-schedule-periodic
| This probe fires when schedulePeriodic() is performed on the thread
identified by args[0]. If the schedulePeriodic()
method is invoked on a non-periodic thread or thread that is not alive, the
method has no effect and the probe does not fire.
|
thread-aie-fired
| This probe fires when an Asynchronously Interrupted Exception
is generated. The ID of thread which will receive the AIE
is stored in args[0]. If the thread is not alive
then args[0] will be zero.
|
thread-aie-delivered
| This probe fires when a pending Asynchronously Interrupted
Exception is being propagated because the current thread is executing
AI-enabled code with an AIE pending.
|
thread-aie-cleared
| This probe fires when an Asynchronously Interrupted Exception
is cleared by the current thread.
|
thread-start
| This probe fires when the start() method is invoked on a thread.
The ID of the thread being started is available in args[0].
The type of the thread is specified in args[1].
The possible values for the args[1]
are shown this table.
The thread's class name is provided in args[2],
and the class name's length in args[3].
The thread's name is provided in args[4],
and the name's length in args[5].
|
thread-begin
| A Java thread fires this probe just before starting the execution
of its run() method. A native thread fires this probe at
the end of a successful call to the JNI method AttachCurrentThread().
A native thread creating a VM will also fire this probe at the end of
the JNI method JNI_CreateJavaVM().
|
thread-end
| A thread fires this probe after the completion of its run() method and,
if it had an uncaught exception, the completion of the uncaughtException
method of its UncaughtExceptionHandler.
A native thread fires this probe when it calls the JNI method DetachCurrentThread().
|
thread-set-name
| This probes fires when the current thread sets the name of the thread
identified by args[0]. The new name is available in
args[1] and its length in args[2].
If the renamed thread is not alive, args[0] is zero.
This probe also fires when a thread creates a system thread, that is, a thread dedicated to
the internal work of the VM and not part of the application. Each system thread has
a different name and can be easily identified through this probe.
Server threads are created by the VM to execute released handlers.
Every time a new server thread is created, the thread-set-name probe is fired.
Handlers that are instances of BoundAsyncEventHandler are
called bound handlers, while handlers that are instances of AsyncEventHandler
but not instances of BoundAsyncEventHandler are
called not-bound handlers.
For server threads associated with bound handlers, the name provided by the probe
is the same as the name returned to the handler
itself when it invokes Thread.currentThread().getName(). This name is built
from the type of the handler and a counter incremented at each creation of
a new handler.
For server threads dedicated to the execution of not-bound handlers,
the name provided by the probe depends only on the type of the thread, so all
server threads with the same type will have the same name.
However, it is possible to configure the VM to fire the thread-set-name
probe every time a server thread binds or unbinds itself to a not-bound handler.
In this case, when the thread-set-name probe is fired during the binding process,
the name provided by the probe is the same as the name returned to the handler
itself when it invokes Thread.currentThread().getName() (as in the creation
of server threads associated with bound handlers). And when the thread-set-name is fired during
the unbinding process, the name provided by the probe is the initial name of the thread.
By default, the thread-set-name probe is disabled during the binding and
unbinding of server threads associated with not-bound handlers.
This is because the cost associated with the preparation
of arguments for the probe is in the critical path of the handler's execution code.
To activate the firing of the thread-set-name probe during the binding and
unbinding process, the VM option
-XX:+RTSJEnableServerThreadNamingProbe must be specified on the command line at
startup time.
|
thread-wfnp-enter
| This probe is fired by a thread invoking the waitForNextPeriod() or
waitForNextPeriodInterruptible() method.
If waitForNextPeriod() is invoked args[0] is false,
otherwise it is true.
|
thread-wfnp-exit
| This probe is fired by a thread when it returns from a waitForNextPeriod()
call. The value returned by the waitForNextPeriod() method
is available in args[0].
|
thread-deadline-miss
| This probe fires when a thread's deadline miss causes the release
of its deadline miss handler. The ID of the handler to be released
is available in args[0]
thread-sleep-begin
| A thread fires this probe at the beginning of the Thread.sleep() and
RealtimeThread.sleep() methods, before going to sleep.
|
thread-sleep-end
| A thread fires this probe at the end of the Thread.sleep() and
RealtimeThread.sleep() methods, after the completion of the sleep.
|
thread-yield
| A thread fires this probe when it performs a call to Thread.yield().
|
|
Arguments
| Probe
| args[0]
| args[1]
| args[2]
| args[3]
| args[4]
| args[5]
|
thread-period-change
| int
| unsigned long
| unsigned long
| -
| -
| -
|
thread-deschedule-periodic
| int
| -
| -
| -
| -
| -
|
thread-schedule-periodic
| int
| -
| -
| -
| -
| -
|
thread-aie-fired
| int
| -
| -
| -
| -
| -
|
thread-aie-delivered
| -
| -
| -
| -
| -
| -
|
thread-aie-cleared
| -
| -
| -
| -
| -
| -
|
thread-start
| int
| int
| char*
| int
| char*
| int
|
thread-begin
| -
| -
| -
| -
| -
| -
|
thread-end
| -
| -
| -
| -
| -
| -
|
thread-set-name
| int
| char*
| int
| -
| -
| -
|
thread-wfnp-enter
| int
| -
| -
| -
| -
| -
|
thread-wfnp-exit
| int
| -
| -
| -
| -
| -
|
thread-deadline-miss
| uintptr_t
| -
| -
| -
| -
| -
|
thread-sleep-begin
| -
| -
| -
| -
| -
| -
|
thread-sleep-end
| -
| -
| -
| -
| -
| -
|
thread-yield
| -
| -
| -
| -
| -
| -
|
Constants
| Value
| Thread Type |
| -1 |
java.lang.Thread |
| 1 |
javax.realtime.RealtimeThread |
| 0 |
javax.realtime.NoHeapRealtimeThread |
[Contents]
Probes Related to Handlers
The handler probes are related to instances of AsyncEventHandler.
These probes aim to expose all the steps
from the event's firing to the execution of the application's logic:
firing, release policy, binding, and so forth.
They also allow tracking of the creation and destruction of server threads
in order to help the developer in sizing the server pools.
Handlers that are instances of BoundAsyncEventHandler are
called bound handlers, while handlers that are instances of AsyncEventHandler
but not instances of BoundAsyncEventHandler are
called not-bound handlers.
Probes
| Probe
| Description
|
event-fire
| This probe fires when the event identified by the
args[0] is fired.
|
handler-creation
| This probe fires after the creation of an AsyncEventHandler instance to
provide useful information about this handler.
An opaque ID for this handler is provided in args[0].
The class name of the handler is available in args[1],
and the class name's length in args[2].
If the handler is allowed to access the heap, args[3]
is false, otherwise it is true.
|
handler-destruction
| This probe fires just before the handler identified in args[0] is
collected. At this point, the handler can no longer be released or executed.
|
handler-release-accepted
| This probe fires when the release of a handler has been accepted. This release
could have been caused by the firing of an event, a timer, or a
deadline miss. The ID of the handler being released is specified in args[0].
args[1] and args[2] are the high 32-bits and low 32-bits
of a 64-bit signed integer containing the time when the release request occurred,
while args[3] and args[4] are the
high 32-bits and low 32-bits of a 64-bit signed integer containing the time the handler will
actually be released. The real release time and the
effective release time are different when the release of the handler has been delayed
because of a Minimum Interarrival Time policy enforcement. In the other cases,
the values are equal.
|
handler-release-replace
| This probe fires when the release of a handler will
replace a previously accepted release in the pending release queue. This release
could have been caused by the firing of an event, a timer, or a
deadline miss. The ID of the handler being released is specified in args[0].
args[1] and args[2] are the high 32-bits and low 32-bits
of a 64-bit signed integer containing the time when the release request occurred,
while args[3] and args[4] are the
high 32-bits and low 32-bits of a 64-bit signed integer containing the time the handler will
actually be released. The real release time and the
effective release time are different when the release of the handler has been delayed
because of a Minimum Interarrival Time policy enforcement. In other cases,
the values are equal.
|
handler-release-rejected
| This probe fires when the release of a handler has been refused.
The ID of the handler being rejected is specified in args[0].
args[1] and args[2]
are the high 32-bits and low 32-bits of a 64-bit signed integer containing
the time of the release being rejected.
The release policy being considered for this release is specified in
args[3]. The possible values for args[3]
are shown this table.
|
handler-release-ignored
| This probe fires when the release of a handler has been ignored.
The ID of the handler being ignored is specified in args[0].
args[1] and args[2]
are the high 32-bits and low 32-bits of a 64-bit signed integer containing
the time of the release being ignored.
The release policy being considered for this release is specified in
args[3]. The possible values for args[3]
are shown this table.
|
server-thread-binding
| This probe fires when a server thread is bound to the handler identified
by args[1]. The thread ID of the server thread being bound
is available in args[0].
Server threads executing a bound handler fire this probe only once,
that is, when the handler is created.
|
server-thread-unbinding
| This probe fires when a server thread (the current thread) unbinds itself from the handler identified
by args[0]. Server threads executing a bound handler fire this probe only once,
that is, when the handler is destroyed.
|
server-thread-creation
| This probe fires when a new server thread is created. The thread ID of
the server thread that has been created is available in args[0].
If the server thread is an instance of NoHeapRealtimeThread,
args[1] is true, otherwise it is false.
This probe does not fire if the thread is intended to be associated with a bound handler.
|
server-thread-destruction
| This probe fires when a server thread (the current thread) is destroyed.
If the server thread is an instance of NoHeapRealtimeThread,
args[0] is true, otherwise it is false.
This probe does not fire if the thread is intended to be associated with a bound handler.
|
server-thread-wakeup
| This probe fires when the current thread wakes up the server thread with the
thread ID args[0].
The priority at which this server thread has been awakened is specified
in args[1]. If the server thread is a bound server thread,
args[1] is zero.
|
handler-start
| This probe fires when a server thread starts the execution of the main loop of the
handler logic (not the handleAsyncEvent() method, but an outer loop that tracks
the fire count and any needed delay due to MIT violation). The handler ID is available
in args[0].
|
handler-end
| This probe fires when a server thread ends the execution of the main loop of the
handler logic (not the handleAsyncEvent() method, but an outer loop that tracks
the fire count and any needed delay due to MIT violation). The handler ID is available
in args[0].
|
handler-deadline-miss
| This probe fires when a handler's deadline miss causes the release
of its deadline miss handler. The handler ID of the handler to be released
is specified in args[0].
|
Arguments
| Probe
| args[0]
| args[1]
| args[2]
| args[3]
| args[4]
|
event-fire
| uintptr_t
| -
| -
| -
| -
|
handler-creation
| uintptr_t
| char*
| int
| int
| -
|
handler-destruction
| uintptr_t
| -
| -
| -
| -
|
handler-release-accepted
| uintptr_t
| unsigned long
| unsigned long
| unsigned long
| unsigned long
|
handler-release-replace
| uintptr_t
| unsigned long
| unsigned long
| unsigned long
| unsigned long
|
handler-release-rejected
| uintptr_t
| unsigned long
| unsigned long
| int
| -
|
handler-release-ignored
| uintptr_t
| unsigned long
| unsigned long
| int
| -
|
server-thread-binding
| int
| uintptr_t
| -
| -
| -
|
server-thread-unbinding
| uintptr_t
| -
| -
| -
| -
|
server-thread-creation
| int
| int
| -
| -
| -
|
server-thread-destruction
| int
| -
| -
| -
| -
|
server-thread-wakeup
| int
| int
| -
| -
| -
|
handler-start
| uintptr_t
| -
| -
| -
| -
|
handler-end
| uintptr_t
| -
| -
| -
| -
|
handler-deadline-miss
| uintptr_t
| -
| -
| -
| -
|
Constants
| Value |
Release policy |
| 1 |
Minimum interarrival time violation with ignore policy |
| 2 |
Minimum interarrival time violation with except policy |
| 3 |
Minimum interarrival time violation with replace policy |
| 4 |
Minimum interarrival time violation with save policy |
| 5 |
Arrival queue overflow with ignore policy |
| 6 |
Arrival queue overflow with except policy |
| 7 |
Arrival queue overflow with replace policy |
| 8 |
Arrival queue overflow with save policy |
[Contents]
Probes Related to Compilation
The compilation probes help the developer to track when compilations occur
for a given class, method, or type of thread. They also provide information
about the patching of code due to late resolution of symbols.
See the Java RTS Compilation Guide for
detailed information about using the various compilation modes to achieve determinism.
Probes
| Probe
| Description
|
method-compile-begin
| This probe is triggered when the compilation of a method starts.
args[0] and args[1] provide the class
name and the class name's length.
args[2] and args[3] provide the method
name and the method name's length.
args[4] and args[5] provide the signature
and the signature's length. args[6] indicates
for which thread type this method will be compiled
|
method-compile-end
| This probe is triggered when the compilation of a method ends.
args[0] and args[1] provide the class
name and the class name's length.
args[2] and args[3] provide the method
name and the method name's length.
args[4] and args[5] provide the signature
and the signature's length. args[6] is true if the
compilation was successful, it is false otherwise. args[7] indicates
for which thread type this method was compiled.
|
compiler-patching-klass
|
This probe is triggered on runtime resolution of a class reference in compiled
code.
args[0] and args[1] provide the class
name and the class name's length in which the symbol is unresolved.
args[2] and args[3] provide the method
name and the method name's length in which the symbol is unresolved.
args[4] and args[5] provide the signature
and the signature's length in which the symbol is unresolved.
args[6] provides the bytecode index where the symbol is
unresolved in the method.
args[7] and args[8] provide the
name and the name's length of the resolved class.
args[9] is the type of the thread that triggered the resolution.
|
compiler-patching-tablecall
| This probe is triggered on runtime resolution of a virtual/interface method
call in compiled code.
args[0] and args[1] provide the class
name and the class name's length in which the symbol is unresolved.
args[2] and args[3] provide the method
name and the method name's length in which the symbol is unresolved.
args[4] and args[5] provide the signature
and the signature's length in which the symbol is unresolved.
args[6] provides the bytecode index where the symbol is
unresolved in the method.
args[7] and args[8] provide the class
name and the class name's length of the resolved method.
args[9] and args[10] provide the method
name and the method name's length of the resolved method.
args[11] and args[12] provide the signature
and the signature's length of the resolved method.
args[13] is the type of the thread
that triggered the resolution.
|
compiler-patching-directcall
| This probe is triggered on runtime resolution of a direct method
call in compiled code.
args[0] and args[1] provide the class
name and the class name's length in which the symbol is unresolved.
args[2] and args[3] provide the method
name and the method name's length in which the symbol is unresolved.
args[4] and args[5] provide the signature
and the signature's length in which the symbol is unresolved.
args[6] provides the bytecode index where the symbol is
unresolved in the method.
args[7] and args[8] provide the class
name and the class name's length of the resolved method.
args[9] and args[10] provide the method
name and the method name's length of the resolved method.
args[11] and args[12] provide the signature
and the signature's length of the resolved method.
args[13] is the type of the thread
that triggered the resolution.
|
Arguments
| Probe
| args[0]
| args[1]
| args[2]
| args[3]
| args[4]
| args[5]
| args[6]
| args[7]
| args[8]
| args[9]
| args[10]
| args[11]
| args[12]
| args[13]
|
method-compile-begin
| char*
| int
| char*
| int
| char*
| int
| int
| -
| -
| -
| -
| -
| -
| -
|
method-compile-end
| char*
| int
| char*
| int
| char*
| int
| int
| int
| -
| -
| -
| -
| -
| -
|
compiler-patching-klass
| char*
| int
| char*
| int
| char*
| int
| int
| char*
| int
| int
| -
| -
| -
| -
|
compiler-patching-tablecall
| char*
| int
| char*
| int
| char*
| int
| int
| char*
| int
| char*
| int
| char*
| int
| int
|
compiler-patching-directcall
| char*
| int
| char*
| int
| char*
| int
| int
| char*
| int
| char*
| int
| char*
| int
| int
|
[Contents]
Probes Related to the RTGC
The RTGC probes are related to the activities of the Real-Time Garbage Collector and its
worker threads.
Probes
| Probe
| Description
|
rtgc-cycle-begin
| This probe fires when the RTGC starts a collection cycle.
|
rtgc-cycle-end
| This probe fires when the RTGC ends a collection cycle.
|
rtgc-change-priority
| This probe fires when the RTGC changes its priority.
The new priority is provided in args[0].
|
rtgc-worker-thread-start
| A RTGC worker thread fires this probe when it starts executing
job args[0] for the RTGC.
For the current GC cycle, the thread executing job 0 is called the Pacing Thread and
the thread executing job 1 is called the Coordinator Thread.
These two threads are used by the RTGC for internal purposes
but are not part of the set of worker threads configured by the RTGCNormalWorkers
and RTGCBoostedWorkers options.
|
rtgc-worker-thread-stop
| A RTGC worker thread fires this probe when it completes the execution of
job args[0] for the RTGC.
For the current GC cycle, the thread executing job 0 is called the Pacing Thread and
the thread executing job 1 is called the Coordinator Thread.
These two threads are used by the RTGC for internal purposes
but are not part of the set of worker threads configured by the RTGCNormalWorkers
and RTGCBoostedWorkers options.
|
rtgc-policy-stats
| This probe fires at the end of each RTGC cycle and provides a number of counters related
to the memory status during this cycle and the parameters the RTGC will use for its next cycle.
args[0] provides the RTGC priority. args[1] provides the
end_free_size counter. args[2] provides the
min_remaining_memory counter. args[3] provides the
mode_margin counter. args[4] provides the
critical_limit counter. args[5] provides the
normal_limit counter. args[6] provides the
RTGCCriticalReservedBytes counter.
|
rtgc-alloc-stats
| This probe fires at the end of each RTGC cycle and provides a detailed status of allocations
that occurred during this cycle. The status is provided through an user structure pointed by
args[0] with its size specified in args[1].
This structure is not stable and may differ between releases of Java RTS. The structure
implemented in Java RTS 2.1 is the following one:
struct rtgc_alloc_stats {
// allocations by all threads in normal mode since VM startup:
size_t normal_total; // total for all GC runs
size_t normal_worst; // worst GC run
size_t normal_average; // average for all the GC runs
// allocations by all threads in boosted mode since VM startup:
size_t boosted_total; // total for all GC runs
size_t boosted_worst; // worst GC run
size_t boosted_average; // average for all the GC runs
// allocations by critical threads during this GC run:
size_t critical_threads_cycle; // total in all modes
size_t critical_threads_in_deterministic;
// in deterministic mode only
// long-term stats for RTGCCriticalReservedBytes:
size_t critical_threads_worst;
// worst case in deterministic mode since VM startup
size_t reserved_field; // reserved for future use
size_t critical_threads_total;
// total allocations for critical threads
};
|
rtheap-tlab-alloc
| This probe fires every time a thread gets a new TLAB in the real-time heap.
The size of the allocated TLAB is provided in args[0].
|
rtheap-mem-alloc
| This probe fires every time a thread successfully allocates memory in the real-time
heap without using the TLAB mechanism. The amount of memory allocated is
provided in args[0].
|
rtheap-mem-alloc-failure
| This probe fires every time a thread fails while trying to allocate
memory in the real-time heap without using the TLAB mechanism. The amount
of memory the thread tried to allocate is provided in args[0].
|
rtheap-split-alloc
| This probe fires every time a thread successfully allocates memory for a split object
in the real-time heap without using the TLAB mechanism. The amount
of memory allocated is specified in args[0]. An opaque identifier of the split object
being allocated is provided in args[1]. Because split objects are allocated in several pieces, this probes fires
several times for the same object.
|
rtheap-split-alloc-failure
| This probe fires every time a thread fails while trying to allocate
memory for a split object in the real-time heap without using the TLAB mechanism.
The amount of memory the thread tried to allocate is specified in args[0].
An opaque identifier of the split object being allocated is provided in args[1]. When
such a failure occurs, all the previously allocated memory for this split object is
freed.
|
rtheap-total-alloc-quantum1
| This probe fires every time the total amount of memory allocated in the real-time heap reaches
a value which is a multiple of quantum1. The value of quantum1 is
set to 128KB. The current total amount of memory allocated in the real-time heap is
provided in args[0].
|
rtheap-total-alloc-quantum2
| This probe fires every time the total amount of memory allocated in the real-time heap reaches
a value which is a multiple of quantum2. The value of quantum2 is
set to 1MB. The current total amount of memory allocated in the real-time heap is
provided in args[0].
|
rtheap-important-alloc-quantum1
| This probe fires every time the total amount of memory allocated in the real-time heap
by important threads reaches a value which is a multiple of quantum1.
The value of quantum1 is set to 128KB. The current total amount of memory
allocated in the real-time heap by important threads is provided in args[0].
|
rtheap-important-alloc-quantum2
| This probe fires every time the total amount of memory allocated in the real-time heap
by important threads reaches a value which is a multiple of quantum2.
The value of quantum2 is set to 1MB. The current total amount of memory
allocated in the real-time heap by important threads is provided in args[0].
|
rtheap-critical-alloc-quantum1
| This probe fires every time the total amount of memory allocated in the real-time heap
by critical threads reaches a value which is a multiple of quantum1.
The value of quantum1 is set to 128KB. The current total amount of memory
allocated in the real-time heap by critical threads is provided in args[0].
|
rtheap-critical-alloc-quantum2
| This probe fires every time the total amount of memory allocated in the real-time heap
by critical threads reaches a value which is a multiple of quantum2.
The value of quantum2 is set to 1MB. The current total amount of memory
allocated in the real-time heap by critical threads is provided in args[0].
|
Arguments
| Probe
| args[0]
| args[1]
| args[2]
| args[3]
| args[4]
| args[5]
| args[6]
|
rtgc-cycle-begin
| -
| -
| -
| -
| -
| -
| -
|
rtgc-cycle-end
| -
| -
| -
| -
| -
| -
| -
|
rtgc-change-priority
| int
| -
| -
| -
| -
| -
| -
|
rtgc-worker-thread-start
| int
| -
| -
| -
| -
| -
| -
|
rtgc-worker-thread-stop
| int
| -
| -
| -
| -
| -
| -
|
rtgc-policy-stats
| int
| uintptr_t
| uintptr_t
| uintptr_t
| uintptr_t
| uintptr_t
| uintptr_t
|
rtgc-alloc-stats
| uintptr_t
| uintptr_t
| -
| -
| -
| -
| -
|
rtheap-tlab-alloc
| uintptr_t
| -
| -
| -
| -
| -
| -
|
rtheap-mem-alloc
| uintptr_t
| -
| -
| -
| -
| -
| -
|
rtheap-mem-alloc-failure
| uintptr_t
| -
| -
| -
| -
| -
| -
|
rtheap-split-alloc
| uintptr_t
| uintptr_t
| -
| -
| -
| -
| -
|
rtheap-split-alloc-failure
| uintptr_t
| uintptr_t
| -
| -
| -
| -
| -
|
rtheap-total-alloc-quantum1
| uintptr_t
| -
| -
| -
| -
| -
| -
|
rtheap-total-alloc-quantum2
| uintptr_t
| -
| -
| -
| -
| -
| -
|
rtheap-important-alloc-quantum1
| uintptr_t
| -
| -
| -
| -
| -
| -
|
rtheap-important-alloc-quantum2
| uintptr_t
| -
| -
| -
| -
| -
| -
|
rtheap-critical-alloc-quantum1
| uintptr_t
| -
| -
| -
| -
| -
| -
|
rtheap-critical-alloc-quantum2
| uintptr_t
| -
| -
| -
| -
| -
| -
|
[Contents]
Probes Related to Classes
The class-related probes aim to expose when classes are loaded and the threads that
perform those loads. They also provide information about when those
classes are initialized, and the type of the thread executing the initialization code.
The probes related to class initialization are defined according to the
steps described in section 2.17.5 "Detailed Initialization Procedure" of the
The Java™ Virtual Machine Specification book, second edition.
Probes
| Probe
| Description
|
class-loaded
| This probe fires when a thread loads a new class. args[0] gives the name of
the class being loaded and args[1] the class name's length.
args[2] is an opaque ID for the class loader
used to load the class. args[4] is the type of the thread
performing the class loading. args[3] is currently not used.
|
class-initialization-required
| This probe fires when a class is required to be initialized and the current thread proceeds to
initiate that initialization. It is placed before step 1 of the initialization process.
args[0] gives the name of the class being initialized and args[1] the class name's length.
args[2] is an opaque ID for the class loader used to load the class.
args[3] is the type of the current thread.
|
class-initialization-recursive
| This probe fires when a thread that needs to initialize a class discovers that it is already in
the process of initializing that class. It corresponds to step 3 of the initialization process.
args[0] gives the name of the class being initialized and args[1] the class name's length.
args[2] is an opaque ID for the class loader used to load the class.
args[3] is the type of the current thread.
args[4] is always false.
|
class-initialization-concurrent
| This probe fires when the current thread discovers that another thread concurrently completed
the initialization of the given class. It corresponds to step 4 of the initialization process.
args[0] gives the name of the class being initialized and args[1] the class name's length.
args[2] is an opaque ID for the class loader used to load the class.
args[3] is the type of the current thread.
args[4] is true if the thread had to wait at the beginning of the initialization process.
|
class-initialization-erroneous
| This probe fires when the current thread discovers that the given class has already been
marked as being in the "erroneous" state and cannot be initialized. It corresponds to step 5
of the initialization process.
args[0] gives the name of the class being initialized and args[1] the class name's length.
args[2] is an opaque ID for the class loader used to load the class.
args[3] is the type of the current thread.
args[4] is true if the thread had to wait at the beginning of the initialization process.
|
class-initialization-super-failed
| This probe fires when the current thread encounters an error trying to initialize the
superclass of the given class. It corresponds to step 7 of the initialization process.
Of course the initialization attempt for the superclass
would have its own probe firings with more information.
args[0] gives the name of the class being initialized and args[1] the class name's length.
args[2] is an opaque ID for the class loader used to load the class.
args[3] is the type of the current thread.
args[4] is true if the thread had to wait at the beginning of the initialization process.
|
class-initialization-clinit
| This probe fires when the current thread commences execution of the <clinit> method of the
given class. It corresponds to step 8 of the initialization process.
args[0] gives the name of the class being initialized and args[1] the class name's length.
args[2] is an opaque ID for the class loader used to load the class.
args[3] is the type of the current thread.
args[4] is true if the thread had to wait at the beginning of the initialization process.
|
class-initialization-error
| This probe fires when the execution of <clinit> results in an exception being thrown
(in response to which the class is marked as being in the "erroneous" state). It corresponds to
steps 10 and 11 of the initialization process.
args[0] gives the name of the class being initialized and args[1] the class name's length.
args[2] is an opaque ID for the class loader used to load the class.
args[3] is the type of the current thread.
args[4] is true if the thread had to wait at the beginning of the initialization process.
|
class-initialization-end
| This probe fires after successful execution of the <clinit> method and the class has
been marked as initialized. It corresponds to step 9 of the initialization process.
args[0] gives the name of the class being initialized and args[1] the class name's length.
args[2] is an opaque ID for the class loader used to load the class.
args[3] is the type of the current thread.
args[4] is true if the thread had to wait at the beginning of the initialization process.
|
Arguments
| Probe
| args[0]
| args[1]
| args[2]
| args[3]
| args[4]
|
class-loaded
| char*
| uintptr_t
| void*
| uintptr_t
| intptr_t
|
class-initialization-required
| char*
| uintptr_t
| void*
| intptr_t
| -
|
class-initialization-recursive
| char*
| uintptr_t
| void*
| intptr_t
| int
|
class-initialization-concurrent
| char*
| uintptr_t
| void*
| intptr_t
| int
|
class-initialization-erroneous
| char*
| uintptr_t
| void*
| intptr_t
| int
|
class-initialization-super-failed
| char*
| uintptr_t
| void*
| intptr_t
| int
|
class-initialization-clinit
| char*
| uintptr_t
| void*
| intptr_t
| int
|
class-initialization-error
| char*
| uintptr_t
| void*
| intptr_t
| int
|
class-initialization-end
| char*
| uintptr_t
| void*
| intptr_t
| int
|
[Contents]
Probes Related to the VM
The VM-related probes aim to expose events that might impact all the activities within
the virtual machine.
Probes
| Probe
| Description
|
safepoint-begin
| This probe fires at the beginning of a global safepoint performed by the VM.
|
safepoint-end
| This probe fires at the end of a global safepoint performed by the VM.
|
vm-operation-request
| This probe fires when a VM operation is added to the list of requested VM operations.
args[0] gives the name of the VM operation being added,
and args[1] provides the length of this name. args[2]
describes the execution mode of this VM operation. The possible values for
args[2] are shown in this table.
args[3] is true if this VM operation is to be executed before non-urgent
pending VM operations. In case of a nested VM operation, this probe is not fired.
|
vm-operation-begin
| This probe fires at the beginning of the execution of a VM operation by the VM thread.
args[0] gives the name of the VM operation being executed,
and args[1] provides the length of this name. args[2]
describes the execution mode of this VM operation. The possible values for
args[2] are shown in this table.
args[3] is true if this VM operation is to be executed before non-urgent
pending VM operations.
|
vm-operation-end
| This probe fires when the VM Thread completes the execution of a VM operation.
args[0] gives the name of the VM operation that has been executed,
and args[1] provides the length of this name. args[2]
describes the execution mode of this VM operation. The possible values for
args[2] are shown in this table.
args[3] is true if this VM operation was executed before non-urgent
pending VM operations.
|
vm-creation-begin
| This probe fires at the beginning of the Java Virtual Machine loading and initialization.
|
vm-creation-end
| This probe fires when the loading and the initialization of the Java Virtual Machine have
successfuly completed.
|
Arguments
| Probe
| args[0]
| args[1]
| args[2]
| args[3]
|
safepoint-begin
| -
| -
| -
| -
|
safepoint-end
| -
| -
| -
| -
|
vm-operation-request
| char*
| int
| int
| int
|
vm-operation-begin
| char*
| int
| int
| int
|
vm-operation-end
| char*
| int
| int
| int
|
vm-creation-begin
| -
| -
| -
| -
|
vm-creation-end
| -
| -
| -
| -
|
Constants
| Value |
Mode name |
Requesting thread |
VMOperation under safepoint |
| 0 |
safepoint |
blocked |
yes |
| 1 |
no_safepoint |
blocked |
no |
| 2 |
concurrent |
not blocked |
no |
| 3 |
async_safepoint |
not blocked |
yes |
[Contents]
Probes Related to the Application
Using the com.sun.rtsjx.DTraceUserEvent class, the application has the ability
to generate its own events visible from a DTrace script. This class always fires the
user-event probe, but it is possible to use a string to differentiate the events.
Probes
| Probe
| Description
|
user-event
| This probe fires when the method com.sun.rtsjx.DTraceUserEvent.fire(String msg) is invoked.
args[0] gives the string passed in argument to the fire() method and
args[1] provides the length of this string.
|
Arguments
| Probe
| args[0]
| args[1]
|
user-event
| char*
| int
|
[Contents]
Supported Platforms
The jrts DTrace probe provider is available only on Solaris 10 platforms (SPARC and x86).
[Contents]
Sample Scripts
Here are some sample scripts showing how to use the probes described above.
[Contents]
Contact Us
Please report any problems or bugs you might encounter to the
Java RTS team.
[Contents]
Copyright © 2008 Sun Microsystems, Inc. All Rights Reserved.
|
|
