This chapter is dedicated to JRCMD—one of the simplest tools in the JRockit distribution. JRCMD is a small command-line tool that can be used to interact with a running JRockit instance. It can also be used to list all running instances of the JRockit JVM on a system.
In this chapter, you will learn:
- How to use JRCMD to list the locally running JVMs on your machine
- How to use JRCMD to execute diagnostic commands on one or all JVMs running locally on your machine
- How to override the SIGQUIT signal handler to make JRockit run diagnostic commands of your choice instead of printing stack dumps, which is the default action
- How to utilize JRCMD to solve various tasks such as:
- Heap analysis
- Exception profiling
- Native memory tracking
- Controlling the management server lifecycle
- Controlling JRockit Flight Recorder from the command line
The last part of this chapter is in a format that makes it usable as a JRCMD reference. The reference part lists the various diagnostic commands in alphabetical order, complete with examples.
Sometimes a command-line utility is exactly the right tool for the job. You may want to send commands to JVMs in batch scripts, or you may be operating in a very secure environment and only have a command line at your disposal through SSH. Whatever the reason, JRCMD is a small and powerful tool for sending commands to locally running instances of the JRockit JVM from the command line.
The basic usage pattern is to first execute JRCMD with no arguments to list the JVMs currently running on the system. The JVMs will be listed by operating system Process ID (PID) followed by the class name of the main class of the Java application running in the JVM.
For example:
C:>JROCKIT_HOMEinjrcmd
2416 com.jrockit.mc.rcp.start.MCMain
19344 jrockit.tools.jrcmd.JrCmd
In the previous example, there were two JVM instances running when JRCMD was executed—an instance running JRockit Mission Control and, as JRCMD is a Java application too, the JVM running JRCMD itself.
The JRockit instance on which to execute the command is selected by passing its PID as the first argument to JRCMD. A special case is passing PID 0, in which case JRCMD will attempt to execute the command on all the JVMs it can find. As different versions of JRockit may be running at the same time and may support different sets of commands, not all commands may be available for all versions of JRockit. Normally, a specific PID should be selected. In addition, two instances of the same JRockit version may also export different sets of diagnostic commands depending on command-line parameters and configuration.
To list the commands available in a specific instance of JRockit, the help command is used, as illustrated by the following example:
C:>JROCKIT_HOMEinjrcmd 2416 help
2416:
The following commands are available:
kill_management_server
start_management_server
print_object_summary
memleakserver
...
For more information about a specific command use 'help <command>'.
Parameters to commands are optional unless otherwise stated.
The following examples assume that the bin directory in JROCKIT_HOME is on the path.
The commands that JRCMD can execute are commonly referred to as the JRockit Diagnostic Commands, as that is what they are called when accessed through the JRockit Management API (JMAPI) or the custom JRockit JMX MBeans (JMXMAPI).
The diagnostic commands can be invoked in several different ways. JMAPI and JMXMAPI can be used to invoke them programmatically, from Java. This will be discussed in Chapter 12, Using the JRockit Management APIs.