Attaching To JVMs

  JProfiler has the capability to profile any JVM that has a minimum version of 1.6, even if that JVM was not started with the VM parameters for profiling. Through the use of the attach API that is present in Oracle/Sun JVMs, JProfiler can load the profiling agent on the fly. There are three scenarios for attaching to running JVMs:
  • Locally running JVM
    In this case, invoke Session->Quick Attach from the main menu and select the JVM from a list of discovered JVMs.

    When you close the session, you can save the session settings (filter, profiling and triggers settings) so that you can reuse them for future use. When you attach to the same application again, start the saved session instead of using "Quick attach". Of course you can also start out by creating such a dedicated session in the first place.

  • JVM running on a remote machine with SSH access

    In this case, invoke Session->Quick Attach from the main menu and select "On another computer". Click [Edit] to configure the SSH connection and make sure to keep the "Discover running JVMs and attach to selected process" option on the "Configure SSH tunnel" step of the wizard selected.

    After the SSH connection has been established, JProfiler will then

    • automatically detect the remote platform
    • if not already present, download the appropriate agent libraries from ej-technologies' web server to your local machine
    • if not already present, upload those agent libraries to the remote machine
    • use the jpenable command line tool to detect JVMs on the remote machine and report back information through the SSH connection

    Similar to the "Locally running JVM" case above, you can then select the JVM from the list of discovered JVMs. In addition, the selection dialog allows you to change the user that is used for detecting JVMs.

  • JVM running on remote machine without SSH access
    In this case, extract a 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 is listens on a specific profiling port.

    In your local JProfiler GUI, create an "Attach to remote JVM" session and enter the host name and the same profiling port that you specified in jpenable on the remote machine. When you start the session, it connects to the remote JVM and you can start profiling.

    Alternatively, invoke Session->Quick Attach and select the "On another computer" option that will allow you to enter your remote connection details without configuring a session. When you close the session, you will then be asked whether to save it or not.

  When the profiling agent is loaded for an attach session (either by the JProfiler GUI or by jpenable, the profiling agent did not have the chance to instrument classes when they were loaded. Instead, it has to reload them which puts a burden on the PermGem space of the heap. Classes are not easily garbage collected and so the PermGem space has to support both old and new versions of all reloaded classes. If the PermGen space is to small for a particular application, you can increase it with the VM parameter -XX:MaxPermSize=128m.

When you choose "Dynamic instrumentation" as the method call recording type, it is important to choose profiled packages that focus on the classes of interest. In that way, relatively few classes are instrumented. Alternatively, you can choose Sampling in the profiling settings.

If JProfiler detects that the PermGen space would be overloaded with the current filter settings, it will warn you in the session startup dialog. You should then switch to sampling or define narrow set of profiled packages. Clicking on the hyperlinks in the warning message will quickly make these changes. When selecting profiled packages, the total amount of instrumented classes is monitored and you are notified if you exceed the approximate maximum number of classes that can be instrumented.

  Views that show information on recorded objects, such as the Recorded objects view, the Allocation call tree or the heap walker allocations screen rely on instrumentation of certain classes. Unfortunately, array allocations have to be instrumented at all call sites. When the profiling agent is present at startup, this is not a problem, but in attach mode, a large fraction of all classes has to be instrumented which might fail due to the limitations of the PermGen space.

By default, array allocations are not recorded in attach mode, although the session startup dialog gives you the possibility to do so for "non-client" JVMs (the "client" JVM has a bug that prevents this from working successfully).