Class Controller
- java.lang.Object
-
- com.jprofiler.api.controller.Controller
-
public class Controller extends java.lang.ObjectUse this class to influence the run time behaviour of JProfiler.
OverheadWhen 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 useIf you would like to access the functionality in this class from the command line, use the
Offline profilingjpcontrollercommand line executable that attaches to the JProfiler MBean which is registered for every profiled application. For more information, invokejpcontroller -help.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 forController.The
JAR file and dependency$JPROFILER_HOME/api/samples/offlineexample project shows how to perform offline profiling. Open the gradle build filebuild.gradlein an editor for instructions on how to run it.All classes in this package are contained in
Maven$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.
Gradle<dependency> <groupId>com.jprofiler</groupId> <artifactId>jprofiler-controller</artifactId> <version>VERSION</version> </dependency> <repository> <id>ej-technologies</id> <url>https://maven.ej-technologies.com/repository</url> </repository>repositories { maven { url 'https://maven.ej-technologies.com/repository' } } dependencies { classpath group: 'com.jprofiler', name: 'jprofiler-controller', version: 'VERSION' }
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.StringPROBE_NAME_ALL_CUSTOMIdentifier for all custom probes.static java.lang.StringPROBE_NAME_CASSANDRAName of the built-in Cassandra probe.static java.lang.StringPROBE_NAME_CLASS_LOADERName of the built-in class loader probe.static java.lang.StringPROBE_NAME_EXCEPTIONName of the built-in Exception probe.static java.lang.StringPROBE_NAME_FILEName of the built-in file probe.static java.lang.StringPROBE_NAME_HBASEName of the built-in Cassandra probe.static java.lang.StringPROBE_NAME_HTTP_CLIENTName of the built-in HTTP client probe.static java.lang.StringPROBE_NAME_HTTP_SERVERName of the built-in http server probe.static java.lang.StringPROBE_NAME_JDBCName of the built-in JDBC probe.static java.lang.StringPROBE_NAME_JMSName of the built-in JMS probe.static java.lang.StringPROBE_NAME_JNDIName of the built-in JNDI probe.static java.lang.StringPROBE_NAME_MONGO_DBName of the built-in MongoDB probe.static java.lang.StringPROBE_NAME_PERSISTENCEName of the built-in persistence probe.static java.lang.StringPROBE_NAME_PROCESSName of the built-in process probe.static java.lang.StringPROBE_NAME_RMIName of the built-in RMI probe.static java.lang.StringPROBE_NAME_SOCKETName of the built-in socket probe.static java.lang.StringPROBE_NAME_WSName of the built-in web service probe.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static voidaddBookmark(java.lang.String description)Adds a bookmark at the current time.static voidaddBookmark(java.lang.String description, int color, boolean dashed)Add a bookmark at the current time.static voidenableTriggerGroup(boolean enabled, java.lang.String groupId)Enable or disable all triggers with a specified group ID.static voidenableTriggers(boolean enabled)Enable or disable all triggers.static voidmarkHeap()Mark all objects currently on the heap as "old".static voidsaveSnapshot(java.io.File file)Saves a snapshot of all profiling data to disk.static voidsaveSnapshotOnExit(java.io.File file)Saves a snapshot of all profiling data to disk when the VM shuts down.static voidstartAllocRecording(boolean reset)Starts recording of memory allocations.static voidstartAllocRecording(boolean reset, TrackingOptions trackingOptions)Starts recording of memory allocations.static voidstartCallTracer(int cap, boolean recordFiltered, boolean reset)Starts the call tracer.static voidstartComplexityRecording()Starts algorithmic complexity recording for all previously configured methods.static voidstartCPURecording(boolean reset)Starts recording CPU data.static voidstartCPURecording(boolean reset, TrackingOptions trackingOptions)Starts recording CPU data.static voidstartMonitorRecording()Start recording of monitor usage with default thresholds of 100 microseconds for blocking events and 100 ms for waiting events.static voidstartMonitorRecording(int blockingThreshold, int waitingThreshold)Start recording of monitor usage.static voidstartProbeRecording(java.lang.String probeName, boolean events)Start recording data for a selected probe.static voidstartProbeRecording(java.lang.String probeName, ProbeRecordingOptions recordingOptions)Start recording data for a selected probe.static voidstartProbeTracking(java.lang.String probeName, java.lang.String[] descriptions, ProbeObjectType objectType, ProbeValueType valueType)Start tracking selected elements for a selected probe.static voidstartThreadProfiling()Starts recording of thread states and monitor usage.static voidstartVMTelemetryRecording()Starts recording of VM telemetry data.static voidstopAllocRecording()Stops recording of memory allocations.static voidstopCallTracer()Stops the call tracer.static voidstopComplexityRecording()Stops algorithmic complexity recording and prepares data for snapshot.static voidstopCPURecording()Stops CPU recording.static voidstopMonitorRecording()Stop recording of monitor usage.static voidstopProbeRecording(java.lang.String probeName)Stop recording data for a selected probe.static voidstopProbeTracking(java.lang.String probeName, java.lang.String[] description, ProbeObjectType objectType, ProbeValueType valueType)Stop tracking selected elements for a selected probe.static voidstopThreadProfiling()Stops recording of thread states and monitor usage.static voidstopVMTelemetryRecording()Stops recording of VM telemetry data.static voidtriggerHeapDump()Trigger a heap dump.static voidtriggerHeapDump(HeapDumpOptions heapDumpOptions)Trigger a heap dump with the specifiedheap dump options.static voidtriggerThreadDump()Trigger a thread dump.
-
-
-
Field Detail
-
PROBE_NAME_PERSISTENCE
public static final java.lang.String PROBE_NAME_PERSISTENCE
Name of the built-in persistence probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(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 instartProbeRecording(String, boolean)andstopProbeRecording(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 instartProbeRecording(String, boolean)andstopProbeRecording(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 instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_MONGO_DB
public static final java.lang.String PROBE_NAME_MONGO_DB
Name of the built-in MongoDB probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_CASSANDRA
public static final java.lang.String PROBE_NAME_CASSANDRA
Name of the built-in Cassandra probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_HBASE
public static final java.lang.String PROBE_NAME_HBASE
Name of the built-in Cassandra probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_HTTP_CLIENT
public static final java.lang.String PROBE_NAME_HTTP_CLIENT
Name of the built-in HTTP client probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_RMI
public static final java.lang.String PROBE_NAME_RMI
Name of the built-in RMI probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_WS
public static final java.lang.String PROBE_NAME_WS
Name of the built-in web service probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_HTTP_SERVER
public static final java.lang.String PROBE_NAME_HTTP_SERVER
Name of the built-in http server probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(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 instartProbeRecording(String, boolean)andstopProbeRecording(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 instartProbeRecording(String, boolean)andstopProbeRecording(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 instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_CLASS_LOADER
public static final java.lang.String PROBE_NAME_CLASS_LOADER
Name of the built-in class loader probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_EXCEPTION
public static final java.lang.String PROBE_NAME_EXCEPTION
Name of the built-in Exception probe. Used instartProbeRecording(String, boolean)andstopProbeRecording(String).- See Also:
- Constant Field Values
-
PROBE_NAME_ALL_CUSTOM
public static final java.lang.String PROBE_NAME_ALL_CUSTOM
Identifier for all custom probes. If used instartProbeRecording(String, boolean)andstopProbeRecording(String)all custom probes will be started or stopped.- 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 withstopCPURecording(). With these methods you can restrict CPU profiling to certain regions of your code.- Parameters:
reset- iftrueand cpu recording is currently switched off, any previously accumulated CPU profiling data will be discarded. Iffalse, CPU data will be accumulated across pairs of invocations ofstartCPURecording()andstopCPURecording().
-
startCPURecording
public static void startCPURecording(boolean reset, TrackingOptions trackingOptions)Starts recording CPU data. This method can be called repeatedly and alternatingly withstopCPURecording(). With these methods you can restrict CPU profiling to certain regions of your code.- Parameters:
reset- iftrueand cpu recording is currently switched off, any previously accumulated CPU profiling data will be discarded. Iffalse, CPU data will be accumulated across pairs of invocations ofstartCPURecording()andstopCPURecording().trackingOptions- an array of TRACKING_ constants ornullfor the previous state
-
stopCPURecording
public static void stopCPURecording()
Stops CPU recording. This method can be called afterstartCPURecording()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(java.lang.String probeName, boolean events)Start recording data for a selected probe. For more information and a more general signature seestartProbeRecording(String, ProbeRecordingOptions).
-
startProbeRecording
public static void startProbeRecording(java.lang.String probeName, ProbeRecordingOptions recordingOptions)Start recording data for a selected probe.- Parameters:
probeName- the name of the probe. For built-in probes, see thePROBE_NAMEconstants in this class. For embedded and injected probes, the class name of the probe is used. For script probes, this name isscript.nwhere 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(String),ProbeRecordingOptions
-
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 thePROBE_NAMEconstants in this class. For embedded and injected probes, the class name of the probe is used. For script probes, this name isscript.nwhere n is the one-based index of the script 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 thePROBE_NAMEconstants in this class. For embedded and injected probes, the class name of the probe is used. For script probes, this name isscript.nwhere 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 trackedvalueType- 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 ifstartProbeTracking(String, String[], ProbeObjectType, ProbeValueType)has been called before.- Parameters:
probeName- the name of the probe. For built-in probes, see thePROBE_NAMEconstants in this class. For embedded and injected probes, the class name of the probe is used. For script probes, this name isscript.nwhere n is the one-based index of the script probe.description- the descriptions of the tracked elementsobjectType- the type of the elements to be trackedvalueType- 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 withstopCallTracer().- Parameters:
recordFiltered- iftrue, calls into filtered classes will be recorded, too.cap- the maximum number of events to be recorded. A good default is 100000.reset- iftruepreviously recorded calls will be cleared..
-
stopCallTracer
public static void stopCallTracer()
Stops the call tracer. This method can be called afterstartCallTracer()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 withstopMonitorRecording(). 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 withstopMonitorRecording(). 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 withstartMonitorRecording(). 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 withstopAllocRecording(). 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- iftrueand allocation recording is currently switched off, any previously recorded profiling data will be discarded. Iffalse, allocations within all pairs of invocations ofstartAllocRecording()andstopAllocRecording()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 withstopAllocRecording(). 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- iftrueand allocation recording is currently switched off, any previously recorded profiling data will be discarded. Iffalse, allocations within all pairs of invocations ofstartAllocRecording()andstopAllocRecording()will be recorded.trackingOptions- the request tracking options
-
stopAllocRecording
public static void stopAllocRecording()
Stops recording of memory allocations. This method can be called afterstartAllocRecording()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 benull
-
addBookmark
public static void addBookmark(java.lang.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 benullcolor- the RGB color to be used for drawing the bookmark, for example0xFF0000.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. CallstriggerHeapDump(HeapDumpOptions.DEFAULT).- See Also:
triggerHeapDump(HeapDumpOptions)
-
triggerHeapDump
public static void triggerHeapDump(HeapDumpOptions heapDumpOptions)
Trigger a heap dump with the specifiedheap dump options. If you want to analyze a heap dump with the heap walker in a snapshot saved with thesaveSnapshotmethod, 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(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.jpsfor thefileparameter, 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 uniquefileparameters 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 withstopThreadProfiling(). 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 withstartThreadProfiling(). 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 withstopVMTelemetryRecording(). 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 withstartVMTelemetryRecording(). 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.jpsfor thefileparameter, 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.IllegalArgumentExceptionEnable 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 enabledgroupId- 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
-
-