JProfiler Help - 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 bin/jpdump 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. Using jpenable without the --offline argument also requires a connection from the JProfiler GUI before jpcontroller can connect to the profiled process.

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 by the 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.

By default, 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 --non-interactive 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 JProfiler MBean. 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.

Command Line Executables For Profiling

Loading the profiling agent into a running JVM

Saving HPROF snapshots

Controlling the profiling agent