Interface RemoteControllerMBean
This is JProfiler's MBean interface. The MBean can be used with tools like JConsole or in your own application.
For direct calls from your code in the same JVM, rather use the com.jprofiler.api.controller.Controller
class.
To learn how to access the JProfiler MBean in a different profiled JVM programmatically, have a look at the
$JPROFILER_HOME/api/samples/mbean
example project.
Open the gradle build file build.gradle
in an editor for instructions on how to run it.
All classes in this package are contained in $JPROFILER_HOME/api/jprofiler-mbean.jar
.
The MBean API is also available as a dependency. In the snippets below, "VERSION"
should be replaced with the corresponding JProfiler version.
<dependency>
<groupId>com.jprofiler</groupId>
<artifactId>jprofiler-mbean</artifactId>
<version>VERSION</version>
</dependency>
<repository>
<id>ej-technologies</id>
<url>https://maven.ej-technologies.com/repository</url>
</repository>
Gradle
repositories {
maven {
url 'https://maven.ej-technologies.com/repository'
}
}
dependencies {
classpath group: 'com.jprofiler', name: 'jprofiler-mbean', version: 'VERSION'
}
-
Method Summary
Modifier and TypeMethodDescriptionvoid
addBookmark
(String description) Adds a bookmark at the current time.convertToAbsolutePath
(String path) Return an absolute path for the given path.void
enableTriggerGroup
(boolean enabled, 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".saveSnapshot
(String file) Saves a snapshot of all profiling data to disk.void
saveSnapshotOnExit
(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
Starts algorithmic complexity recording for all previously configured methods.void
startCPURecording
(boolean reset) Starts recording CPU data.void
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
(String probeName, boolean events, boolean specialRecording) Start recording data for a selected probe.void
Starts recording of thread states and monitor usage.void
Starts recording of VM telemetry data.void
Stops recording of memory allocations.void
Stops algorithmic complexity recording and prepares data for snapshot.void
Stops CPU recording.void
Stop recording of monitor usage.void
stopProbeRecording
(String probeName) Stop recording data for a selected probe.void
Stops recording of thread states and monitor usage.void
Stops recording of VM telemetry data.void
Triggers a heap dump.void
triggerHeapDumpWithOptions
(boolean fullGc, boolean onlyRecorded, boolean primitiveData, boolean calculateRetainedSizes) Triggers a heap dump.void
Trigger a dump of current monitors and locks.void
Trigger a thread dump.
-
Method Details
-
startCPURecording
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
- iftrue
, any previously accumulated CPU profiling data will be discarded. Iffalse
, CPU data will be accumulated across pairs of invocations ofstartCPURecording()
andstopCPURecording()
.
-
stopCPURecording
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. -
startAllocRecording
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
- iftrue
, any previously recorded profiling data will be discarded. Iffalse
, allocations within all pairs of invocations ofstartAllocRecording()
andstopAllocRecording()
will be recorded.
-
stopAllocRecording
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
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
-
triggerHeapDumpWithOptions
void triggerHeapDumpWithOptions(boolean fullGc, boolean onlyRecorded, 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 thesaveSnapshot
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
- iftrue
, a full garbage collection will be performed.onlyRecorded
- iftrue
, only objects recorded between startAllocRecording and stopAllocRecording will be included in the dump.primitiveData
- iftrue
, primitive data will also be recorded. This has no effect for JVMTI 1.0 (Java 5).calculateRetainedSizes
- iftrue
, the retained sizes of all objects will be calculated. This requiresfullGc=true
.
-
triggerHeapDump
void triggerHeapDump()Triggers a heap dump. Calls triggerHeapDumpWithOptions(true, false, true, true). -
markHeap
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
Saves a snapshot of all profiling data to disk. This is especially important for offline profiling. You should choose the standard extension.jps
for thefile
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 uniquefile
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.- Returns:
- the absolute path where the snapshot was saved. This can be in a temporary directory if the working directory is not writable.
-
startThreadProfiling
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
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
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
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
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 thefile
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.
-
enableTriggerGroup
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 enabledgroupId
- the group ID- Throws:
IllegalArgumentException
- if no trigger with the specified group ID exists
-
enableTriggers
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
-
startComplexityRecording
void startComplexityRecording()Starts algorithmic complexity recording for all previously configured methods. -
stopComplexityRecording
void stopComplexityRecording()Stops algorithmic complexity recording and prepares data for snapshot. -
startMonitorRecording
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
void startMonitorRecording(int blockedThreshold, int waitingThreshold) Start recording of monitor usage. This method can be called repeatedly and alternatingly withstopMonitorRecording()
. Monitor profiling is switched off by default.- Parameters:
blockedThreshold
- the recording threshold for blocking events in microseconds.waitingThreshold
- the recording threshold for waiting events in microseconds.
-
stopMonitorRecording
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. -
triggerThreadDump
void triggerThreadDump()Trigger a thread dump. -
triggerMonitorDump
void triggerMonitorDump()Trigger a dump of current monitors and locks. -
startProbeRecording
Start recording data for a selected probe.- Parameters:
probeName
- the name of the probe. For built-in probes, see thePROBE_NAME
constants incom.jprofiler.api.controller.Controller
. For embedded and injected probes, the class name of the probe is used. For script probes, this name isscript.n
where n is the one-based index of the script 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
Stop recording data for a selected probe.- Parameters:
probeName
- the name of the probe. For built-in probes, see thePROBE_NAME
constants incom.jprofiler.api.controller.Controller
. The string values can be obtained when clicking on the "Constant Field Values" link in the JavaDoc of the fields. For embedded and injected probes, the class name of the probe is used. For script probes, this name isscript.n
where n is the one-based index of the script probe.
-
convertToAbsolutePath
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 thesaveSnapshot(String)
method. The returned path will have file separators of the remote machine.
-