This chapter describes how to use diagnostic commands to communicate with a running Oracle JRockit JVM process.
The diagnostic commands tell the JRockit JVM to perform tasks such as printing a heap report or a garbage collection activity report, or enabling a specific verbose module.
This chapter contains the following sections:
For more information about each diagnostic command, see the "Diagnostic Commands" chapter in Oracle JRockit Command Line Reference.
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, the JVM will search for the ctrlhandler.act file and execute the commands in it.
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 diagnostic command by using the system property -Djrockit.ctrlbreak.enable<name>=<true|false>, where name is the name of the diagnostic command. The run_class handler is not enabled by default. To enable it, enter the following:
-Djrockit.ctrlbreak.enablerun_class=true
jrcmd is a command-line tool included with the JRockit JDK that you can use to send diagnostic commands to a running JVM process. jrcmd communicates with the JVM by using the JDK attach mechanism. This section provides a brief overview of jrcmd. It includes information about the following:
Enter jrcmd at the command line with the appropriate parameters.
Example:
jrcmd <jrockit pid> [<command> [<arguments>]] [-l] [-f file] [-p] -h]
<jrockit pid> is either the process ID or the name of the Main class that runs the application.
[<command> [<arguments>]] is any diagnostic command and its associated arguments; for example, version, print_properties, command_line.
-l displays the counters exposed by this process. These counters are for internal use by Oracle and are not officially supported or documented.
-f reads and executes commands from the file.
-p lists JRockit JVM processes on the local machine.
-h displays help.
If the PID is 0, commands will be sent to all Jrockit JVM processes. If no options are given, the default is -p. If you are running a Flight Recorder-specific diagnostic command and use 0 as the PID, the recorder does not remain active.
Note:
jrcmd parameter strings are limited to 256 characters. If the parameter string exceeds this limit, an exception will be thrown.This section provides examples of using jrcmd for the following tasks:
Do the following to list all JRockit JVM processes running on the machine:
Run jrcmd or jrcmd -p to list the running JRockit JVMs; for example:
> jrcmd -P
10064 Sleeper
-Xverbose:memory -Xmx30m
>
You will see the PID of the process (10064), the program it is currently running (Sleeper), and the parameters used to start the JVM (-Xverbose:memory -Xmx30m).
To send a command to the process you identified in Section 4.2.2.1, "Listing JRockit JVM Processes", do the following:
Find the PID. See Section 4.2.2.1, "Listing JRockit JVM Processes" (10064).
Run jrcmd with that PID and the version command; for example:
> jrcmd 10064 version
This command sends the version command to the JRockit JVM. The response will be:
Oracle JRockit(R) build R28.0.0-679-130297-1.6.0_17-20100312-2122-windows-x86_64, compiled mode GC mode: Garbage collection optimized for throughput, strategy: genparpar
You can create a file (similar to the ctrlhandler.act file) that contains several commands and execute all of them. Use this procedure:
Create a file called commands.txt with the following contents:
version
timestamp
Execute the file with jrcmd; for example:
> jrcmd 10064 -f commands.txt
The system will respond:
Oracle JRockit(R) build R28.1.0-102-137086-1.6.0_20-20100825-2121-windows-ia32, compiled mode GC mode: Garbage collection optimized for throughput, strategy: genparpar ==== Timestamp ==== uptime: 0 days, 02:41:21 time: Mon Sep 06 16:23:43 2010
Set the PID to 0 to send the commands to all running JRockit JVM processes.
jrcmdWhen using jrcmd, be aware of these limitations:
In order to issue diagnostic commands to a process on Linux or Solaris, you must run jrcmd with the same user as the one running the Java process.
When using jrcmd on Windows, you must 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, because they are running in two separate environments.
When a JRockit JVM is started as the root user and then changed to a less-privileged user, security restrictions will prevent jrcmd from communicating properly with the process.
The following actions are permitted:
Root can list the running processes.
The less-privileged user can send commands to the process.
The following actions are prohibited:
Root cannot send commands to the process; commands will be treated as a Ctrl-Break signal and print a thread dump instead.
Less privileged users 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 cannot 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 FAT file systems, which provide 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 Example 4-1) in your current working directory. If it cannot find the file there, it will search in the directory that contains the JVM. If it cannot find this file there, it will revert to printing the thread dump. If it finds the file, it will read the file searching for command entries, each of which invoke the corresponding diagnostic command.
Example 4-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 # # 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 in the proper format (that is, name=value; for example, set_filename filename=c:\output.txt append=true). The acceptable property types are string, integer, and Boolean values.
You can disable Ctrl-Break functionality by using the following option:
-Djrockit.dontusectrlbreakfile=true
To get help about the available commands, use the command help. This will print all available commands.
For more information about each diagnostic command, see the "Diagnostic Commands" chapter in Oracle JRockit Command Line Reference.