com.jprofiler.api.agent.mbean

Class RemoteController

java.lang.Object

com.jprofiler.api.agent.mbean.RemoteController

All Implemented Interfaces:

RemoteControllerMBean

public class RemoteController
extends java.lang.Object
implements RemoteControllerMBean

This is JProfiler's MBean implementation. For direct calls from your code in the same JVM, rather use the Controller class.

Constructor Summary

Constructors

Constructor and Description
RemoteController()

Method Summary

Modifier and Type	Method and Description
void	addBookmark(java.lang.String description) Adds a bookmark at the current time.
java.lang.String	convertToAbsolutePath(java.lang.String path) Return an absolute path for the given path.
void	enableTriggerGroup(boolean enabled, java.lang.String groupId) Enable or disable all triggers with a specified group ID.
void	enableTriggers(boolean enabled) Enable or disable all triggers.
void	markHeap() Mark all objects currently on the heap as "old".
void	saveSnapshot(java.lang.String file) Saves a snapshot of all profiling data to disk.
void	saveSnapshotOnExit(java.lang.String file) Saves a snapshot of all profiling data to disk when the VM shuts down.
void	startAllocRecording(boolean reset) Starts recording of memory allocations.
void	startComplexityRecording() Starts algorithmic complexity recording for all previously configured methods.
void	startCPURecording(boolean reset) Starts recording CPU data.
void	startMethodStatsRecording() Starts method statistics recording.
void	startMonitorRecording() Start recording of monitor usage with default thresholds of 100 microseconds for blocking events and 100 ms for waiting events.
void	startMonitorRecording(int blockedThreshold, int waitingThreshold) Start recording of monitor usage.
void	startProbeRecording(java.lang.String probeName, boolean events, boolean specialRecording) Start recording data for a selected probe.
void	startThreadProfiling() Starts recording of thread states and monitor usage.
void	startVMTelemetryRecording() Starts recording of VM telemetry data.
void	stopAllocRecording() Stops recording of memory allocations.
void	stopComplexityRecording() Stops algorithmic complexity recording and prepares data for snapshot.
void	stopCPURecording() Stops CPU recording.
void	stopMethodStatsRecording() Stops method statistics recording.
void	stopMonitorRecording() Stop recording of monitor usage.
void	stopProbeRecording(java.lang.String probeName) Stop recording data for a selected probe.
void	stopThreadProfiling() Stops recording of thread states and monitor usage.
void	stopVMTelemetryRecording() Stops recording of VM telemetry data.
void	triggerHeapDump() Triggers a heap dump.
void	triggerHeapDumpWithOptions(boolean fullGc, boolean selectRecorded, boolean primitiveData, boolean calculateRetainedSizes) Triggers a heap dump.
void	triggerThreadDump() Trigger a thread dump.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RemoteController

public RemoteController()

Method Detail

startCPURecording

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

Specified by:

startCPURecording in interface RemoteControllerMBean

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

stopCPURecording

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

Specified by:

stopCPURecording in interface RemoteControllerMBean

startAllocRecording

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

Specified by:

startAllocRecording in interface RemoteControllerMBean

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

Specified by:

stopAllocRecording in interface RemoteControllerMBean

addBookmark

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

Specified by:

addBookmark in interface RemoteControllerMBean

Parameters:

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

triggerHeapDumpWithOptions

public void triggerHeapDumpWithOptions(boolean fullGc,
                                       boolean selectRecorded,
                                       boolean primitiveData,
                                       boolean calculateRetainedSizes)

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

Specified by:

triggerHeapDumpWithOptions in interface RemoteControllerMBean

Parameters:

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

selectRecorded - if true, only objects recorded between startAllocRecording and stopAllocRecording will be included in the dump.

primitiveData - if true, primitive data will also be recorded. This has no effect for JVMTI 1.0 (Java 5).

calculateRetainedSizes - if true, the retained sizes of all objects will be calculated. This requires fullGc=true.

triggerHeapDump

public void triggerHeapDump()

Triggers a heap dump. Calls triggerHeapDumpWithOptions(true, false, true, true).

Specified by:

triggerHeapDump in interface RemoteControllerMBean

See Also:

RemoteControllerMBean.triggerHeapDumpWithOptions(boolean, boolean, boolean, boolean)

markHeap

public void markHeap()

Description copied from interface: RemoteControllerMBean

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

Specified by:

markHeap in interface RemoteControllerMBean

saveSnapshot

public void saveSnapshot(java.lang.String 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.

Specified by:

saveSnapshot in interface RemoteControllerMBean

Parameters:

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

startThreadProfiling

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

Specified by:

startThreadProfiling in interface RemoteControllerMBean

stopThreadProfiling

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

Specified by:

stopThreadProfiling in interface RemoteControllerMBean

startVMTelemetryRecording

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

Specified by:

startVMTelemetryRecording in interface RemoteControllerMBean

stopVMTelemetryRecording

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

Specified by:

stopVMTelemetryRecording in interface RemoteControllerMBean

saveSnapshotOnExit

public void saveSnapshotOnExit(java.lang.String 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 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.

Specified by:

saveSnapshotOnExit in interface RemoteControllerMBean

Parameters:

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

enableTriggerGroup

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

Specified by:

enableTriggerGroup in interface RemoteControllerMBean

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

Specified by:

enableTriggers in interface RemoteControllerMBean

Parameters:

enabled - if the triggers should be enabled

startMethodStatsRecording

public void startMethodStatsRecording()

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

Specified by:

startMethodStatsRecording in interface RemoteControllerMBean

stopMethodStatsRecording

public void stopMethodStatsRecording()

Stops method statistics recording.

Specified by:

stopMethodStatsRecording in interface RemoteControllerMBean

startComplexityRecording

public void startComplexityRecording()

Description copied from interface: RemoteControllerMBean

Starts algorithmic complexity recording for all previously configured methods.

Specified by:

startComplexityRecording in interface RemoteControllerMBean

stopComplexityRecording

public void stopComplexityRecording()

Description copied from interface: RemoteControllerMBean

Stops algorithmic complexity recording and prepares data for snapshot.

Specified by:

stopComplexityRecording in interface RemoteControllerMBean

startMonitorRecording

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

Specified by:

startMonitorRecording in interface RemoteControllerMBean

startMonitorRecording

public void startMonitorRecording(int blockedThreshold,
                                  int waitingThreshold)

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

Specified by:

startMonitorRecording in interface RemoteControllerMBean

Parameters:

blockedThreshold - the recording threshold for blocking events in microseconds.

waitingThreshold - the recording threshold for waiting events in microseconds.

stopMonitorRecording

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

Specified by:

stopMonitorRecording in interface RemoteControllerMBean

triggerThreadDump

public void triggerThreadDump()

Trigger a thread dump.

Specified by:

triggerThreadDump in interface RemoteControllerMBean

startProbeRecording

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

Start recording data for a selected probe.

Specified by:

startProbeRecording in interface RemoteControllerMBean

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 - determines whether events should be recorded for the "Events" view of the probe. Has no effect for probes that do not have an "Events" view.

specialRecording - determines whether special recordings for the probe should be switched on. For the "JDBC" probe, this controls connection leak tracking. Has no effect for other probes without special recording.

stopProbeRecording

public void stopProbeRecording(java.lang.String probeName)

Stop recording data for a selected probe.

Specified by:

stopProbeRecording in interface RemoteControllerMBean

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.

convertToAbsolutePath

public java.lang.String convertToAbsolutePath(java.lang.String path)

Return an absolute path for the given path. Relative paths will be resolved against the working directory of the profiled JVM. With this method you can determine where a snapshot will be saved to when a relative path is passed to the RemoteControllerMBean.saveSnapshot(String) method. The returned path will have file separators of the remote machine.

Specified by:

convertToAbsolutePath in interface RemoteControllerMBean