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 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:
By using jrcmd, a command line tool that sends the commands to a given JRockit JVM process.
By pressing Ctrl-Break, whereupon the JVM will look for a ctrlhandler.act file and execute the commands listed therein.
By using the JRockit Management Console in Oracle JRockit Mission Control to send diagnostic commands to a running JRockit JVM process.
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:
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:
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:
In order to issue diagnostic commands to a process on Linux or Solaris, you need to run jrcmd as the same user as the one running the Java process.
When using jrcmd on Windows, you need to run the Java process and jrcmd from the same Windows station. If you run the Java process as a Windows service, and run jrcmd on your desktop, it will not work, since they are running in two separate environments.
When an JRockit JVM is started as root and then changed to a less privileged user, jrcmd will not be able to communicate properly with the process thereafter due to security restrictions.
The following things can be done: Root can list the running processes. The less privileged user can send commands to the process.
The following things cannot be done: Root cannot send commands to the process; any commands will be treated as a Ctrl-Break signal and print a thread dump instead. The less privileged user cannot list the running JRockit JVM process, but if they know the process ID (PID), they can send commands to the process using jrcmd <pid> <command>.
If the default Windows temporary directory (java.io.temp) is on a FAT file system, jrcmd will not be able to discover local processes. For security reasons, local monitoring and management is only supported if your default Windows temporary directory is on a file system that supports setting permissions on files and directories (for example, on an NTFS file system). It is not supported on a FAT file system that provides insufficient access controls.
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.
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:
Available Diagnostic Commands
Table 21-1 lists the currently available diagnostic commands.
Table 21-1 Existing Ctrl-Break Handlers
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.
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.
Prints the command line used to start the JRockit JVM.
Print all memory the OS says the JRockit JVM process is holding onto, as well as what each subsystem thinks it is holding onto.
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.
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.
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.
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.
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.
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.
Will print the current values of the lock profile counters. Enable lock profiling with -Djrockit.lockprofiling.
Will reset the current values of the lock profile counters. Enable lock profiling with -Djrockit.lockprofiling.