JProfiler API documentation

com.jprofiler.agent
Class Controller

java.lang.Object
  extended by com.jprofiler.agent.Controller

public class Controller
extends java.lang.Object

This is JProfiler's profiling API. It is contained in bin/agent.jar in your JProfiler installation directory. Call these static methods from your source code to influence the run time behaviour of JProfiler.

When executing your application without JProfiler, all calls into this class will quietly do nothing.

Nested Class Summary
static interface Controller.HTTPRequestResolver
          Interface for mapping HTTP requests to strings that are displayed in the JProfiler GUI.
static interface Controller.JMSResolver
          Interface for mapping JMS messages to strings that are displayed in the JProfiler GUI.
 
Method Summary
static void addBookmark(java.lang.String description)
          Add a bookmark at the current time.
static void registerHTTPRequestResolver(Controller.HTTPRequestResolver resolver)
          Register a resolver class that will map HTTP requests to description strings.
static void registerJMSResolver(Controller.JMSResolver resolver)
          Register a resolver class that will map JMS messages to description strings.
static void saveSnapshot(java.io.File file)
          Save a snapshot of all profiling data to disk.
static void saveSnapshotOnExit(java.io.File file)
          Save a snapshot of all profiling data to disk when the VM shuts down.
static void startAllocRecording(boolean reset)
          Start recording of memory allocations.
static void startCPURecording(boolean reset)
          Start recording CPU data.
static void startThreadProfiling()
          Start recording of thread states and monitor usage.
static void startVMTelemetryRecording()
          Start recording of VM telemetry data.
static void stopAllocRecording()
          Stop recording of memory allocations.
static void stopCPURecording()
          Stop CPU recording.
static void stopThreadProfiling()
          Stop recording of thread states and monitor usage.
static void stopVMTelemetryRecording()
          Stop recording of VM telemetry data.
static void triggerHeapDump()
          Trigger a heap dump.
static void triggerHeapDump(boolean fullGc)
          Trigger a heap dump.
static void triggerHeapDump(boolean fullGc, boolean onlyRecorded)
          Trigger a heap dump.
static void triggerHeapDump(boolean fullGc, boolean onlyRecorded, boolean primitiveData)
          Trigger a heap dump.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

startCPURecording

public static void startCPURecording(boolean reset)
Start recording CPU data. This method can be called repeatedly and alternatingly with stopCPURecording(). With these methods you can restrict CPU profiling to certain regions of your code.

Parameters:
reset - if true, any previously accumulated CPU profiling data will be discarded. If false, CPU data will be accumulated accross pairs of invocations of startCPURecording() and stopCPURecording().

stopCPURecording

public static void stopCPURecording()
Stop CPU recording. This method can be called after startCPURecording() has been called. However, you do not have to call it since CPU profiling can run until the JVM exits.

startAllocRecording

public static void startAllocRecording(boolean reset)
Start recording of memory allocations. This method can be called repeatedly and alternatingly with stopAllocRecording(). With these methods you can restrict memory allocation profiling to certain regions of your code. This is especially useful for profiling an application running within an application server.

Parameters:
reset - if true, any previously recorded profiling data will be discarded. If false, allocations within all pairs of invocations of startAllocRecording() and stopAllocRecording() will be recorded.

stopAllocRecording

public static void stopAllocRecording()
Stop recording of memory allocations. This method can be called after startAllocRecording() has been called. However, you do not have to call it since memory profiling can run until the JVM exits.

addBookmark

public static void addBookmark(java.lang.String description)
Add a bookmark at the current time. The bookmark will be displayed in all JProfiler graphs with a time axis. The description will be displayed in the tooltip for the bookmark.

Parameters:
description - the name of the bookmark, may also be null

triggerHeapDump

public static void triggerHeapDump()
Trigger a heap dump. Calls triggerHeapDump(false, false) for backwards compatibility purposes.

triggerHeapDump

public static void triggerHeapDump(boolean fullGc)
Trigger a heap dump. Calls triggerHeapDump(fullGc, false) for backwards compatibility purposes.

Parameters:
fullGc - if true, a full garbage collection will be performed.

triggerHeapDump

public static void triggerHeapDump(boolean fullGc,
                                   boolean onlyRecorded)
Trigger a heap dump. Calls triggerHeapDump(fullGc, onlyRecorded, true) for backwards compatibility purposes.

Parameters:
fullGc - if true, a full garbage collection will be performed.
onlyRecorded - if true, only objects recorded between startAllocRecording and stopAllocRecording will be inlucded in the dump.

triggerHeapDump

public static void triggerHeapDump(boolean fullGc,
                                   boolean onlyRecorded,
                                   boolean primitiveData)
Trigger a heap dump. If you want to analyze a heap dump with the heap walker in a snapshot saved with the saveSnapshot method, you should call this method from your source code at an appropriate time.

ATTENTION: Taking a heap dump takes a long time (on the order of seconds). If you call this method to often, your application might become unusable or take an excessively long time to finish.

Parameters:
fullGc - if true, a full garbage collection will be performed.
onlyRecorded - if true, only objects recorded between startAllocRecording and stopAllocRecording will be inlucded in the dump.
primitiveData - if true, also primitive data will be recorded in JVMPI mode.

saveSnapshot

public static void saveSnapshot(java.io.File file)
Save a snapshot of all profiling data to disk. This is especially important for offline profiling. You should choose the standard extension .jps for the file parameter, since JProfiler's GUI frontend filters the corresponding file choosers for that extension. If you want to save several snapshots during one profiling run, please take care to provide unique file parameters since snapshot files will be overwritten otherwise.

ATTENTION: Saving a snapshot takes a long time (on the order of seconds). If you call this method to often, your application might become unusable or take an excessively long time to finish, and your hard disk might run out of space.

Parameters:
file - the file to which the snapshot should be saved.

registerJMSResolver

public static void registerJMSResolver(Controller.JMSResolver resolver)
Register a resolver class that will map JMS messages to description strings. The default action in JProfiler is to call getJMSDestination().toString() on JMS messages. JMS messages with the same description are cumulated by JProfiler, so the resolver can determine the granularity of JMS message recording.

Parameters:
resolver - the resolver, null to restore the default behavior.

registerHTTPRequestResolver

public static void registerHTTPRequestResolver(Controller.HTTPRequestResolver resolver)
Register a resolver class that will map HTTP requests to description strings. The default action in JProfiler is to call getQueryString() on HTTPServletRequests. HTTP requests with the same description have a separate call tree, so the resolver can determine the granularity of HTTP request recording.

Parameters:
resolver - the resolver, null to restore the default behavior.

startThreadProfiling

public static void startThreadProfiling()
Start recording of thread states and monitor usage. This method can be called repeatedly and alternatingly with stopThreadProfiling(). For an offline session, thread profiling is switched on by default.

stopThreadProfiling

public static void stopThreadProfiling()
Stop recording of thread states and monitor usage. This method can be called repeatedly and alternatingly with startThreadProfiling(). However, you do not have to call it since thread profiling can run until the JVM exits.

startVMTelemetryRecording

public static void startVMTelemetryRecording()
Start recording of VM telemetry data. This method can be called repeatedly and alternatingly with stopVMTelemetryRecording(). For an offline session, VM telemetry recording is switched on by default.

stopVMTelemetryRecording

public static void stopVMTelemetryRecording()
Stop recording of VM telemetry data. This method can be called repeatedly and alternatingly with startVMTelemetryRecording(). However, you do not have to call it since VM telemetry recording can run until the JVM exits.

saveSnapshotOnExit

public static void saveSnapshotOnExit(java.io.File file)
Save a snapshot of all profiling data to disk when the VM shuts down. This is especially important for offline profiling. You should choose the standard extension .jps for the file parameter, since JProfiler's GUI frontend filters the corresponding file choosers for that extension.

ATTENTION: Saving a snapshot can take quite some time (on the order fo seconds). When the VM is shut down during a user logout or a system shutdown, the OS may terminate the VM before saving is completed.

Parameters:
file - the file to which the snapshot should be saved.