The big picture of all important interactions involving the profiled application, the JProfiler UI and all command line utilities is given below.

The profiling agent

The "JVM tool interface" (JVMTI) is a native interface that a profiler uses to gain access to information and add hooks for inserting its own instrumentation. This means that at least part of the profiling agent must be implemented as native code and so a JVM profiler is not platform-independent. JProfiler supports a range of platforms that are listed on the web site.

A JVM profiler is implemented as a native library that is loaded either at startup or at some point later on. To load it at startup, a VM parameter -agentpath:<path to native library> is added to the command line. You rarely have to add this parameter manually, because JProfiler will add it for you, for example, in an IDE integration, an integration wizard or if it launches the JVM directly. However, it's important to know that this is what enables profiling.

If the JVM succeeds in loading the native library, it calls a special function in the library to give the profiling agent a chance to initialize itself. JProfiler will then print a couple of diagnostic messages prefixed with JProfiler> so you know that profiling is active. The bottom line is that if you pass the -agentpath VM parameter, the profiling agent is either loaded successfully or the JVM does not start.

Once loaded, the profiling agent asks the JVMTI to be notified of all kinds of events, such as thread creation or class loading. Some of these events directly deliver profiling data. Using the class loading event, the profiling agent instruments classes as they are loaded and inserts its own bytecode to perform its measurements.

JProfiler can load the agent into an already running JVM, either by using the JProfiler UI, or with the bin/jpenable command line tool. In that case, a substantial number of already loaded classes may have to be retransformed in order to apply the required instrumentation.

Recording data

The JProfiler agent only collects the profiling data. The JProfiler UI is started separately and connects to the profiling agent through a socket. This means that it is actually irrelevant if the profiled JVM is running on the local machine or on a remote machine - the communication mechanism between the profiling agent and the JProfiler UI is always the same.

From the JProfiler UI, you can instruct the agent to record data, display the profiling data in the UI and save snapshots to disk. As an alternative to the UI, the profiling agent can be controlled through its MBean. A command line tool that uses this MBean is bin/jpcontroller.

Yet another way to control the profiling agent is with a predefined set of triggers and actions. In that way, the profiling agent can operate in unattended mode. This is called "offline profiling" in JProfiler and is useful for automating profiling sessions.

Snapshots

While the JProfiler UI can show live profiling data, it is often necessary to save snapshots of all recorded profiling data. Snapshots are either saved manually in the JProfiler UI or automatically by trigger actions.

Snapshots can be opened and compared in the JProfiler UI. For automated processing, the command line tools bin/jpexport and bin/jpcompare can be used to extract data and create HTML reports from previously saved snapshots.

A low-overhead way of obtaining a heap snapshot from a running JVM is to use the bin/jpdump command line tool. It uses the built-in functionality of the JVM to save an HPROF snapshot that can be opened by JProfiler and does not require the profiling agent to be loaded.