## JProfiler API documentation

## com.jprofiler.api.agent
Class Controller

    java.lang.Object
      com.jprofiler.api.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.

If you would like to interactively access the functionality in this class, please use the `jpcontroller` command line executable that attaches to the JProfiler MBean which is registered for every profiled application. For more information, please invoke `jprofiler -help`.

Field Summary
`static java.lang.String` | `PROBE_NAME_FILE` Name of the built-in file probe.
`static java.lang.String` | `PROBE_NAME_JDBC` Name of the built-in JDBC probe.
`static java.lang.String` | `PROBE_NAME_JMS` Name of the built-in JMS probe.
`static java.lang.String` | `PROBE_NAME_JNDI` Name of the built-in JNDI probe.
`static java.lang.String` | `PROBE_NAME_PERSISTENCE` Name of the built-in persistence probe.
`static java.lang.String` | `PROBE_NAME_PROCESS` Name of the built-in process probe.
`static java.lang.String` | `PROBE_NAME_SERVLET` Name of the built-in servlet probe.
`static java.lang.String` | `PROBE_NAME_SOCKET` Name of the built-in socket probe.

Method Summary
`static void` | `addBookmark(java.lang.String description)` Adds a bookmark at the current time.
`static void` | `addBookmark(java.lang.String description, java.awt.Color color, boolean dashed)` Add a bookmark at the current time.
`static void` | `enableTriggerGroup(boolean enabled, java.lang.String groupId)` Enable or disable all triggers with a specified group ID.
`static void` | `enableTriggers(boolean enabled)` Enable or disable all triggers.
`static void` | `saveSnapshot(java.io.File file)` Saves a snapshot of all profiling data to disk.
`static void` | `saveSnapshotOnExit(java.io.File file)` Saves a snapshot of all profiling data to disk when the VM shuts down.
`static void` | `startAllocRecording(boolean reset)` Starts recording of memory allocations.
`static void` | `startAllocRecording(boolean reset, TrackingOptions trackingOptions)` Starts recording of memory allocations.
`static void` | `startCallTracer(int cap, boolean recordFiltered, boolean reset)` Starts the call tracer.
`static void` | `startCPURecording(boolean reset)` Starts recording CPU data.
`static void` | `startCPURecording(boolean reset, TrackingOptions trackingOptions)` Starts recording CPU data.
`static void` | `startMethodStatsRecording()` Starts method statistics recording.
`static void` | `startMonitorRecording()` Start recording of monitor usage with default thresholds of 100 microseconds for blocking events and 100 ms for waiting events.
`static void` | `startMonitorRecording(int blockingThreshold, int waitingThreshold)` Start recording of monitor usage.
`static void` | `startProbeRecording(java.lang.String probeName, boolean events)` Start recording data for a selected probe.
`static void` | `startProbeTracking(java.lang.String probeName, java.lang.String[] descriptions, ProbeObjectType objectType, ProbeValueType valueType)` Start tracking selected elements for a selected probe.
`static void` | `startThreadProfiling()` Starts recording of thread states and monitor usage.
`static void` | `startVMTelemetryRecording()` Starts recording of VM telemetry data.
`static void` | `stopAllocRecording()` Stops recording of memory allocations.
`static void` | `stopCallTracer()` Stops the call tracer.
`static void` | `stopCPURecording()` Stops CPU recording.
`static void` | `stopMethodStatsRecording()` Stops method statistics recording.
`static void` | `stopMonitorRecording()` Stop recording of monitor usage.
`static void` | `stopProbeRecording(java.lang.String probeName)` Stop recording data for a selected probe.
`static void` | `stopProbeTracking(java.lang.String probeName, java.lang.String[] description, ProbeObjectType objectType, ProbeValueType valueType)` Stop tracking selected elements for a selected probe.
`static void` | `stopThreadProfiling()` Stops recording of thread states and monitor usage.
`static void` | `stopVMTelemetryRecording()` Stops recording of VM telemetry data.
`static void` | `triggerHeapDump()` Trigger a heap dump.
`static void` | `triggerHeapDump(HeapDumpOptions heapDumpOptions)` Trigger a heap dump with the specified `heap dump options`.
`static void` | `triggerThreadDump()` Trigger a thread dump.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### PROBE_NAME_PERSISTENCE

    public static final java.lang.String PROBE_NAME_PERSISTENCE

  Name of the built-in persistence probe. Used in `startProbeRecording(String, boolean)` and `stopProbeRecording(String)`.

  See Also:
    Constant Field Values

### PROBE_NAME_JDBC

    public static final java.lang.String PROBE_NAME_JDBC

  Name of the built-in JDBC probe. Used in `startProbeRecording(String, boolean)` and `stopProbeRecording(String)`.

  See Also:
    Constant Field Values

### PROBE_NAME_JMS

    public static final java.lang.String PROBE_NAME_JMS

  Name of the built-in JMS probe. Used in `startProbeRecording(String, boolean)` and `stopProbeRecording(String)`.

  See Also:
    Constant Field Values

### PROBE_NAME_JNDI

    public static final java.lang.String PROBE_NAME_JNDI

  Name of the built-in JNDI probe. Used in `startProbeRecording(String, boolean)` and `stopProbeRecording(String)`.

  See Also:
    Constant Field Values

### PROBE_NAME_SERVLET

    public static final java.lang.String PROBE_NAME_SERVLET

  Name of the built-in servlet probe. Used in `startProbeRecording(String, boolean)` and `stopProbeRecording(String)`.

  See Also:
    Constant Field Values

### PROBE_NAME_FILE

    public static final java.lang.String PROBE_NAME_FILE

  Name of the built-in file probe. Used in `startProbeRecording(String, boolean)` and `stopProbeRecording(String)`.

  See Also:
    Constant Field Values

### PROBE_NAME_SOCKET

    public static final java.lang.String PROBE_NAME_SOCKET

  Name of the built-in socket probe. Used in `startProbeRecording(String, boolean)` and `stopProbeRecording(String)`.

  See Also:
    Constant Field Values

### PROBE_NAME_PROCESS

    public static final java.lang.String PROBE_NAME_PROCESS

  Name of the built-in process probe. Used in `startProbeRecording(String, boolean)` and `stopProbeRecording(String)`.

  See Also:
    Constant Field Values

Method Detail

### startCPURecording

    public static void startCPURecording(boolean reset)

  Starts 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 across pairs of invocations of `startCPURecording()` and `stopCPURecording()`.

### startCPURecording

    public static void startCPURecording(boolean reset,
                                         TrackingOptions trackingOptions)

  Starts 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 across pairs of invocations of `startCPURecording()` and `stopCPURecording()`.
    `trackingOptions` - an array of TRACKING_ constants or `null` for the previous state

### startProbeRecording

    public static void startProbeRecording(java.lang.String probeName,
                                           boolean events)

  Start recording data for a selected probe.

  Parameters:
    `probeName` - the name of the probe. For built-in probes, see the `PROBE_NAME` constants in this class. For custom probes, this name is `custom.n` where n is the one-based index of the custom probe.
    `events` - whether single events should be recorded
  See Also:
    `stopProbeRecording(String)`

### stopProbeRecording

    public static void stopProbeRecording(java.lang.String probeName)

  Stop recording data for a selected probe.

  Parameters:
    `probeName` - the name of the probe. For built-in probes, see the `PROBE_NAME` constants in this class. For custom probes, this name is `custom.n` where n is the one-based index of the custom probe.
  See Also:
    `startProbeRecording(String, boolean)`

### startProbeTracking

    public static void startProbeTracking(java.lang.String probeName,
                                          java.lang.String[] descriptions,
                                          ProbeObjectType objectType,
                                          ProbeValueType valueType)

  Start tracking selected elements for a selected probe. Probe recording must be switched on for the selected probe otherwise this method does not have any effect.

  Parameters:
    `probeName` - the name of the probe. For built-in probes, see the `PROBE_NAME` constants in this class. For custom probes, this name is `custom.n` where n is the one-based index of the custom probe.
    `descriptions` - the descriptions of the tracked elements. These are the strings that you see in the probe view in the JProfiler GUI. The sum of the selected elements will be tracked in a single graph. To get separate graphs, call this method multiple times.
    `objectType` - the type of the elements to be tracked
    `valueType` - the type of the values to be tracked

### stopProbeTracking

    public static void stopProbeTracking(java.lang.String probeName,
                                         java.lang.String[] description,
                                         ProbeObjectType objectType,
                                         ProbeValueType valueType)

  Stop tracking selected elements for a selected probe. This only has an effect if `startProbeTracking(String, String[], ProbeObjectType, ProbeValueType)` has been called before.

  Parameters:
    `probeName` - the name of the probe. For built-in probes, see the `PROBE_NAME` constants in this class. For custom probes, this name is `custom.n` where n is the one-based index of the custom probe.
    `description` - the descriptions of the tracked elements
    `objectType` - the type of the elements to be tracked
    `valueType` - the type of the values to be tracked

### stopCPURecording

    public static void stopCPURecording()

  Stops 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.

### startCallTracer

    public static void startCallTracer(int cap,
                                       boolean recordFiltered,
                                       boolean reset)

  Starts the call tracer. This method can be called repeatedly and alternatingly with `stopCallTracer()`.

  Parameters:
    `recordFiltered` - if `true`, calls into filtered classes will be recorded, too.
    `cap` - the maximum number of events to be recorded. A good default is 100000.
    `reset` - if `true` previously recorded calls will be cleared..

### stopCallTracer

    public static void stopCallTracer()

  Stops the call tracer. This method can be called after `startCallTracer()` has been called. However, you do not have to call it since the call tracer will stop automatically after the cap has been reached. The data will be delivered to the frontend afterwards if used in online mode.

### startMethodStatsRecording

    public static void startMethodStatsRecording()

  Starts method statistics recording. This will reset previously recorded method statistics. This method can be called repeatedly and alternatingly with `stopMethodStatsRecording()`.

### stopMethodStatsRecording

    public static void stopMethodStatsRecording()

  Stops method statistics recording.

### startMonitorRecording

    public static void startMonitorRecording()

  Start recording of monitor usage with default thresholds of 100 microseconds for blocking events and 100 ms for waiting events. This method can be called repeatedly and alternatingly with `stopMonitorRecording()`. Monitor profiling is switched off by default.

### startMonitorRecording

    public static void startMonitorRecording(int blockingThreshold,
                                             int waitingThreshold)

  Start recording of monitor usage. This method can be called repeatedly and alternatingly with `stopMonitorRecording()`. Monitor profiling is switched off by default.

  Parameters:
    `blockingThreshold` - the recording threshold for blocking events in microseconds.
    `waitingThreshold` - the recording threshold for waiting events in microseconds.

### stopMonitorRecording

    public static void stopMonitorRecording()

  Stop recording of monitor usage. This method can be called repeatedly and alternatingly with `startMonitorRecording()`. However, you do not have to call it since monitor profiling can run until the JVM exits.

### startAllocRecording

    public static void startAllocRecording(boolean reset)

  Starts 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.

### startAllocRecording

    public static void startAllocRecording(boolean reset,
                                           TrackingOptions trackingOptions)

  Starts 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.
    `trackingOptions` - the request tracking options

### stopAllocRecording

    public static void stopAllocRecording()

  Stops 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)

  Adds 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`

### addBookmark

    public static void addBookmark(java.lang.String description,
                                   java.awt.Color color,
                                   boolean dashed)

  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`
    `color` - the color to be used for drawing the bookmark. If `null` the default color will be used.
    `dashed` - if the line for drawing the bookmark should be dashed or not

### triggerThreadDump

    public static void triggerThreadDump()

  Trigger a thread dump.

### triggerHeapDump

    public static void triggerHeapDump()

  Trigger a heap dump. Calls `triggerHeapDump(HeapDumpOptions.DEFAULT)`.

  See Also:
    `triggerHeapDump(HeapDumpOptions)`

### triggerHeapDump

    public static void triggerHeapDump(HeapDumpOptions heapDumpOptions)

  Trigger a heap dump with the specified `heap dump options`. 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:
    `heapDumpOptions` - the options for the heap dump

### saveSnapshot

    public static void saveSnapshot(java.io.File file)

  Saves 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.

### startThreadProfiling

    public static void startThreadProfiling()

  Starts 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()

  Stops 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()

  Starts 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()

  Stops 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)

  Saves 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 of 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.

### enableTriggerGroup

    public static void enableTriggerGroup(boolean enabled,
                                          java.lang.String groupId)
                                   throws java.lang.IllegalArgumentException

  Enable or disable all triggers with a specified group ID. The group ID can be entered in the "Group ID" step of the trigger configuration wizard in the JProfiler GUI.

  Parameters:
    `enabled` - if the triggers should be enabled
    `groupId` - the group ID
  Throws:
    `java.lang.IllegalArgumentException` - if no trigger with the specified group ID exists

### enableTriggers

    public static void enableTriggers(boolean enabled)

  Enable or disable all triggers. The enabled/disabled state of the single triggers will not be lost, disabling all triggers with this method overrides the enabled/disabled state of the single triggers.

  Parameters:
    `enabled` - if the triggers should be enabled