Before the profiling agent can start any recordings, the profiling settings have to be set. This happens when you connect with the JProfiler UI. Under some circumstances, it is required that the profiling agent knows the profiling settings at startup. The main use cases are:

• Offline profiling

  Triggers or the API are used to record data and save snapshots. The JProfiler GUI cannot connect in this mode. See the help topic on offline profiling for more information.

• Profiling with jpcontroller on a headless machine

  The command line utility jpcontroller can be used instead of the JProfiler GUI to record data and save snapshots interactively or with a non-interactive command file. However, jpcontroller has no facility for configuring profiling settings, so they have to be set in advance.

• Remote attach to older OpenJ9 and IBM JVMs

  Older OpenJ9 and IBM JVMs before 8u281, 11.0.11 and Java 17 do not have the ability to redefine classes without endangering the stability of the profiled process, so profiling settings have to be set at startup. The "Profiled JVM" step of the remote integration wizard in JProfiler asks you about the type of the JVM, and if you select Older OpenJ9 and IBM JVMs there, the wizard will add the options discussed below.

In general, setting profiling settings at startup is the most efficient mode of operation, because the least number of class redefinitions have to be performed. If the reduced convenience is not a problem, it can be used for any kind of profiling session.

Setting profiling settings at startup

If you use an integration wizard, select the On a remote computer option on the "Local or Remote" step and then the Apply configuration at startup option on the "Config synchronization" step. The wizard will then add the same options as discussed in the following paragraphs.

If you have added an -agentpath VM parameter to your start script to load the profiling agent, the profiling settings can be set by adding

,config=<path to config file>,id=<session ID>

to the -agentpath parameter. A complete parameter will look like this:

-agentpath:/path/to/libjprofilerti.so=port=8849,nowait,config=/path/to/config,id=123

If you use jpenable to load the profiling agent after the process has been started, you can choose offline mode in the interactive execution and specify config and ID there. Alternatively, pass the --offline, --config and --id arguments for non-interactive execution.

Preparing the config file

The referenced config file can be the config file of the JProfiler installation on the current machine, in which case the config parameter does not have to be specified at all. The JProfiler config file is located at $HOME/.jprofiler14/jprofiler_config.xml or %USERPROFILE%\.jprofiler14\jprofiler_config.xml and is the default for the config option of the -agentlib VM parameter.

Often, automated profiling should be performed on a different machine and referencing the local JProfiler config file is not possible. You can then prepare a session with the profiling settings in the JProfiler UI on your local machine, export it via Session→Export Session Settings and transfer it to the machine where JProfiler is running on.

The session ID can be seen in the top-right corner of the "Application settings" tab of the session settings dialog (see the screenshot below). If the exported file only contains one session, the id parameter does not have to be specified.

Synchronizing the config file

After you have completed the initial setup, you may want to adjust profiling settings for future profiling runs. This requires that the config file is copied to the remote machine each time you make a modification.

Remote sessions in JProfiler have a "Config synchronization" feature that can automate this process for you.

If the session is started via SSH, you can copy the config file via SSH directly to the remote machine. Otherwise, you can still copy the config file to a local directory which may be mounted on the remote machine. Finally, you can execute an arbitrary command, to copy the config file by other means.