Package com.jprofiler.api.controller

Class Controller

java.lang.Object
com.jprofiler.api.controller.Controller
public class Controller extends Object

Use this class to influence the run time behaviour of JProfiler.

Overhead

When executing your application without JProfiler, all calls into this class will quietly do nothing without any overhead, because the implementations of the methods are empty. When the JProfiler agent is present, these methods will be instrumented and wired up with the agent.

Interactive use

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

Offline profiling

While you can use the controller during interactive profiling sessions, it is most useful for offline profiling. "Offline" refers to the fact that the JProfiler GUI does not have to be connected to the profiled process while profiling data is being recorded and snapshots are saved.

Please read the "Offline profiling" chapter in the documentation (directory $JPROFILER_HOME/doc) for an overview on how to use the Controller API and consult the javadoc for Controller.

The $JPROFILER_HOME/api/samples/offline example project shows how to perform offline profiling. Open the gradle build file build.gradle in an editor for instructions on how to run it.

JAR file and dependency

All classes in this package are contained in $JPROFILER_HOME/api/jprofiler-controller.jar. The controller API is also available as a dependency. In the snippets below, "VERSION" should be replaced with the corresponding JProfiler version.

Maven 

 <dependency>
   <groupId>com.jprofiler</groupId>
   <artifactId>jprofiler-controller</artifactId>
   <version>VERSION</version>
 </dependency>
Gradle 

 dependencies {
   classpath group: 'com.jprofiler', name: 'jprofiler-controller', version: 'VERSION'
 }

  • Field Details

  • Method Details

    • 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 and cpu recording is currently switched off, 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 and cpu recording is currently switched off, 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

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

    • startProbeRecording

      public static void startProbeRecording(String probeName, boolean events)
      Start recording data for a selected probe. For more information and a more general signature see startProbeRecording(String, ProbeRecordingOptions).

    • startProbeRecording

      public static void startProbeRecording(String probeName, ProbeRecordingOptions recordingOptions)
      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 embedded and injected probes, the class name of the probe is used. For script probes, this name is script.n where n is the one-based index of the script probe.
      recordingOptions - determines whether special recordings for the probe should be switched on
      See Also:

    • stopProbeRecording

      public static void stopProbeRecording(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 embedded and injected probes, the class name of the probe is used. For script probes, this name is script.n where n is the one-based index of the script probe.
      See Also:

    • startProbeTracking

      public static void startProbeTracking(String probeName, 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 embedded and injected probes, the class name of the probe is used. For script probes, this name is script.n where n is the one-based index of the script 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(String probeName, 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 embedded and injected probes, the class name of the probe is used. For script probes, this name is script.n where n is the one-based index of the script 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

    • startComplexityRecording

      public static void startComplexityRecording()
      Starts algorithmic complexity recording for all previously configured methods.

    • stopComplexityRecording

      public static void stopComplexityRecording()
      Stops algorithmic complexity recording and prepares data for snapshot.

    • 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:
      cap - the maximum number of events to be recorded. A good default is 100000.
      recordFiltered - if true, calls into filtered classes will be recorded, too.
      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.

    • 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 and allocation recording is currently switched off, 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 and allocation recording is currently switched off, 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(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(String description, int 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 RGB color to be used for drawing the bookmark, for example 0xFF0000.
      dashed - if the line for drawing the bookmark should be dashed or not

    • triggerThreadDump

      public static void triggerThreadDump()
      Trigger a thread dump.

    • triggerThreadDump

      public static void triggerThreadDump(String label)
      Trigger a thread dump with an optional label for identification.
      Parameters:
      label - A string parameter used to label the dump. Can be null.

    • triggerAllObjectsDump

      public static void triggerAllObjectsDump()
      Triggers a dump of all objects on the heap to be displayed it in the "All objects" view.

    • triggerAllObjectsDump

      public static void triggerAllObjectsDump(String label)
      Triggers a dump of all objects on the heap to be displayed it in the "All objects" view with an optional label for identification.
      Parameters:
      label - A string parameter used to label the dump. Can be null.

    • triggerMonitorDump

      public static void triggerMonitorDump()
      Trigger a dump of current monitors and locks.

    • triggerHeapDump

      public static void triggerHeapDump()
      Trigger a heap dump. Calls triggerHeapDump(HeapDumpOptions.DEFAULT).
      See Also:

    • 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

    • markHeap

      public static void markHeap()
      Mark all objects currently on the heap as "old". In the next heap dump, you can then distinguish between objects created before and after this method was called. This action has much less overhead than a full heap dump

    • saveSnapshot

      public static void saveSnapshot(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, 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(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, String groupId) throws 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:
      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

    • triggerMBeanSnapshot

      public static void triggerMBeanSnapshot(String label, String regexp)
      Triggers an MBean snapshot with an optional label. The recorded MBeans con be optionally filtered with a regular expression.
      Parameters:
      label - An optional label for the snapshot. Can be null.
      regexp - An optional regular expression for filtering MBeans based on the canonical name. Can be null.