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

Constructor Summary

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

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: write profiling information to file.
long[]	forceGC()
java.lang.String	getHost()
int	getPort()
long	getStatus() Get current profiling status.
static void	main(java.lang.String[] args) The Controller provides a command line interface to some of its functionality.
void	startAllocationRecording(long mode) Start object allocation recording.
void	startCPUProfiling(long mode, java.lang.String filters) Start CPU profiling.
void	startMonitorProfiling() Start monitor profiling (requires that the profiled application runs on Java 5 or newer)
void	stopAllocationRecording() Stop allocation recording.
void	stopCPUProfiling() Stop CPU profiling.
void	stopMonitorProfiling() Stop monitor profiling (requires that the profiled application runs on Java 5 or newer).

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

com.sun.*
java.*
javax.*
sun.*
jrockit.*

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 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 connect to the application fails

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: write profiling information to file.

If some profiling is being performed (e.g. started with startCPUProfiling(long, String), startMonitorProfiling() or startAllocationRecording(long), or remotely), it won't stop after the capture. To stop it, explicitly call stopCPUProfiling(), stopMonitorProfiling() or stopAllocationRecording().

Parameters:

snapshotFlags - defines how much information should be stored:

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

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:

• there's no Java application with properly configured profiler agent listening on port at host
• profiled application has terminated
• agent cannot capture snapshot for some reason

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(long mode)
                              throws java.lang.Exception

Start object allocation recording.

Parameters:

mode - ProfilingModes.ALLOCATION_RECORDING_ALL or
ProfilingModes.ALLOCATION_RECORDING_ADAPTIVE

Throws:

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

• there's no Java application with properly configured profiler agent listening on port at host
• allocation recording is already running
• profiled application has terminated

See Also:

captureMemorySnapshot(), stopCPUProfiling()

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. The possible reasons are:

• there's no Java application with properly configured profiler agent listening on port at host
• profiled application has terminated

startCPUProfiling

public void startCPUProfiling(long mode,
                              java.lang.String filters)
                       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 - string containing '\n'-separated list of classes whose methods should not be profiled. Wildcards are accepted ('*'). More methods are profiled, bigger the overhead. The filters are used with ProfilingModes.CPU_TRACING only; with ProfilingModes.CPU_SAMPLING the value is ignored. If null or empty string passed, all methods will be profiled (not recommended due to high overhead). For example, you can pass DEFAULT_FILTERS.

Throws:

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

• there's no Java application with properly configured profiler agent listening on port at host
• specified profiling mode is not supported by the JVM of the profiled application, e.g. tracing is supported with Java 5 and newer and thus is not available with Java 1.4.
• CPU profiling is already running
• profiled application has terminated
• agent cannot capture snapshot for some reason

See Also:

captureSnapshot(long), stopCPUProfiling(), 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. The possible reasons are:

• there's no Java application with properly configured profiler agent listening on port at host
• profiled application has terminated

See Also:

startCPUProfiling(long, String), captureSnapshot(long)

startMonitorProfiling

public void startMonitorProfiling()
                           throws java.lang.Exception

Start monitor profiling (requires that the profiled application runs on Java 5 or newer)

Throws:

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

• there's no Java application with properly configured profiler agent listening on port at host
• specified profiling mode is not supported by the JVM of the profiled application, e.g. tracing is supported with Java 5 and newer and thus is not available with Java 1.4.
• CPU profiling is already running
• profiled application has terminated
• agent cannot capture snapshot for some reason

See Also:

captureSnapshot(long), stopMonitorProfiling()

stopMonitorProfiling

public void stopMonitorProfiling()
                          throws java.lang.Exception

Stop monitor profiling (requires that the profiled application runs on Java 5 or newer). If monitor profiling is not running, this method takes no action.

Throws:

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

• there's no Java application with properly configured profiler agent listening on port at host
• profiled application has terminated

See Also:

startMonitorProfiling(), captureSnapshot(long)

advanceGeneration

public void advanceGeneration(java.lang.String description)

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.

Generations are only available if the profiled application runs on Java 5 or newer.

Parameters:

description - optional description associated with the generation

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 following code snippet demonstrates how to use this method:

long status = controller.getStatus();

if ((status & ProfilingModes.ALLOCATION_RECORDING_ADAPTIVE) != 0) {
  System.out.println("Allocation recording is on (adaptive)");
}
else if ((status & ProfilingModes.ALLOCATION_RECORDING_ALL) != 0) {
  System.out.println("Allocation recording is on (all objects)");
}
else {
  System.out.println("Allocation recording is off");
}

if ((status & ProfilingModes.CPU_TRACING) != 0) {
  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

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 -cp yjp-controller-api-redist.jar com.yourkit.api.Controller"

Throws:

java.lang.Exception