Package com.yourkit.api.controller.v2

Class Controller

java.lang.Object
com.yourkit.api.controller.v2.Controller
public final class Controller extends Object
The class provides API to control profiling of Java applications.

  • Method Details

    • newBuilder

      @NotNull public static Controller.Builder newBuilder()
      Returns:
      New builder to construct the Controller.

    • advanceGeneration

      public void advanceGeneration(@Nullable String description) throws IOException

      Advances object generation number.

      Parameters:
      description - Optional description associated with the generation.
      Throws:
      IOException

    • capturePerformanceSnapshot

      @NotNull public String capturePerformanceSnapshot() throws IOException
      Captures snapshot without heap data.
      Returns:
      Absolute file path of the captured snapshot file. If a remote application is being profiled, then the path is in the file system of the remote host.
      Throws:
      IOException

    • captureMemorySnapshot

      @NotNull public String captureMemorySnapshot() throws IOException
      Captures snapshot with heap data.
      Returns:
      Absolute file path of the captured snapshot file. If a remote application is being profiled, then the path is in the file system of the remote host.
      Throws:
      IOException

    • captureHprofSnapshot

      @NotNull public String captureHprofSnapshot() throws IOException
      Captures snapshot with heap data in HPROF format.
      Returns:
      Absolute file path of the captured snapshot file. If a remote application is being profiled, then the path is in the file system of the remote host.
      Throws:
      ControllerException - If JVM does not support HPROF snapshots.
      IOException

    • getAddress

      @NotNull public InetSocketAddress getAddress()
      Returns:
      Profiler agent address.

    • forceGc

      public void forceGc() throws IOException
      Forces garbage collection in the profiled application.
      Throws:
      IOException

    • getJvmTelemetry

      @NotNull public JvmTelemetry getJvmTelemetry() throws IOException
      Returns:
      Current JvmTelemetry.
      Throws:
      IOException

    • getStatus

      @NotNull public Status getStatus() throws IOException
      Returns:
      Status of the profiler agent. You can also use getStatus counter-part from the HTTP API.
      Throws:
      IOException

    • getTotalCreatedObjects

      @NotNull public TotalCreatedObjects getTotalCreatedObjects() throws IOException
      Returns:
      Statistics of object allocation profiling.
      Throws:
      IOException
      See Also:

    • getProbeActivityModes

      @NotNull public Map<? extends String,? extends ProbeActivityMode> getProbeActivityModes() throws IOException
      Returns:
      The mapping of probe class names to the ProbeActivityMode.
      Throws:
      IOException

    • setProbeActivityModes

      public void setProbeActivityModes(@NotNull Map<? extends String,? extends ProbeActivityMode> probeClassName2Mode) throws IOException
      Changes probe activity modes of the specified probes.
      Parameters:
      probeClassName2Mode - Mapping of probe class names to ProbeActivityMode. It specifies the probes whose mode should be changed. If a probe is not present in the mapping, its mode will remain unchanged.
      Throws:
      IOException

    • getTriggers

      @NotNull public String getTriggers() throws IOException
      Obtains current trigger description.
      Returns:
      Description of triggers. The returned value is never null. If there are no triggers, an empty string will be returned.
      Throws:
      IOException

    • setTriggers

      public void setTriggers(@NotNull String triggers, boolean append) throws IOException, ControllerException
      Sets triggers.
      Parameters:
      triggers - Description of trigger(s). See detail here
      append - If TRUE, the triggers will be added to the currently existing triggers, if FALSE - will replace them.
      Throws:
      ControllerException - Possible reasons:
      • The trigger description is invalid.
      IOException

    • resetAllocationProfiling

      public void resetAllocationProfiling() throws IOException
      Clears recorded allocations.

      Note: when allocation profiling starts, collected allocation data is cleared automatically, so you do not have to explicitly call this method in that case.

      Throws:
      IOException

    • resetCpuProfiling

      public void resetCpuProfiling() throws IOException
      Clears current results of CPU profiling in any mode, be it sampling, tracing or call counting.

      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:
      IOException

    • clearEventTables

      public void clearEventTables(@NotNull List<? extends String> tableNames) throws IOException
      Clears event table(s) by name. If the specified tables have dependent tables, they will be cleared too.
      Throws:
      IOException

    • resetExceptionProfiling

      public void resetExceptionProfiling() throws IOException
      Clears recorded exceptions.

      Note: when exception profiling starts, recorded exceptions are cleared automatically, so you do not have to explicitly call this method in that case.

      Throws:
      IOException

    • resetMonitorProfiling

      public void resetMonitorProfiling() throws IOException
      Clears monitor profiling data.

      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:
      IOException

    • startAllocationProfiling

      public void startAllocationProfiling(@NotNull AllocationProfilingSettings settings) throws IOException, ControllerException
      Starts object allocation profiling. The method clears previously recorded allocation data.

      If allocation profiling is already running, it will reset and start anew.

      Throws:
      ControllerException - Possible reasons:
      • Allocation profiling has been disabled for the profiled application with startup options 'disable_alloc' or 'disable_all'.
      IOException

    • startAsyncSamplingCpu

      public void startAsyncSamplingCpu(@NotNull CpuProfilingSettings settings) throws IOException, ControllerException

      Starts asynchronous CPU sampling.

      Asynchronous sampling is a low-overhead profiling mode that does not suffer from the Safepoint bias problem. It features HotSpot-specific APIs to collect stack traces. It works with OpenJDK, Oracle JDK and other Java runtimes based on the HotSpot JVM.

      Time measurement accuracy is high for methods consuming CPU cycles. Methods like sleep() and wait() which don't consume much CPU time will not be shown in the results.

      If CPU profiling is already running, it will reset and start anew.

      Parameters:
      settings - CPU sampling settings. Pass null to use the profiled application's settings, or pass your custom settings as a non-null string.
      Throws:
      ControllerException - Possible reasons:
      • Asynchronous sampling is not supported by the JVM.
      IOException

    • startAsyncSamplingPeriodic

      public void startAsyncSamplingPeriodic(@NotNull CpuProfilingSettings settings) throws IOException, ControllerException

      Starts asynchronous periodic sampling.

      Asynchronous sampling is a low overhead profiling mode that does not suffer from the Safepoint bias problem. It features HotSpot-specific APIs to collect stack traces. It works with OpenJDK, Oracle JDK and other Java runtimes based on the HotSpot JVM.

      If CPU profiling is already running, it will reset and start anew.

      Parameters:
      settings - CPU sampling settings. Pass null to use the profiled application's settings, or pass your custom settings as a non-null string.
      Throws:
      ControllerException - Possible reasons:
      • Asynchronous sampling is not supported by the JVM.
      IOException

    • stopAllocationProfiling

      public void stopAllocationProfiling() throws IOException
      Stops allocation profiling. If allocation profiling is not running, this method has no effect.
      Throws:
      IOException

    • startCallCounting

      public void startCallCounting() throws IOException, ControllerException
      Starts CPU call counting. Unlike other CPU profiling modes, only method invocations are counted, neither call stacks nor times are gathered.

      If CPU profiling is already running, it will reset and start anew.

      Throws:
      ControllerException - Possible reasons:
      • Call counting (along with CPU tracing) has been disabled for the profiled application with startup options 'disable_tracing' or 'disable_all'.
      IOException

    • startExceptionProfiling

      public void startExceptionProfiling() throws IOException
      Starts exception profiling. If exception profiling is not running when this method is called, previous exception profiling data is cleared. If exception profiling is already running, this method has no effect.
      Throws:
      IOException

    • stopExceptionProfiling

      public void stopExceptionProfiling() throws IOException
      Stops exception profiling. If exception profiling is not running, this method has no effect.
      Throws:
      IOException

    • startMonitorProfiling

      public void startMonitorProfiling() throws IOException
      Starts monitor profiling. If monitor profiling is not running when this method is called, previous monitor profiling data is cleared. If monitor profiling is already running, this method has no effect.
      Throws:
      IOException

    • stopMonitorProfiling

      public void stopMonitorProfiling() throws IOException
      Stops monitor profiling. If monitor profiling is not running, this method has no effect.
      Throws:
      IOException

    • startSampling

      public void startSampling(@NotNull CpuProfilingSettings settings) throws IOException, ControllerException
      Starts CPU sampling. When sampling is used, the profiler periodically queries stacks and times of running threads to estimate the slowest parts of the code. In this mode, method invocation counts are not available.

      If CPU profiling is already running, it will reset and start anew.

      Throws:
      IOException
      ControllerException

    • startThreadProfiling

      public void startThreadProfiling(@NotNull ThreadProfilingSettings settings) throws IOException
      Starts thread profiling. If thread profiling is already running, this method has no effect.
      Throws:
      IOException

    • stopThreadProfiling

      public void stopThreadProfiling() throws IOException
      Stops thread profiling. If thread profiling is not running, this method has no effect.
      Throws:
      IOException

    • resetThreadProfiling

      public void resetThreadProfiling() throws IOException
      Clears the collected thread profiling data and continues the thread profiling if it is active.

      Note: when thread profiling starts, collected thread profiling results are cleared automatically, so you do not have to explicitly call this method in that case.

      Throws:
      IOException

    • startTelemetry

      public void startTelemetry() throws IOException
      Starts collecting performance telemetry. If telemetry is already being collected, the method has no effect.
      Throws:
      IOException

    • stopTelemetry

      public void stopTelemetry() throws IOException
      Stops collecting performance telemetry. If telemetry is not being collected, the method has no effect.
      Throws:
      IOException

    • resetTelemetry

      public void resetTelemetry() throws IOException
      Clears telemetry.

      Note: when telemetry starts, collected telemetry is cleared automatically, so you do not have to explicitly call this method in that case.

      Throws:
      IOException

    • startTracing

      public void startTracing(@NotNull CpuProfilingSettings settings) throws IOException, ControllerException
      Starts CPU tracing. When tracing is used, the profiler instruments the bytecode of the profiled application for recording time spent inside each profiled method. Both times and invocation counts are available.

      If CPU profiling is already running, it will reset and start anew.

      Throws:
      ControllerException - Possible reasons:
      • CPU tracing has been disabled for the profiled application with startup options 'disable_tracing' or 'disable_all'.
      IOException

    • stopCpuProfiling

      public void stopCpuProfiling() throws IOException
      Stops CPU profiling in any mode, be it sampling, tracing or call counting. If CPU profiling is not running, this method has no effect.
      Throws:
      IOException

    • getJfrConfigs

      @NotNull public List<JfrConfig> getJfrConfigs() throws IOException
      Returns:
      Available flight recording configurations, which can be started.
      Throws:
      IOException

    • startJfr

      public void startJfr(@NotNull JfrSettings settings) throws IOException, ControllerException
      Starts flight recording.

      If a flight recording is already running, it will be reset and started again.

      Parameters:
      settings - flight recording settings or null for default.
      Throws:
      ControllerException - Possible reasons:
      • If JVM does not support JFR.
      • flight recording settings are invalid.
      IOException

    • stopJfr

      public void stopJfr() throws IOException, ControllerException
      Stops flight recording. If flight recording is not running, this method has no effect.
      Throws:
      ControllerException - If JVM does not support JFR.
      IOException

    • resetJfr

      public void resetJfr() throws IOException, ControllerException
      Clears the collected flight recording data and continues the recording if it is active.

      Note: when flight recording starts, collected results are cleared automatically, so you do not have to explicitly call this method in that case.

      Throws:
      ControllerException - If JVM does not support JFR.
      IOException

    • captureJfrSnapshot

      @NotNull public String captureJfrSnapshot() throws IOException, ControllerException
      Captures JFR snapshot.
      Returns:
      Absolute file path of the snapshot file. If a remote application is being profiled, then the path is in the file system of the remote host.
      Throws:
      ControllerException - If JVM does not support JFR.
      IOException