Remote Profiling - Application Servers And Standalone Applications


1. Introduction

Although it is easiest to profile applications and application servers that are running on your local machine, sometimes it is not possible to replicate the execution environment on your computer. If you have no physical access to the remote machine or if the remote machine has no GUI where you could run JProfiler, you have to set up remote profiling.

Remote profiling means that the profiling agent is running on the remote machine and the JProfiler GUI is running on your local machine. Profiling agent and JProfiler GUI communicate with each other through a socket. This situation is fundamentally the same as running a session that is launched on the local machine, except that the communication socket connects between different machines. The main difference for you is that for sessions launched by JProfiler you don't have to worry about the location of native libraries and that the startup sequence can be managed by JProfiler.

2. The jpenable command line utility

To avoid running an integration wizard or modifying the VM parameters of the profiled application, just extract the JProfiler archive from the download page on the remote machine. You do not have to enter a license key there. Run the bin/jpenable command line application on the remote machine. You will be able to select a JVM and load the profiling agent into it so that it listens on a specific profiling port. In your local JProfiler GUI, you can then connect with an "Attach to profiled JVM (local or remote)" session.

This only works with a Java VM of version 1.6 or higher and has the drawback that array allocations are not recorded, i.e. stack trace information for array allocations is not available. Also, if you're profiling regularly, it might be more convenient to prepare a permanent setup that does not require you to run the jpenable executable every time.

To avoid the use of the JProfiler GUI, jpenable also offers an offline mode where you specify a config file with the desired session settings. Session settings can be exported from the JProfiler GUI. Either the session settings contain triggers that record data and save snapshots or you use the bin/jpcontroller command line application to control data recording and to save snapshots.

3. The remote integration wizard

All integration wizards in JProfiler can help you with setting up remote profiling. After choosing the integration type or application server, the wizard asks you where the profiled application is located. If you choose the remote option, there will be additional questions regarding the remote machine.

When the remote integration wizard asks you for startup scripts or other files of the application server on the remote machine it brings up a standard file selector. If the file system of the remote machine is accessible as a network drive or mounted into your file system, you can select those files and JProfiler will directly write modified files to the right location.

If you do not have direct access to the file system of the remote machine, you have two options: You can use the console integration wizard by executing bin/jpintegrate on the remote machine. Alternatively, you can copy the required files to the local machine and use the "remote" option in the integration wizard. However, you must then transfer the modified or new files back to the remote machine after the integration wizard has completed.

4. Requirements for remote profiling

Although the integration wizards in JProfiler give you all required information, it's always a good idea to have a little more inside knowledge about the mechanics and the requirements of remote profiling. When trouble-shooting a failed integration, you should check that the requirements below are fulfilled correctly.

The following requirements have to be satisfied for remote profiling:

  1. JProfiler has to be installed on the local machine and on the remote machine. If the remote machine is a Unix machine, you might not be able to run the GUI installer of JProfiler. In this case, please use the .tar.gz archive to install JProfiler.

    Unless you specified the "nowait" parameter on the command line together with a "config" argument, (only necessary for pre 1.6 JVMs), you do not have to enter a license key on the remote machine. The license key is always provided by the JProfiler GUI. Because of that, it is sufficient to unpack JProfiler to any directory where you have write permission.

  2. The operating system and the architecture of the remote machine must be explicitly supported by JProfiler. Please see the list of supported platforms for more information. JProfiler is not a pure Java application, it contains a lot of native code which is not easily portable to unsupported platforms.
  3. On the remote machine, you have to add a number of VM parameters to the java invocation of your application server or your standalone application. The fundamental VM parameter is -agentpath:[path to jprofilerti library] which tells the JVM to load the native profiling agent. The help page on remote sessions in the reference section tells you the corresponding path to the jprofilerti library for all platforms.

    Depending on your JVM and your platform, you have to add further VM parameters to your java invocation. The remote session invocation table in the reference section gives you the exact parameter sequence for your configuration.

    This is all that is required to profile a modern JVM (Java 1.5 and later).

  4. On the local machine, you have to define a "Attach to profiled JVM" session whose "host" entry points to the remote machine.

5. Starting remote profiling

If you run the integration wizard for a local application server, JProfiler will be able to start it and connect to it. JProfiler has no way to start the application server if it is located on a remote machine. For remote applications and application servers, you have to perform two actions to start the profiling session:

  1. Execute the modified start script on the remote machine. Depending on what option you have chosen in the remote profiling wizard, there are two startup sequences: either the application or application server starts up completely, or it prints a few lines of information and tells you that it is waiting for a connection. With Java 1.6.0 and later, the profiling options will be sent to the profiling agent when the GUI connects and you don't have to copy your config file to the server.

    With Java 1.5.0 and earlier, changing profiling settings at runtime is not possible. In the case where the application does not wait for a connection from the JProfiler GUI, the profiling agent loads the profiling configuration from the config.xml file you have copied to the server as instructed by the integration wizard.

  2. Start the "Attach to profiled JVM" session in the JProfiler GUI on the local machine. The session will connect to the remote computer and the remote application or application server will then start up if it waited for the GUI connection.

6. Trouble-shooting

When things don't work out as expected, please have a look at the terminal output of the profiled application or application server on the remote machine. For application servers, the stderr stream might be written to a log file. Depending on the content of the stderr output, the search for the problem takes different directions: