Diagnostics Guide

     Previous  Next    Open TOC in new window  Open Index in new window  View as PDF - New Window  Get Adobe Reader - New Window
Content starts here

Running Diagnostic Commands

Use diagnostic commands to communicate with a running Oracle JRockit JVM process. These commands tell the JRockit JVM to for example print a heap report or a garbage collection activity report, or to turn on or off a specific verbose module. This chapter describes how to run diagnostic commands and lists the available commands. The following sections are included:

 

Diagnostic Commands Overview

Diagnostic commands help you communicate with a running JRockit JVM process. With these commands you can for example ask for a heap report or enable or disable a verbose module.

You can send diagnostic commands to a running JVM process in several ways:

You can enable or disable any diagnostic command using the system property -Djrockit.ctrlbreak.enable<name>=<true|false>, where name is the name of the diagnostic command. The following two handlers are disallowed by default and need to be turned on:

For example:

-Djrockit.ctrlbreak.enablerun_class=true

 

Using jrcmd

jrcmd is a command line tool included with the JRockit JDK you can use to send diagnostic commands to a running JVM process. This section provides a brief overview of jrcmd. It includes information on the following subjects:

How jrcmd Communicates with the JRockit JVM

jrcmd uses the JRIPC library, a small C library, to communicate with a running JRockit JVM process. JRIPC has the following basic functionality

How to Use jrcmd

To use jrcmd, simply enter it at the command line, with the appropriate parameters: 

jrcmd <jrockit pid> [<command> [<arguments>]] [-l] [-f file] [-p] -h]

where:

If the PID is 0, commands will be sent to all JRockit JVM processes. If no options are given, default is -p.

jrcmd Examples

Here are some examples of using jrcmd for:

Listing JRockit JVM Processes

Do the following to list all JRockit JVM processes running on the machine:

  1. Run jrcmd or jrcmd -p to list the running JRockit JVMs; for example:
    2. > jrcmd -P
    10064 Sleeper
            -Xverbose:memory -Xmx30m
    >

    You will see the PID of the process (10064) and the program it is currently running (Sleeper) as well as the parameters used to start the JVM (-Xverbose:memory -Xmx30m).

Sending a Command to a Process

To send a command to the process you identified in Listing JRockit JVM Processes, do the following:

  1. Find the PID from Listing JRockit JVM Processes (10064)
  2. Enter jrcmd with that PID and the version command; for example:
    3. > jrcmd 10064 version

    This command sends the version command to the JRockit JVM. The response will be: 

    Oracle WebLogic JRockit(R) Virtual Machine build 9.9.9-1.5.0-Jun 9 2004-13:52:53-<internal>, Native Threads, GC strategy: parallel

Sending Several Commands

You can create a file (just like the ctrlhandler.act file) with several commands and execute all of them. Use this procedure:

  1. Create a file called commands.txt with the following contents:
    • version
    • timestamp
  2. Execute the file with jrcmd; for example:
    3. > jrcmd 10064 -f commands.txt

    The system will respond: 

    Oracle WebLogic JRockit(R) Virtual Machine build 9.9.9-1.5.0-Jun  9 2004-13:52:53-<internal>, Native Threads, GC strategy: parallel
    ==== Timestamp ====  uptime: 0 days, 00:05:04 time: Fri Jun 11 14:28:31 2004
  3. Use the PID 0 to send the commands to all running JRockit JVM processes.

Known Limitations of jrcmd

When using jrcmd, be aware of these limitations:

 

Ctrl-Break Handler

Another way you can run diagnostic commands is by pressing Ctrl-Break. When you press Ctrl-Break, the JRockit JVM will search for a file named ctrlhandler.act (see Listing 21-1) in your current working directory. If it doesn't find the file there, it will look in the directory containing the JVM. If it does not find this file there either, it will revert to displaying the normal thread dump. If it finds the file, it will read the file searching for command entries, each of which invoke the corresponding diagnostic command.

Listing 21-1 ctrlhandler.act File 
set_filename filename=c:\output.txt append=true
print_class_summary
print_object_summary increaseonly=true
print_threads
print_threads nativestack=true
print_utf8pool
jrarecording filename=c:\myjra.xml time=120 nativesamples=true
verbosity set=memory,memdbg,codegen,opt,sampling filename="c:\output"
timestamp

stop
# ctrl-break-handler will stop reading the file after it finds
# the stop key-word
#
# version - print JRockit version
#
# print_threads - the normal thread dump that lists all the currently
# running threads and there state
#
# print_class_summary - prints a tree of the currently loaded classes
#
# print_utf8pool - print the internal utf8 pool
#
# print_object_summary - display info about how many objects of each
# type that are live currently and how much size
# they use. Also displays points to information
#
# jvmpi_datadump
#
# jvmpi_datareset
#
# jrarecording - starts a jrarecording
#
# verbosity - changes the verbosity level , not functional in ariane142_04
#
# start_management_server - starts a management server
# kill_management_server - shuts the management server down
#   (the managementserver.jar has to be in the bootclasspath for
#   these command to work)
#
#

In the ctrlhandler.act file, each command entry starts with a Ctrl-Break Handler name followed by the arguments to be passed to the Ctrl-Break Handler. The arguments should be on the property form (that is, name=value; for example, set_filename filename=c:\output.txt append=true). String, integer or boolean values are acceptable property types.

You can disable Ctrl-Break functionality by setting this command:

-Djrockit.dontusectrlbreakfile=true.

 

Available Diagnostic Commands

Table 21-1 lists the currently available diagnostic commands.

Table 21-1 Existing Ctrl-Break Handlers
Command
Description
set_filename filename=<file> [append=true]
Set the file which all commands following this command will use for printing. You can have several set_filename commands in a file. It takes two arguments: filename and an optional append to specify if you want to append to the file or overwrite it. The default file is stderr, and to overwrite the file.
timestamp
Prints a timestamp.
version
Prints the JRockit JVM version
print_threads [nativestack=true] [jvmmonitors=true]
Prints a normal thread dump.
  • nativestack=true will print C-level stacktraces as well as Java traces.
  • jvmmonitors=true will also print the JRockit JVM's internal native locks (those that are registered): status and wait queue, and with -XXnativeLockProfiling=true their profile stats (acquired/contended/tryfailed).
verbosity [args=<components>] [filename=<file>]
Change the verbosity level normally specified with -Xverbose. This handler does not work in R25.
command_line
Prints the command line used to start the JRockit JVM.
print_object_summary
See the JRockit Memory Leak Detector User Guide (for JRockit Mission Control 1.0) or the Memory Leak Detector built-in help (for Oracle JRockit Mission Control 2.0 and later).
print_class_summary
Print all loaded classes.
print_utf8pool
Print all UTF8 strings.
print_memusage
Print all memory the OS says the JRockit JVM process is holding onto, as well as what each subsystem thinks it is holding onto.
oom_diagnostics

Note: This command applies only to versions of JRockit JVM R26.3 and earlier.

Cause an OutOfMemoryDiagnostics to be printed. If both set_filename and -Djrockit.oomdiagnostics.filename is set, the latter takes precedence.
This command is deprecated in the JRockit JVM R26.4. Use heap_diagnostics instead.
heap_diagnostics
Cause a heap diagnostic to be printed. Output ends up on Ctrl-Break Handler output stream and does not take the property -Djrockit.oomdiagnostics.filename into consideration. This command applies only to versions of JRockit JVM R26.4 and later.
heapreport
Prints out a report on the JVM’s native memory allocation on the C-Heap. This is only supported if you are running with HEAP_TRACE defined.
gcreport
Prints out a comprehensive summary of garbage collection activity so far during the run. In order to be able to dynamically print out the same information as -XgcReport would provide at the end of an application run, make sure to have the option flag -XgcReport in your start-up configuration, otherwise the correct measurements won't be performed.
jrarecording [filename=<file>] [time=<time>] [nativesamples=true]
Starts a JRA recording. For more information, please refer to Creating a JRA Recording with JRockit Mission Control 1.0
run_optfile [filename=<file>]
See Creating and Using an Optfile.
start_management_server
Starts the management server. (Actually the listening socket that in turn starts servers whenever a connection is established). managementnserver.jar has to be in the boot classpath for this command to work.
kill_management_server
Stops the management server. (Actually shuts down the listening socket.) The only reason it isn't named stop_management_server is that stop is a reserved keyword that stops parsing of the act file. The managementserver.jar has to be in the boot classpath for this command to work.
lockprofile_print
Will print the current values of the lock profile counters. Enable lock profiling with -Djrockit.lockprofiling.
lockprofile_reset
Will reset the current values of the lock profile counters. Enable lock profiling with -Djrockit.lockprofiling.
print_exceptions [stacktraces=all/true/false] [exceptions=all/true/false]
Enable/disable printing of exceptions (see -Xverbose). To turn exception printing off completely you need to set exceptions = false even if it was turned on by stacktraces = true.
force_crash
Forces the Oracle JRockit JVM to crash/dump.
run_class [class=<classname>] [daemon=<true|false>]
Runs any class implementing the Runnable interface. Must be enabled with:
-Djrockit.ctrlbreak.enablerun_class=true.
Note that the class name must use slashes (/) to separate package names; for example:
jrcmd <pid> run_class class=java/lang/Thread
memprof [sampleRate=<seconds>] [trendSize=<size>] [forceThreshold=<bytes>] [verboseResultStats=<true|false>] [skipSymbols=<symbolexcludelist>]
Turns on memory profiling in the running application. Memory profiling can be very helpful for diagnosing such problems as memory leaks.

 

Getting Help

To get help about the available commands, execute the special command help. This will print all available commands.


  Back to Top       Previous  Next