Package com.oracle.bedrock.jprofiler

Class JProfiler

java.lang.Object

com.oracle.bedrock.jprofiler.JProfiler

public class JProfiler
extends Object

A factory for RemoteCallable to execute JProfiler functions in a JVM running with JProfiler enabled.

Copyright (c) 2016. All Rights Reserved. Oracle Corporation.
Oracle is a registered trademark of Oracle Corporation and/or its affiliates.

Author:

Jonathan Knight

Constructor Summary

Constructors

Constructor	Description
JProfiler()

Method Summary

Modifier and Type	Method	Description
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	addBookmark(String description)	Create a JProfiler that adds a bookmark at the current time.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	addBookmark(String description, Color color, boolean dashed)	Create a JProfiler that adds a bookmark at the current time.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	disableTriggerGroup(String groupId)	Create a JProfiler that disables all triggers with a specified group ID.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	disableTriggers()	Create a JProfiler that disables all triggers.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	enableTriggerGroup(String groupId)	Create a JProfiler that enables all triggers with a specified group ID.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	enableTriggers()	Create a JProfiler that enables all triggers.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	saveSnapshot(File file)	Create a JProfiler that saves a snapshot of all profiling data to disk.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	saveSnapshotOnExit(File file)	Create a JProfiler that saves a snapshot of all profiling data to disk when the VM shuts down.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startAllocRecording(boolean reset)	Create a JProfiler that starts recording of memory allocations.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startAllocRecording(boolean reset, com.jprofiler.api.agent.TrackingOptions options)	Create a JProfiler that starts recording of memory allocations.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startCallTracer(int cap, boolean recordFiltered, boolean reset)	Create a JProfiler that starts the call tracer.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startCPURecording(boolean reset)	Create a JProfiler that starts recording CPU data.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startCPURecording(boolean reset, com.jprofiler.api.agent.TrackingOptions options)	Create a JProfiler that starts recording CPU data.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startMethodStatsRecording()	Create a JProfiler that starts method statistics recording.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startMonitorRecording()	Create a JProfiler that starts recording of monitor usage with default thresholds of 100 microseconds for blocking events and 100 ms for waiting events.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startMonitorRecording(int blockingThreshold, int waitingThreshold)	Create a JProfiler that starts recording of monitor usage.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startProbeRecording(String probeName, boolean events)	Create a JProfiler that starts recording data for a selected probe.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startProbeRecording(String probeName, com.jprofiler.api.agent.ProbeRecordingOptions options)	Create a JProfiler that starts recording data for a selected probe.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startProbeTracking(String probeName, String[] descriptions, com.jprofiler.api.agent.ProbeObjectType objectType, com.jprofiler.api.agent.ProbeValueType valueType)	Create a JProfiler that starts tracking selected elements for a selected probe.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startThreadProfiling()	Create a JProfiler that starts recording of thread states and monitor usage.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	startVMTelemetryRecording()	Create a JProfiler that starts recording of VM telemetry data.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopAllocRecording()	Create a JProfiler that stops recording of memory allocations.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopCallTracer()	Create a JProfiler that stops the call tracer.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopCPURecording()	Create a JProfiler that stops CPU recording.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopMethodStatsRecording()	Create a JProfiler that stops method statistics recording.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopMonitorRecording()	Create a JProfiler that Stop recording of monitor usage.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopProbeRecording(String probeName)	Create a JProfiler that stops recording data for a selected probe.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopProbeTracking(String probeName, String[] descriptions, com.jprofiler.api.agent.ProbeObjectType objectType, com.jprofiler.api.agent.ProbeValueType valueType)	Create a JProfiler that stops tracking selected elements for a selected probe.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopThreadProfiling()	Create a JProfiler that stops recording of thread states and monitor usage.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	stopVMTelemetryRecording()	Create a JProfiler that stops recording of VM telemetry data.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	triggerHeapDump()	Create a JProfiler that triggers a heap dump.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	triggerHeapDump(com.jprofiler.api.agent.HeapDumpOptions options)	Create a JProfiler that triggers a heap dump.
static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void>	triggerThreadDump()	Create a JProfiler that triggers a thread dump.

Methods inherited from class java.lang.Object

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

Constructor Detail

JProfiler

public JProfiler()

Method Detail

addBookmark

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> addBookmark(String description)

Create a JProfiler that 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

Returns:

a JProfiler that adds a bookmark at the current time

addBookmark

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> addBookmark(String description,
                                                                                     Color color,
                                                                                     boolean dashed)

Create a JProfiler that 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

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 not

Returns:

a JProfiler that adds a bookmark at the current time

enableTriggers

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> enableTriggers()

Create a JProfiler that enables all triggers.

Returns:

a JProfiler that enables all triggers

disableTriggers

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> disableTriggers()

Create a JProfiler that disables all triggers. The enabled/disabled state of the single triggers will not be lost, disabling all triggers with this method overrides the enabled state of the single triggers

Returns:

a JProfiler that enables all triggers

enableTriggerGroup

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> enableTriggerGroup(String groupId)
                                                                                     throws IllegalArgumentException

Create a JProfiler that enables 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:

groupId - the group ID

Returns:

a JProfiler that enables all triggers with a specified group ID

Throws:

IllegalArgumentException

disableTriggerGroup

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> disableTriggerGroup(String groupId)
                                                                                      throws IllegalArgumentException

Create a JProfiler that disables 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:

groupId - the group ID

Returns:

a JProfiler that disables all triggers with a specified group ID

Throws:

IllegalArgumentException

saveSnapshot

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> saveSnapshot(File file)

Create a JProfiler that 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.

Parameters:

file - the file to which the snapshot should be saved

Returns:

a JProfiler that saves a snapshot of all profiling data to disk

saveSnapshotOnExit

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> saveSnapshotOnExit(File file)

Create a JProfiler that 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.

Returns:

a JProfiler that saves a snapshot of all profiling data to disk when the VM shuts down

startAllocRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startAllocRecording(boolean reset)

Create a JProfiler that starts recording of memory allocations. This method can be called repeatedly and alternately 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, any previously recorded profiling data will be discarded. If false, allocations within all pairs of invocations of this method and stopAllocRecording() will be recorded.

Returns:

a JProfiler that starts recording of memory allocations

startAllocRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startAllocRecording(boolean reset,
                                                                                             com.jprofiler.api.agent.TrackingOptions options)

Create a JProfiler that starts recording of memory allocations. This method can be called repeatedly and alternately 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, any previously recorded profiling data will be discarded. If false, allocations within all pairs of invocations of this method and stopAllocRecording() will be recorded.

options - the request tracking options

Returns:

a JProfiler that starts recording of memory allocations

stopAllocRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopAllocRecording()

Create a JProfiler that stops recording of memory allocations. This method can be called after or startAllocRecording(boolean)has been called. However, you do not have to call it since memory profiling can run until the JVM exits.

Returns:

a JProfiler that stops recording of memory allocations

startCallTracer

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startCallTracer(int cap,
                                                                                         boolean recordFiltered,
                                                                                         boolean reset)

Create a JProfiler that starts the call tracer. This method can be called repeatedly and alternately 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

Returns:

a JProfiler that starts the call tracer

stopCallTracer

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopCallTracer()

Create a JProfiler that stops the call tracer. This method can be called after startCallTracer(int, boolean, boolean) 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.

Returns:

a JProfiler that stops the call tracer

startCPURecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startCPURecording(boolean reset)

Create a JProfiler that starts recording CPU data. This method can be called repeatedly and alternately with stopCPURecording(). With these methods you can restrict CPU profiling to certain regions of your code.

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

Returns:

a JProfiler that starts recording CPU data

startCPURecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startCPURecording(boolean reset,
                                                                                           com.jprofiler.api.agent.TrackingOptions options)

Create a JProfiler that starts recording CPU data. This method can be called repeatedly and alternately with stopCPURecording(). With these methods you can restrict CPU profiling to certain regions of your code.

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

options - the request tracking options

Returns:

a JProfiler that starts recording CPU data

stopCPURecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopCPURecording()

Create a JProfiler that 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.

Returns:

a JProfiler that stops CPU recording

startMethodStatsRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startMethodStatsRecording()

Create a JProfiler that starts method statistics recording. This will reset previously recorded method statistics. This method can be called repeatedly and alternately with stopMethodStatsRecording()

Returns:

a JProfiler that starts method statistics recording

stopMethodStatsRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopMethodStatsRecording()

Create a JProfiler that stops method statistics recording.

Returns:

a JProfiler stops method statistics recording

startMonitorRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startMonitorRecording()

Create a JProfiler that starts 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 alternately with stopMonitorRecording(). Monitor profiling is switched off by default.

Returns:

a JProfiler that starts recording of monitor usage

startMonitorRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startMonitorRecording(int blockingThreshold,
                                                                                               int waitingThreshold)

Create a JProfiler that starts recording of monitor usage. This method can be called repeatedly and alternately 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

Returns:

a JProfiler

stopMonitorRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopMonitorRecording()

Create a JProfiler that Stop recording of monitor usage. This method can be called repeatedly and alternately with startMonitorRecording() or startMonitorRecording(int, int). However, you do not have to call it since monitor profiling can run until the JVM exits.

Returns:

a JProfiler

startProbeRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startProbeRecording(String probeName,
                                                                                             boolean events)

Create a JProfiler that starts recording data for a selected probe.

Parameters:

probeName - the name of the probe. For built-in probes, see the PROBE_NAME constants in the com.jprofiler.api.agent.Controller class. For custom probes, this name is custom.n where n is the one-based index of the custom probe

events - whether single events should be recorded for the "Events" view of the probe

Returns:

a JProfiler that starts recording data for a selected probe

startProbeRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startProbeRecording(String probeName,
                                                                                             com.jprofiler.api.agent.ProbeRecordingOptions options)

Create a JProfiler that starts recording data for a selected probe.

Parameters:

probeName - the name of the probe. For built-in probes, see the PROBE_NAME constants in the com.jprofiler.api.agent.Controller class. For custom probes, this name is custom.n where n is the one-based index of the custom probe

options - the request tracking options

Returns:

a JProfiler that starts recording data for a selected probe

stopProbeRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopProbeRecording(String probeName)

Create a JProfiler that stops recording data for a selected probe.

Parameters:

probeName - the name of the probe. For built-in probes, see the PROBE_NAME constants in the com.jprofiler.api.agent.Controller class. For custom probes, this name is custom.n where n is the one-based index of the custom probe

Returns:

a JProfiler stops recording data for a selected probe

startProbeTracking

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startProbeTracking(String probeName,
                                                                                            String[] descriptions,
                                                                                            com.jprofiler.api.agent.ProbeObjectType objectType,
                                                                                            com.jprofiler.api.agent.ProbeValueType valueType)

Create a JProfiler that starts 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 the com.jprofiler.api.agent.Controller 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 tracked

valueType - the type of the values to be tracked

Returns:

a JProfiler that starts tracking selected elements for a selected probe

stopProbeTracking

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopProbeTracking(String probeName,
                                                                                           String[] descriptions,
                                                                                           com.jprofiler.api.agent.ProbeObjectType objectType,
                                                                                           com.jprofiler.api.agent.ProbeValueType valueType)

Create a JProfiler that stops 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 the com.jprofiler.api.agent.Controller 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 tracked

valueType - the type of the values to be tracked

Returns:

a JProfiler that stops tracking selected elements for a selected probe

startThreadProfiling

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startThreadProfiling()

Create a JProfiler that starts recording of thread states and monitor usage. This method can be called repeatedly and alternately with stopThreadProfiling(). For an offline session, thread profiling is switched on by default.

Returns:

a JProfiler that starts recording of thread states and monitor usage

stopThreadProfiling

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopThreadProfiling()

Create a JProfiler that stops recording of thread states and monitor usage. This method can be called repeatedly and alternately with startThreadProfiling(). However, you do not have to call it since thread profiling can run until the JVM exits.

Returns:

a JProfiler that stops recording of thread states and monitor usage

startVMTelemetryRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> startVMTelemetryRecording()

Create a JProfiler that starts recording of VM telemetry data. This method can be called repeatedly and alternately with stopVMTelemetryRecording(). For an offline session, VM telemetry recording is switched on by default.

Returns:

a JProfiler that starts recording of VM telemetry data

stopVMTelemetryRecording

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> stopVMTelemetryRecording()

Create a JProfiler that stops recording of VM telemetry data. This method can be called repeatedly and alternately with startVMTelemetryRecording(). However, you do not have to call it since VM telemetry recording can run until the JVM exits.

Returns:

a JProfiler that stops recording of VM telemetry data

triggerHeapDump

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> triggerHeapDump()

Create a JProfiler that triggers a heap dump. If you want to analyze a heap dump with the heap walker in a snapshot saved with the saveSnapshot(File) method, you should call this method from your source code at an appropriate time.

Returns:

a JProfiler that triggers a heap dump

triggerHeapDump

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> triggerHeapDump(com.jprofiler.api.agent.HeapDumpOptions options)

Create a JProfiler that triggers a heap dump. If you want to analyze a heap dump with the heap walker in a snapshot saved with the saveSnapshot(File) method, you should call this method from your source code at an appropriate time.

Parameters:

options - the options controlling the heap dump

Returns:

a JProfiler that triggers a heap dump

triggerThreadDump

public static com.oracle.bedrock.runtime.concurrent.RemoteCallable<Void> triggerThreadDump()

Create a JProfiler that triggers a thread dump.

Returns:

a JProfiler that triggers a thread dump