com.yourkit.api
Class Controller

java.lang.Object
  com.yourkit.api.Controller

public final class Controller
extends java.lang.Object

The class provides API to control profiling of Java applications.

Field Summary

static java.lang.String	DEFAULT_FILTERS Default filters
static java.lang.String	DEFAULT_WALLTIME_SPEC Default wall time configuration (see http://www.yourkit.com/docs/90/help/times.jsp) to be passed as a parameter of startCPUProfiling(long, String, String)

Constructor Summary

Controller()
Creates a contoller to profile application itself, i.e.

Controller(java.lang.String host, int port)
Creates a contoller to profile application given host it is running and the port its profiler agent listens to.

Method Summary

void	advanceGeneration(java.lang.String description) Advance current object generation number.
java.lang.String	captureMemorySnapshot() This method is just a convenient replacement of captureSnapshot(ProfilingModes.SNAPSHOT_WITH_HEAP)
java.lang.String	captureSnapshot(long snapshotFlags) Captures snapshot, i.e.
void	clearAllocationData() Clear recorded allocations.
void	clearCPUData() Clear CPU profiling data.
void	clearExceptions() Clear collected exception telemetry.
void	clearMonitorData() Clear monitor profiling data.
void	disableExceptionTelemetry() Stop collecting exception telemetry.
void	disableStackTelemetry() Stop collecting thread stack and state telemetry.
void	enableExceptionTelemetry() Start collecting exception telemetry.
void	enableStackTelemetry() Start collecting thread stack and state telemetry.
long[]	forceGC()
java.lang.String	getHost()
int[]	getPeriodicSnapshotTrigger() Deprecated. Use getPeriodicSnapshotTriggerStatus()
PeriodicSnapshotTriggerStatus	getPeriodicSnapshotTriggerStatus() Get current status of periodic snapshot trigger - see detail in Help.
int	getPort()
long	getStatus() Get current profiling status.
int	getUsedMemoryThreshold() Get current status of on-low-memory snapshot trigger - see detail in Help.
static void	main(java.lang.String[] args) The Controller provides a command line interface to some of its functionality.
void	setPeriodicSnapshotTrigger(int periodSec) Deprecated. Use setPeriodicSnapshotTrigger(int, long) instead
void	setPeriodicSnapshotTrigger(int periodSec, long snapshotFlags) Setup periodic snapshot trigger - see detail in Help..
void	setUsedMemoryThreshold(int usedHeapPercent) Setup on-low-memory snapshot trigger - see detail in Help.
void	startAllocationRecording(boolean recordEachEnabled, int recordEach, boolean sizeLimitEnabled, int sizeLimit) Start object allocation recording.
void	startCPUProfiling(long mode, java.lang.String filters) Same as startCPUProfiling(mode, filters, DEFAULT_WALLTIME_SPEC)
void	startCPUProfiling(long mode, java.lang.String filters, java.lang.String wallTimeSpec) Start CPU profiling.
void	startMonitorProfiling() Start monitor profiling.
void	stopAllocationRecording() Stop allocation recording.
void	stopCPUProfiling() Stop CPU profiling.
void	stopMonitorProfiling() Stop monitor profiling.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_FILTERS

public static final java.lang.String DEFAULT_FILTERS

Default filters

See Also:

Constant Field Values

DEFAULT_WALLTIME_SPEC

public static final java.lang.String DEFAULT_WALLTIME_SPEC

Default wall time configuration (see http://www.yourkit.com/docs/90/help/times.jsp) to be passed as a parameter of startCPUProfiling(long, String, String)

See Also:

Constant Field Values

Constructor Detail

Controller

public Controller()
           throws java.lang.Exception

Creates a contoller to profile application itself, i.e. to profile the JVM running the code that invokes this constructor.

The application should be launched with profiler agent; see Help topic "Running applications with profiler" for details.

Throws:

java.lang.Exception - if application is not launched with the profiler agent

See Also:

Controller(String, int)

Controller

public Controller(java.lang.String host,
                  int port)
           throws java.lang.Exception

Creates a contoller to profile application given host it is running and the port its profiler agent listens to.

The application to profile should be launched with profiler agent; see Help topic "Running applications with profiler" for details.

Note that the constructor attempts to connect to the specified application. If connection fails, an exception is thrown.

Parameters:

host - name of host where application being profiled is running. Cannot be null.

port - port profiler agent listens on. Must be in range 1-65535.

Throws:

java.lang.Exception - if the profiled application cannot be connected. Possible reasons:

• there's no Java application at host started with profiler agent listening on port
• profiled application has terminated
• host:port is not accessible
• I/O error

See Also:

Controller()

Method Detail

getHost

public java.lang.String getHost()

Returns:

name of host where controlled profiled application is running. The method never returns null.

getPort

public int getPort()

Returns:

port profiler agent listens on.

captureSnapshot

public java.lang.String captureSnapshot(long snapshotFlags)
                                 throws java.lang.Exception

Captures snapshot, i.e. writes profiling information to file.

If profiling is being performed (e.g. started with startCPUProfiling(long, String), startMonitorProfiling() or startAllocationRecording(boolean, int, boolean, int), or remotely), it will not stop after the capture. To stop it, explicitly call stopCPUProfiling(), stopMonitorProfiling() or stopAllocationRecording().

Parameters:

snapshotFlags - defines what kind of snapshot to capture:

• ProfilingModes.SNAPSHOT_WITHOUT_HEAP - capture snapshot with all the recorded information (CPU profiling, monitors, telemetry), but without the heap dump.
• ProfilingModes.SNAPSHOT_WITH_HEAP - capture snapshot with all the recorded information (CPU profiling, monitors, telemetry, allocations), as well as with the heap dump.
• ProfilingModes.SNAPSHOT_HPROF - capture snapshot in HPROF format (heap dump only).

Returns:

absolute path to the captured snapshot. Note that if a remote application is profiled (see Controller(String, int)), the returned path will be in the file system of the remote host.

Throws:

java.lang.Exception - if capture failed. The possible reasons are:

• profiled application has terminated
• the profiler agent cannot capture snapshot for some reason
• I/O error

captureMemorySnapshot

public java.lang.String captureMemorySnapshot()
                                       throws java.lang.Exception

This method is just a convenient replacement of captureSnapshot(ProfilingModes.SNAPSHOT_WITH_HEAP)

Throws:

java.lang.Exception

startAllocationRecording

public void startAllocationRecording(boolean recordEachEnabled,
                                     int recordEach,
                                     boolean sizeLimitEnabled,
                                     int sizeLimit)
                              throws java.lang.Exception

Start object allocation recording. Note that recordEach and sizeLimit parameters are applied independently. For example, the following call will record allocation of each 10th object OR if object size is 100K or more: controller.startAllocationRecording(true, 10, true, 100*1024)

Parameters:

recordEachEnabled - whether recordEach parameter should be applied

recordEach - record each recordEach'th object allocation; ignored if recordEachEnabled==false

sizeLimitEnabled - whether sizeLimit parameter should be applied

sizeLimit - record allocation of object with shallow size >= sizeLimit; the value is specified in bytes; ignored if sizeLimitEnabled==false

Throws:

java.lang.Exception - if failed. Possible reasons:

• allocation recording is already running
• profiled application has terminated
• I/O error

See Also:

captureMemorySnapshot(), stopAllocationRecording()

stopAllocationRecording

public void stopAllocationRecording()
                             throws java.lang.Exception

Stop allocation recording. If allocation recording is not running, this method takes no action.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

startAllocationRecording(boolean, int, boolean, int), captureMemorySnapshot()

clearAllocationData

public void clearAllocationData()
                         throws java.lang.Exception

Clear recorded allocations. If allocation recording is not running, this method takes no action. Note: when allocation recording starts, collected allocation data is cleared automatically, so you do not have to explicitly call this method in that case.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

startAllocationRecording(boolean, int, boolean, int), stopAllocationRecording(), captureMemorySnapshot()

startCPUProfiling

public void startCPUProfiling(long mode,
                              java.lang.String filters)
                       throws java.lang.Exception

Same as startCPUProfiling(mode, filters, DEFAULT_WALLTIME_SPEC)

Throws:

java.lang.Exception

startCPUProfiling

public void startCPUProfiling(long mode,
                              java.lang.String filters,
                              java.lang.String wallTimeSpec)
                       throws java.lang.Exception

Start CPU profiling.

Parameters:

mode - ProfilingModes.CPU_SAMPLING or
ProfilingModes.CPU_TRACING or
ProfilingModes.CPU_SAMPLING | ProfilingModes.CPU_J2EE or
ProfilingModes.CPU_TRACING | ProfilingModes.CPU_J2EE

filters - specify filters to be applied in runtime (read about the filters at http://www.yourkit.com/docs/90/help/filters.jsp). The value is used with ProfilingModes.CPU_TRACING only; with ProfilingModes.CPU_SAMPLING the value is ignored (just pass an empty string). For tracing, specify a string containing '\n'-separated list of class name patterns to be filtered. Prepend class name pattern with '+' to avoid its filtering. Wildcards are accepted ('*'). More methods are profiled, bigger the overhead. Pass null to read filter settings from <profiled application's user home>/.yjp/.filters. Pass an empty string to use no filters, i.e. to trace all methods (not recommended due to high overhead). Pass DEFAULT_FILTERS to use default filters.

wallTimeSpec - specify for which methods wall time should be measured instead of CPU time (read about time measurement at http://www.yourkit.com/docs/90/help/times.jsp). Pass null to read wall time settings from <profiled application's user home>/.yjp/.walltime. Pass an empty string not to measure wall time for any methods. Pass DEFAULT_WALLTIME_SPEC to use default settings.

Throws:

java.lang.Exception - if failed. Possible reasons:

• CPU profiling is already running
• profiled application has terminated
• I/O error

See Also:

captureSnapshot(long), stopCPUProfiling(), clearCPUData(), DEFAULT_FILTERS

stopCPUProfiling

public void stopCPUProfiling()
                      throws java.lang.Exception

Stop CPU profiling. If CPU profiling is not running, this method takes no action.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

startCPUProfiling(long, String), captureSnapshot(long), clearCPUData()

clearCPUData

public void clearCPUData()
                  throws java.lang.Exception

Clear CPU profiling data. If CPU profiling is not running, this method takes no action. Note: when CPU profiling starts, collected CPU profiling data is cleared automatically, so you do not have to explicitly call this method in that case.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

startCPUProfiling(long, String), stopCPUProfiling(), captureSnapshot(long)

startMonitorProfiling

public void startMonitorProfiling()
                           throws java.lang.Exception

Start monitor profiling.

Throws:

java.lang.Exception - if failed. Possible reasons:

• monitor profiling is already running
• profiled application has terminated
• I/O error

See Also:

captureSnapshot(long), stopMonitorProfiling(), clearMonitorData()

stopMonitorProfiling

public void stopMonitorProfiling()
                          throws java.lang.Exception

Stop monitor profiling. If monitor profiling is not running, this method takes no action.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

startMonitorProfiling(), captureSnapshot(long), clearCPUData()

clearMonitorData

public void clearMonitorData()
                      throws java.lang.Exception

Clear monitor profiling data. If monitor profiling is not running, this method takes no action. Note: when monitor profiling starts, collected monitor profiling data is cleared automatically, so you do not have to explicitly call this method in that case.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

startMonitorProfiling(), stopMonitorProfiling(), captureSnapshot(long)

enableStackTelemetry

public void enableStackTelemetry()
                          throws java.lang.Exception

Start collecting thread stack and state telemetry. If this telemetry is already being collected, the method takes no action.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

captureSnapshot(long), disableStackTelemetry()

disableStackTelemetry

public void disableStackTelemetry()
                           throws java.lang.Exception

Stop collecting thread stack and state telemetry. If this telemetry is not being collected, the method takes no action.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

enableStackTelemetry(), captureSnapshot(long)

enableExceptionTelemetry

public void enableExceptionTelemetry()
                              throws java.lang.Exception

Start collecting exception telemetry. If this telemetry is already being collected, the method takes no action.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

captureSnapshot(long), disableExceptionTelemetry()

disableExceptionTelemetry

public void disableExceptionTelemetry()
                               throws java.lang.Exception

Stop collecting exception telemetry. If this telemetry is not being collected, the method takes no action.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

enableExceptionTelemetry(), captureSnapshot(long)

clearExceptions

public void clearExceptions()
                     throws java.lang.Exception

Clear collected exception telemetry.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

enableExceptionTelemetry(), disableExceptionTelemetry(), captureSnapshot(long)

advanceGeneration

public void advanceGeneration(java.lang.String description)
                       throws java.lang.Exception

Advance current object generation number.

Since that moment, all newly created objects will belong to the new generation.

Note that generations are also automatically advanced on capturing snapshots.

Parameters:

description - optional description associated with the generation

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

forceGC

public long[] forceGC()
               throws java.lang.Exception

Returns:

array of 2 elements: [0] - size of objects in heap before GC, bytes, [1] - size of objects in heap after GC, bytes

Throws:

java.lang.Exception

getStatus

public long getStatus()
               throws java.lang.Exception

Get current profiling status. The status is a bit mask. The following code snippet demonstrates how to check its bits:

long status = controller.getStatus();

if ((status & ProfilingModes.ALLOCATION_RECORDING) != 0) {
  System.out.println("Allocation recording is on");
}
else {
  System.out.println("Allocation recording is off");
}

if ((status & ProfilingModes.CPU_TRACING) == ProfilingModes.CPU_TRACING) {
  System.out.println("CPU profiling is on (tracing)");
}
else if ((status & ProfilingModes.CPU_SAMPLING) != 0) {
  System.out.println("CPU profiling is on (sampling)");
}
else {
  System.out.println("CPU profiling is off");
}

if ((status & ProfilingModes.MONITOR_PROFILING) != 0) {
  System.out.println("Monitor profiling is on");
}
else {
  System.out.println("Monitor profiling is off");
}
   

Returns:

a bit mask to check against ProfilingModes

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

setPeriodicSnapshotTrigger

public void setPeriodicSnapshotTrigger(int periodSec,
                                       long snapshotFlags)
                                throws java.lang.Exception

Setup periodic snapshot trigger - see detail in Help..

Parameters:

periodSec - snapshot capture period in seconds; -1 to disable the trigger

snapshotFlags - defines what kind of snapshot to capture:

• ProfilingModes.SNAPSHOT_WITHOUT_HEAP - capture snapshot with all the recorded information (CPU profiling, monitors, telemetry), but without the heap dump.
• ProfilingModes.SNAPSHOT_WITH_HEAP - capture snapshot with all the recorded information (CPU profiling, monitors, telemetry, allocations), as well as with the heap dump.
• ProfilingModes.SNAPSHOT_HPROF - capture snapshot in HPROF format (heap dump only).

If trigger is to be disabled (periodSec is -1), pass 0 as the value of snapshotFlags.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

getPeriodicSnapshotTrigger()

setPeriodicSnapshotTrigger

public void setPeriodicSnapshotTrigger(int periodSec)
                                throws java.lang.Exception

Deprecated. Use setPeriodicSnapshotTrigger(int, long) instead

Same as setPeriodicSnapshotTrigger(periodSec, ProfilingModes.SNAPSHOT_WITH_HEAP)

Throws:

java.lang.Exception

getPeriodicSnapshotTrigger

public int[] getPeriodicSnapshotTrigger()
                                 throws java.lang.Exception

Deprecated. Use getPeriodicSnapshotTriggerStatus()

Get current status of periodic snapshot trigger - see detail in Help.

Returns:

int array of 2 elements: [0] - period in seconds, -1 if the trigger is disabled; [1] - not used

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

setPeriodicSnapshotTrigger(int)

getPeriodicSnapshotTriggerStatus

public PeriodicSnapshotTriggerStatus getPeriodicSnapshotTriggerStatus()
                                                               throws java.lang.Exception

Get current status of periodic snapshot trigger - see detail in Help.

Returns:

never null

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

setPeriodicSnapshotTrigger(int)

setUsedMemoryThreshold

public void setUsedMemoryThreshold(int usedHeapPercent)
                            throws java.lang.Exception

Setup on-low-memory snapshot trigger - see detail in Help.

Parameters:

usedHeapPercent - memory snapshot will be captured when usedHeapPercent% of the heap memory is used. The value should not be bigger than 99%. To disable the trigger, specify 0.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

getUsedMemoryThreshold()

getUsedMemoryThreshold

public int getUsedMemoryThreshold()
                           throws java.lang.Exception

Get current status of on-low-memory snapshot trigger - see detail in Help.

Returns:

used memory heap percent at which on-low-memory snapshot will be triggered, or 0 if the trigger is disabled. Note: after on-low-memory snapshot is captured, the trigger becomes disabled. If you need to re-enable it, do it explicitly.

Throws:

java.lang.Exception - if failed. Possible reasons:

• profiled application has terminated
• I/O error

See Also:

setUsedMemoryThreshold(int)

main

public static void main(java.lang.String[] args)
                 throws java.lang.Exception

The Controller provides a command line interface to some of its functionality. To get usage instructions, launch this command: "java -jar yjp-controller-api-redist.jar"

Throws:

java.lang.Exception