Command Line Executables For Profiling
JProfiler includes a number of command line tools for setting up the profiling agent and controlling profiling actions from the command line.
Loading the profiling agent into a running JVM
With the command line utility
bin/jpenable, you can load the profiling agent into any
running JVM with a version of 6 or higher. With command line arguments you can automate the process so that it
requires no user input. The supported arguments are:
Usage: jpenable [options] jpenable starts the profiling agent in a selected local JVM, so you can connect to it from a different computer. If the JProfiler GUI is running locally, you can attach directly from the JProfiler GUI instead of running this executable. * if no argument is given, jpenable attempts to discover local JVMs that are not being profiled yet and asks for all required input on the command line. * with the following arguments you can partially or completely supply all user input on the command line: -d --pid=<PID> The PID of the JVM that should be profiled -n --noinput Do not ask for user input under any circumstances -h --help Show this help --options=<OPT> Debugging options passed to the agent GUI mode: (default) -g --gui The JProfiler GUI will be used to attach to the JVM -p --port=<nnnnn> The port on which the profiling agent should listen for a connection from the JProfiler GUI Offline mode: -o --offline The JVM will be profiled in offline mode -c --config=<PATH> Path to the config file with the profiling settings -i --id=<ID> ID of the session in the config file. Not required, if the config file holds only a single session. Note that the JVM has to be running as the same user as jpenable, otherwise JProfiler cannot connect to it. An exception are Windows services running under the local system account if you list them interactively with jpenable.
Saving HPROF snapshots
If you just need a heap snapshot, consider using the
command line tool that saves an HPROF snapshot without loading
the profiling agent into the VM:
Usage: jpdump [options] jpdump saves an HPROF heap dump from a locally running JVM to a file. The HPROF file can then be opened in the JProfiler GUI. * if no argument is given, jpdump lists all locally running JVMs. * with the following arguments you can partially or completely supply all user input on the command line: -p --pid=<PID> The PID of the JVM whose heap should be dumped With a specified PID, no further questions will by asked. -a --all Save all objects. If not specified, only live objects are dumped -f --file=<PATH> Path to the dump file. If not specified, the dump file <VM name>.hprof is written in the current directory. If the file already exists, a number is appended. -h --help Show this help Note that the JVM has to be running as the same user as jpdump, otherwise JProfiler cannot connect to it. An exception are Windows services running under the local system account if you list them interactively with jpdump.
This has a lower overhead than loading the profiling agent and saving a JProfiler heap snapshot. Also, because the profiling agent can never be unloaded, this method is suitable for JVMs running in production.
Controlling the profiling agent
When you start the
bin/jpcontroller executable without arguments, it attempts to connect
to a profiled JVM on the local machine. If multiple profiled JVMs were discovered, you can select one from a list.
Because the discovery mechanism uses the attach API of the Oracle JVM, this only works for Oracle JVMs starting
with Java 6.
jpcontroller can only connect to JVMs where the profiling settings have been set, so it
does not work if the JVM was started with the "nowait" option for the
-agentpath VM parameter.
That option is set when choosing the Startup immediately, connect later with the JProfiler GUI radio
button on the "Startup mode" screen of an integration wizard and no JProfiler GUI has yet connected to the agent.
jpenable without the
--offline argument also requires a
connection from the JProfiler GUI before
jpcontroller can connect to the profiled
If you want to connect to a process on a remote computer, or if the JVM is not a HotSpot JVM with a version of 6
or higher, you have to pass the VM parameter
-Djprofiler.jmxServerPort=[port] to the profiled
JVM. An MBean server will be published on that port and you can specify the chosen port as an argument to
jpcontroller. With the additional VM parameter
-Djprofiler.jmxPasswordFile=[file] you can specify a properties file with key-value pairs
of the form
user=password to set up authentication. Note that these VM parameters are overridden
com.sun.management.jmxremote.port VM parameter.
With the explicit setup of the JMX server, you can use the command line controller to connect to a
remote server by invoking
jpcontroller host:port. If the remote computer is only
reachable via an IP address, you have to add
-Djava.rmi.server.hostname=[IP address] as a
VM parameter to the remote VM.
jpcontroller is an interactive command line utility, but you can also
automate profiling sessions with it without the need for manual input. An automated invocation would pass
[pid | host:port] to select a profiled JVM as well as the
argument. In addition, a list of commands is read, either from stdin, or from a command file that is
specified with the
--command-file argument. Each command starts on a new line, lines that
are blank or start with a "#" comment character are ignored.
Commands for this non-interactive mode are the same as the method names in the
They require the same number of parameters, separated by spaces. String must be surrounded by double quotes if they
contain spaces. In addition, a
sleep <seconds> command is provided that pauses
for a number of seconds. This allows you to start recording, wait for some time and then save a snapshot to disk.
The supported arguments of jpcontroller are shown below:
Usage: jpcontroller [options] [host:port | pid] * if no argument is given, jpcontroller attempts to discover local JVMs that are being profiled * if a single number is specified, jpcontroller attempts to connect to the JVM with process ID [pid]. If that JVM is not profiled, jpcontroller cannot connect. In that case, use the jpenable utility first. * otherwise, jpcontroller connects to "host:port", where port is the value that has been specified in the VM parameter -Djprofiler.jmxServerPort=[port] for the profiled JVM. The following options are available: -n --non-interactive Run an automated session where a list of commands is read from stdin. -f --command-file=<PATH> Read commands from a file instead of stdin. Only applicable together with --non-interactive. Syntax for non-interactive commands: See the javadoc for RemoteControllerMBean (https://bit.ly/2DimDN5) for a list of operations. Parameters are separated by spaces and must be quoted if they contain spaces. For example: addBookmark "Hello world" startCPURecording true sleep 10 stopCPURecording saveSnapshot /path/to/snapshot.jps The sleep <seconds> command pauses for the specified number of seconds. Empty lines and lines starting with # are ignored.