public class Controller
extends java.lang.Object
bin/agent.jar
in
your JProfiler installation directory. Call these static methods from your source code
to influence the run time behaviour of JProfiler.
The agent API is also available as a dependency, please replace "VERSION" in the snippets below with the corresponding JProfiler version:
Maven
<dependency>
<groupId>com.jprofiler</groupId>
<artifactId>jprofiler-agent</artifactId>
<version>VERSION</version>
</dependency>
<repository>
<id>ej-technologies</id>
<url>http://maven.ej-technologies.com/repository</url>
</repository>
Ivy
<dependency org="com.jprofiler" name="jprofiler-agent" rev="VERSION" />
<ibiblio name="ej-technologies" usepoms="true" m2compatible="true"
root="http://maven.ej-technologies.com/repository" />
Gradle
repositories {
maven {
url 'http://maven.ej-technologies.com/repository'
}
}
dependencies {
classpath group: 'com.jprofiler', name: 'jprofiler-agent', version: 'VERSION'
}
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
.
Modifier and Type | Class and Description |
---|---|
static class |
Controller.BookmarkColor
Color class for bookmarks.
|
Modifier and Type | Field and Description |
---|---|
static java.lang.String |
PROBE_NAME_CASSANDRA
Name of the built-in Cassandra probe.
|
static java.lang.String |
PROBE_NAME_CLASS_LOADER
Name of the built-in class loader probe.
|
static java.lang.String |
PROBE_NAME_EXCEPTION
Name of the built-in Exception probe.
|
static java.lang.String |
PROBE_NAME_FILE
Name of the built-in file probe.
|
static java.lang.String |
PROBE_NAME_HBASE
Name of the built-in Cassandra 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_MONGO_DB
Name of the built-in MongoDB 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_RMI
Name of the built-in RMI 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.
|
static java.lang.String |
PROBE_NAME_WS
Name of the built-in web service probe.
|
Modifier and Type | Method and Description |
---|---|
static void |
addBookmark(java.lang.String description)
Adds a bookmark at the current time.
|
static void |
addBookmark(java.lang.String description,
Controller.BookmarkColor 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 |
markHeap()
Mark all objects currently on the heap as "old".
|
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 |
startComplexityRecording()
Starts algorithmic complexity recording for all previously configured methods.
|
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 |
startProbeRecording(java.lang.String probeName,
ProbeRecordingOptions recordingOptions)
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 |
stopComplexityRecording()
Stops algorithmic complexity recording and prepares data for snapshot.
|
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.
|
public static final java.lang.String PROBE_NAME_PERSISTENCE
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_JDBC
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_JMS
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_JNDI
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_MONGO_DB
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_CASSANDRA
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_HBASE
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_RMI
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_WS
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_SERVLET
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_FILE
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_SOCKET
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_PROCESS
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_CLASS_LOADER
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static final java.lang.String PROBE_NAME_EXCEPTION
startProbeRecording(String, boolean)
and stopProbeRecording(String)
.public static void startCPURecording(boolean reset)
stopCPURecording()
. With these methods you can restrict
CPU profiling to certain regions of your code.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()
.public static void startComplexityRecording()
public static void stopComplexityRecording()
public static void startCPURecording(boolean reset, TrackingOptions trackingOptions)
stopCPURecording()
. With these methods you can restrict
CPU profiling to certain regions of your code.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 statepublic static void startProbeRecording(java.lang.String probeName, boolean events)
startProbeRecording(String, ProbeRecordingOptions)
.public static void startProbeRecording(java.lang.String probeName, ProbeRecordingOptions recordingOptions)
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.recordingOptions
- determines whether special recordings for the probe should be switched onstopProbeRecording(String)
,
ProbeRecordingOptions
public static void stopProbeRecording(java.lang.String probeName)
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.startProbeRecording(String, boolean)
public static void startProbeTracking(java.lang.String probeName, java.lang.String[] descriptions, ProbeObjectType objectType, ProbeValueType valueType)
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 trackedvalueType
- the type of the values to be trackedpublic static void stopProbeTracking(java.lang.String probeName, java.lang.String[] description, ProbeObjectType objectType, ProbeValueType valueType)
startProbeTracking(String, String[], ProbeObjectType, ProbeValueType)
has been called before.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 elementsobjectType
- the type of the elements to be trackedvalueType
- the type of the values to be trackedpublic static void stopCPURecording()
startCPURecording()
has been called.
However, you do not have to call it since CPU profiling can run until the
JVM exits.public static void startCallTracer(int cap, boolean recordFiltered, boolean reset)
stopCallTracer()
.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..public static void stopCallTracer()
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.public static void startMethodStatsRecording()
stopMethodStatsRecording()
.public static void stopMethodStatsRecording()
public static void startMonitorRecording()
stopMonitorRecording()
. Monitor profiling is switched off
by default.public static void startMonitorRecording(int blockingThreshold, int waitingThreshold)
stopMonitorRecording()
. Monitor profiling is switched off
by default.blockingThreshold
- the recording threshold for blocking events in microseconds.waitingThreshold
- the recording threshold for waiting events in microseconds.public static void stopMonitorRecording()
startMonitorRecording()
. However, you do not have to call it since
monitor profiling can run until the JVM exits.public static void startAllocRecording(boolean reset)
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.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.public static void startAllocRecording(boolean reset, TrackingOptions trackingOptions)
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.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 optionspublic static void stopAllocRecording()
startAllocRecording()
has been called.
However, you do not have to call it since memory profiling can run until the
JVM exits.public static void addBookmark(java.lang.String description)
description
- the name of the bookmark, may also be null
public static void addBookmark(java.lang.String description, Controller.BookmarkColor color, boolean dashed)
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 notpublic static void triggerThreadDump()
public static void triggerHeapDump()
triggerHeapDump(HeapDumpOptions.DEFAULT)
.triggerHeapDump(HeapDumpOptions)
public static void triggerHeapDump(HeapDumpOptions heapDumpOptions)
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.
heapDumpOptions
- the options for the heap dumppublic static void markHeap()
public static void saveSnapshot(java.io.File file)
.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.
file
- the file to which the snapshot should be saved.public static void startThreadProfiling()
stopThreadProfiling()
. For an offline session, thread
profiling is switched on by default.public static void stopThreadProfiling()
startThreadProfiling()
. However, you do not have to call it since
thread profiling can run until the JVM exits.public static void startVMTelemetryRecording()
stopVMTelemetryRecording()
. For an offline session, VM telemetry
recording is switched on by default.public static void stopVMTelemetryRecording()
startVMTelemetryRecording()
. However, you do not have to call it since
VM telemetry recording can run until the JVM exits.public static void saveSnapshotOnExit(java.io.File file)
.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.
file
- the file to which the snapshot should be saved.public static void enableTriggerGroup(boolean enabled, java.lang.String groupId) throws java.lang.IllegalArgumentException
enabled
- if the triggers should be enabledgroupId
- the group IDjava.lang.IllegalArgumentException
- if no trigger with the specified group ID existspublic static void enableTriggers(boolean enabled)
enabled
- if the triggers should be enabled