To profile a JVM, JProfiler's profiling agent must be loaded into the JVM. This can happen in two different ways: by specifying the -agentpath VM parameter in the startup script, or by using the attach API to load the agent into an already running JVM.
JProfiler supports both modes. Adding the VM parameter is the preferred way of profiling, it is used by integration wizards, IDE plugins and session configuration to start the JVM from within JProfiler. Connections can be made locally and remotely via SSH.
1. -agentpath VM parameters
It is useful to understand how the VM parameters for loading the profiled agent are composed. -agentpath is a generic VM parameter provided by the JVM to load any type of native library that uses the JVMTI interface. Because the profiling interface JVMTI is a native interface, the profiling agent must be a native library. This means you can only comment on platforms that are explicitly supported. 32-bit and 64-bit JVMs also require different native libraries. The Java agent, on the other hand, is loaded with the -javaagent-VM argument and only has access to a limited set of features.
After -agentpath: , the full pathname of the native library will be appended. There is an equivalent argument -agentlib: you only specify the platform-specific library name, but you must ensure that the library is included in the library path. After the path to the library, you can add an equal sign and pass options to the agent, separated by commas. For example, on Linux, the entire parameter might look like this:
-agentpath:/opt/jprofiler10/bin/linux-x64/libjprofilerti.so=port=8849,nowait
The first equal sign separates the pathname from the argument, the second equal sign is part of the argument port=8849. This generic parameter defines the port on which the profiler agent listens for connections from the JProfiler GUI. 8849 is actually the default port, so you can also omit that parameter. However, if you want to profile multiple JVMs on the same machine, you must assign different ports. IDE plugins and locally started sessions assign this port automatically, for integration wizards you have to choose the port explicitly.
The second parameter nowait tells the profiler not to block the JVM at startup, waiting for the JProfiler GUI to connect. Blocking at startup is the default, since the profiling agent does not receive its profiling settings as command line arguments, but from the JProfiler GUI or a configuration file. The command line arguments are only used to bootstrap the profiling agent, tell it how to start and pass debug flags.
By default, the JProfiler agent binds communication sockets to all available network interfaces. If this is not required for security reasons, you can add the option address=[IP address] in order to select a specific interface or loopback to only listen for requests from the local machine. The latter is added automatically for JVMs started for JProfiler UI or IDE integration.
2. Locally initiated sessions
Just like Run Configurations in the IDE, you can profile locally started sessions directly in JProfiler. Specify the classpath, main class, working directory, VM parameters and arguments and JProfiler will start the session for you. All demo sessions shipped with JProfiler are locally started sessions.
A special launch mode is "Web Start", where you select the URL of the JNLP file and JProfiler will start the JVM to profile it. This feature supports OpenWebStart, not legacy WebStart in Oracle JREs prior to Java 9.
A locally started session can be converted to a standalone session using the conversion wizard by invoking Session -> Conversion Wizard from the main menu. Converting Application Session to Remote is just a matter of creating a startup script and inserting the -agentpath VM parameter into the Java call. Converting an application session to offline creates a startup script for offline profiling, which means loading the configuration at startup, no need for the JProfiler GUI. Converting an application session to a Redistributed session does the same thing, but creates a directory jprofiler_dist next to it that contains the profiling agent and the profile so you can send it to other computers that don't have jprofiler installed.
If you develop the analyzed application yourself, consider using the IDE integration instead of launching a session. It will be more convenient and give you better source code navigation. If you are not developing the application yourself but already have a startup script, consider using the remote integration wizard. It will tell you the exact VM parameters that must be added to the Java call.
3. Integration wizard
JProfiler's integration wizards work with many well-known third-party containers using startup scripts or configuration files that can be modified programmatically to include additional VM parameters. For some products, startup scripts can be generated with VM parameters passed as arguments or via environment variables.
In all cases, you have to find some specific files from the third-party product, so JProfiler has the necessary context to perform its modifications. Some generic wizards just give you instructions on what you must do to enable measurement.
The first step in each integration wizard is to choose whether to profile on the local computer or on a remote computer. In the case of a local machine, you have to provide less information, since JProfiler already knows the platform, where JProfiler is installed, and the location of its profile.
An important decision is the "launch mode" discussed above. By default, profiling settings are transferred from the JProfiler UI on startup, but you can also tell the profiling agent to have the JVM start immediately. In the latter case, the profile settings can be applied once the JProfiler GUI is connected.
However, you can also specify a profile and profile settings, which is much more efficient. This is done during the configuration synchronization step. The main problem in this case is that every time the analysis settings are edited locally, the configuration file has to be synchronized with the remote side. The most elegant way is to connect to the remote machine via SSH in the remote address step, then the configuration file can be automatically transferred via SSH.
At the end of the integration wizard, a session is created, analysis starts and, in non-generic cases, third-party products such as application servers are started.
External startup scripts are handled by the "Execute startup script" and "Execute stop script" options on the "Application Settings" tab of the session configuration dialog, and URLs can be displayed by checking the "Use URL to open browser" checkbox. This is also where you can change the remote machine address and configure sync options.
The integration wizards all deal with profiling the JVM running on a remote machine. However, when a configuration file or startup script must be modified, it must be copied to the local computer and the modified version transferred back to the remote computer. It may be more convenient to directly run the command line tool jpintegrate on the remote machine, and have it perform the modifications in-place. jpintegrate requires a full installation of JProfiler and has the same JRE requirements as JProfilerGUI.
When an error occurs when starting a remote assessment session, see the Troubleshooting Guide for a list of steps to resolve the issue.
4. IDE Integration
The most convenient way to evaluate an application is through IDE integration. If you normally start your application from an IDE during development, then the IDE already has all the required information, and the JProfiler plugin can simply add the VM parameter for profiling, start JProfileer if necessary, and connect the profiled JVM to the JProfiler main window.
All IDE integrations are included in the integrations directory of the JProfiler installation. In principle, the archives in this directory can be installed manually via the plugin installation mechanism in the respective IDE. However, the preferred way to install IDE integrations is to invoke Session -> IDE Integrations from the main menu.
A profiling session in the IDE does not get its own session entry in JProfiler, since such a session cannot be started from the JProfilerGUI. Depending on the settings in the IDE, analysis settings are persisted on a per-project or per-run configuration basis.
When connected to an IDE, JProfiler displays a window switcher in the toolbar, making it easy to jump back to the relevant window in the IDE. All ShowSource actions now display the source directly in the IDE, rather than the built-in source viewer in JProfiler.
Five, additional mode
You don't have to decide in advance that you want to profile a JVM. Using an additional feature in JProfiler, you can select a running JVM and dynamically load the profiling agent. While connected mode is convenient, it has several disadvantages that you should be aware of:
- You must determine which JVM to profile from the list of running JVMs. This can sometimes be tricky if many JVMs are running on the same machine.
- There is additional overhead as many classes may need to be redefined to add inserts.
- Some features in JProfiler are not available in append mode. This is mainly because some features of JVMTI can only be turned on at JVM initialization and are not available at later stages of the JVM life cycle.
- Some functionality needs to be inserted in a large portion of all classes. Instrumenting when a class is loaded is cheap, adding instrumentation when a class is loaded later is not. These features are disabled by default when using attach mode.
- The OpenJDK JVM, the Oracle JVM of version 6 or higher, the latest OpenJ9 JVM (8u281+, 11.0.11+ or Java 17+), or the IBM JVM based on such versions support additional features. The VM parameters -XX:+PerfDisableSharedMem and -XX:+DisableAttachMechanism cannot be specified for the JVM.
- The Quick Attach tab in JProfiler's Start Center lists all JVMs that can be profiled. The background color of the list item indicates whether the profiling agent is loaded, the JProfiler GUI is currently connected, or offline profiling is configured.
- When starting an analysis session, the analysis settings can be configured in the Session Settings dialog. When you configure the same process repeatedly, you don't want to re-enter the same configuration again and again, so you can save persistent sessions when you close a session created with the fast connect feature. Next time you want to gauge this process, start the saved session from the Open Session tab instead of the Quick Connect tab. You still need to select a running JVM, but the profiling settings are the same as you configured earlier.
6. Attach to local service
The attach API in the JVM requires the calling process to run as the same user as the process being attached to, so the list of JVMs displayed by JProfiler is limited to the current user. Processes initiated by different users are mostly services. The way to connect to the service varies for Windows, Linux, and Unix-based platforms.
On Windows, the "Extras" dialog has a "Show Services" button that lists all locally running services. JProfiler starts the bridging executable to be able to connect to these processes no matter which user they are running as.
On Linux, JProfiler supports switching users directly in the UI via PolicyKit, which is part of most Linux distributions. By clicking Switch User in the additional dialog, a different username can be entered and authenticated using the system password dialog.
On Unix-based platforms, including macOS, you can execute the command-line tool jpenable as a different user, su or sudo, depending on your Unix variant or Linux distribution. On macOS and Debian-based Linux distributions such as Ubuntu, use sudo.
Use the sudo command:
sudo -u userName jpenableFor su, the required command line is:
su userName -c jpenable
jpenable will allow you to select the JVM and tell you the port on which the profiling agent is listening. On the "Quick Connections" tab in the Launch Center, you can then select the "On Another Computer" option and configure a direct connection to localhost and the port for the given profile.
7. Connect to the JVM on the remote computer
The most demanding profiling setup is remote profiling - the JProfiler GUI is running on the local machine and the profiling JVM is running on another machine. For a setup where the -agentpath VM parameter is passed to the profile JVM, you must have JProfiler installed on the remote machine and set up a remote session on the local machine. Using the remote connection feature in JProfiler, no such modifications are required, only SSH credentials are required to log in to the remote computer.
The SSH connection enables JProfiler to upload the agent package discussed in the "Installing JProfileer" help topic and execute the included command-line tools on the remote machine. You don't need to setup SSH on your local machine, JProfiler comes with it. In the simplest setup, you only need to define the host, username and authentication.
With an SSH connection, JProfiler can automatically discover running JVMs, or connect to a specific port that the profiling agent is already listening on. For the latter case, you can use jpenable or jpintegrate and prepare a special JVM for benchmarking. SSH remote connections can then be configured to connect directly to the configured analysis port.
Autodiscover will list all JVMs on the remote machine that have been started as the SSH logged-in user. In most cases this will not be the user who started the service you want to profile. Since the user that starts the service usually does not allow SSH connections, JProfiler adds a Switch User hyperlink that allows you to switch to that user using sudo or su.
In complex network topologies, it is sometimes not possible to connect directly to remote computers. In this case, you can tell JProfiler to connect using a multi-hop SSH tunnel in the GUI. At the end of the SSH tunnel, you can make a direct network connection, usually to "127.0.0.1".
HPROF snapshots can only be taken for JVMs started by a user logged in with SSH. This is because HPROF snapshots require an intermediate file, which is written with the access rights of the user who started the JVM. For security reasons, file permissions cannot be transferred to SSH logged-in users for downloading. For a full profiling session, there is no such limit.