Class Controller


  • public final class Controller
    extends java.lang.Object
    The class provides API to control profiling of Java applications.
    • Constructor Detail

      • Controller

        public Controller()
                   throws java.lang.Exception

        Creates a controller to profile the application itself, that is the JVM running the code that invokes this constructor.

        The application should be launched with the profiler agent or the profiler agent should be attached to the JVM before using the controller.

        Throws:
        java.lang.Exception - if the profiler agent has not been loaded
        See Also:
        Controller(String, int)
      • Controller

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

        Creates a controller to profile application running on given host with the profiler agent listening on given port.

        The application to profile should be launched with the profiler agent or the profiler agent should be attached to the application's JVM before using the controller.

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

        Parameters:
        host - name or IP address of the host where the profiled application is running. Cannot be NULL. For the current machine specify "localhost".
        port - the 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 with the profiler agent listening on port
        • the profiled application has terminated
        • host:port is not accessible
        • I/O error
        See Also:
        Controller()
    • Method Detail

      • getSessionName

        @NotNull
        public java.lang.String getSessionName()
        Returns session name of the profiled application.
      • getHost

        @NotNull
        public java.lang.String getHost()
        Returns IP address or name of the host where the controlled profiled application is running.
      • getPort

        public int getPort()
        Returns the port the profiler agent listens on.
      • getPid

        public int getPid()
        Returns:
        Process identifier (PID) of the controlled profiled application.
      • captureSnapshot

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

        Captures a snapshot, that is writes profiling information to a file.

        Note: if a profiling activity such as CPU sampling or object allocation recording is running, it will not automatically stop after the snapshot capture. To stop it, explicitly call corresponding stop* methods.

        Parameters:
        snapshotFlags - defines what kind of snapshot to capture:
        • SNAPSHOT_WITHOUT_HEAP - capture snapshot with all the recorded information (CPU profiling, monitors, telemetry), but without the heap dump.
        • SNAPSHOT_WITH_HEAP - capture snapshot with all the recorded information (CPU profiling, monitors, telemetry, allocations), as well as with the heap dump.
        • SNAPSHOT_HPROF - capture snapshot in HPROF format (heap dump only).
        Returns:
        absolute file path of the captured snapshot file. If a remote application is profiled (see Controller(String, int)), the path is in the file system of the remote host.
        Throws:
        java.lang.Exception - if capture failed. Possible reasons:
        • the profiled application has terminated
        • the profiler agent cannot capture snapshot for some reason
        • I/O error
        See Also:
        capturePerformanceSnapshot(), captureMemorySnapshot(), captureHprofSnapshot()
      • captureMemorySnapshot

        public java.lang.String captureMemorySnapshot()
                                               throws java.lang.Exception
        The same as captureSnapshot(Controller.SNAPSHOT_WITH_HEAP)
        Throws:
        java.lang.Exception - if capture failed. Possible reasons:
        • the profiled application has terminated
        • the profiler agent cannot capture snapshot for some reason
        • I/O error
      • capturePerformanceSnapshot

        public java.lang.String capturePerformanceSnapshot()
                                                    throws java.lang.Exception
        The same as captureSnapshot(Controller.SNAPSHOT_WITHOUT_HEAP)
        Throws:
        java.lang.Exception - if capture failed. Possible reasons:
        • the profiled application has terminated
        • the profiler agent cannot capture snapshot for some reason
        • I/O error
      • captureHprofSnapshot

        public java.lang.String captureHprofSnapshot()
                                              throws java.lang.Exception
        The same as captureSnapshot(Controller.SNAPSHOT_HPROF)
        Throws:
        java.lang.Exception - if capture failed. Possible reasons:
        • the profiled application has terminated
        • the profiler agent cannot capture snapshot for some reason (e.g. the JVM does not support HPROF dumps)
        • I/O error
      • startAllocationRecording

        public void startAllocationRecording​(@Nullable
                                             java.lang.String settings)
                                      throws java.lang.Exception
        Starts object allocation recording.
        Parameters:
        settings - a comma or new-line separated list of the following options:
        • exactStacks - record exact stack traces (default)
        • sampledStacks - record estimated stack traces
        • counting - count allocated objects
        for exact or estimated stacks modes only:
        • sizeLimit - record all object of this or larger size in bytes (by default 4096 bytes = 4 KB)
        • recordEach - record only each N-th object of sizes smaller than the limit (by default 10)
        If an empty string or NULL is specified, "exactStacks,sizeLimit=4096,recordEach=10" is assumed
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • allocation recording has been disabled for the profiled application with startup options 'disablealloc' or 'disableall'
        • allocation recording is already running
        • the profiled application has terminated
        • I/O error
        See Also:
        captureMemorySnapshot(), stopAllocationRecording()
      • stopAllocationRecording

        public void stopAllocationRecording()
                                     throws java.lang.Exception
        Stops allocation recording. If allocation recording is not running, this method has no effect.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
        See Also:
        startAllocationRecording(String), captureMemorySnapshot()
      • clearAllocationData

        public void clearAllocationData()
                                 throws java.lang.Exception
        Clears recorded allocations. 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:
        • the profiled application has terminated
        • I/O error
        See Also:
        startAllocationRecording(String), stopAllocationRecording(), captureMemorySnapshot()
      • startSampling

        public void startSampling​(@Nullable
                                  java.lang.String settings)
                           throws java.lang.Exception
        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.
        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:
        java.lang.Exception - if failed. Possible reasons:
        • CPU profiling, be it sampling, tracing or call counting, is already running
        • the profiled application has terminated
        • I/O error
        See Also:
        captureSnapshot(long), stopCpuProfiling(), clearCpuData()
      • startAsyncSamplingCpu

        public void startAsyncSamplingCpu​(@Nullable
                                          java.lang.String settings)
                                   throws java.lang.Exception
        Starts asynchronous CPU sampling. For asynchronous sampling, an experimental HotSpot API and system CPU timers are used. Profiling overhead is lower than in other sampling modes, but methods like sleep() and wait() which don't consume much CPU time will not be shown in the results. Time measurement accuracy is high for methods consuming the CPU time the most
        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:
        java.lang.Exception - if failed. Possible reasons:
        • Asynchronous sampling is not supported by the JVM
        • CPU profiling, be it sampling, tracing or call counting, is already running
        • the profiled application has terminated
        • I/O error
        See Also:
        captureSnapshot(long), stopCpuProfiling(), clearCpuData()
      • startTracing

        public void startTracing​(@Nullable
                                 java.lang.String settings)
                          throws java.lang.Exception
        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.
        Parameters:
        settings - CPU tracing settings. Pass NULL to use the profiled application's settings, or pass your custom settings as a non-NULL string.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • CPU tracing has been disabled for the profiled application with startup options 'disabletracing' or 'disableall'
        • CPU profiling, be it sampling, tracing or call counting, is already running
        • the profiled application has terminated
        • I/O error
        See Also:
        captureSnapshot(long), stopCpuProfiling(), clearCpuData()
      • startCallCounting

        public void startCallCounting()
                               throws java.lang.Exception
        Starts CPU call counting. Unlike other CPU profiling modes only method invocations are counted, neither call stacks nor times are gathered.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • Call counting (along with CPU tracing) has been disabled for the profiled application with startup options 'disabletracing' or 'disableall'
        • CPU profiling, be it sampling, tracing or call counting, is already running
        • the profiled application has terminated
        • I/O error
        See Also:
        captureSnapshot(long), stopCpuProfiling(), clearCpuData()
      • startMonitorProfiling

        public void startMonitorProfiling()
                                   throws java.lang.Exception
        Starts monitor profiling.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • monitor profiling is already running
        • the profiled application has terminated
        • I/O error
        See Also:
        captureSnapshot(long), stopMonitorProfiling(), clearMonitorData()
      • stopMonitorProfiling

        public void stopMonitorProfiling()
                                  throws java.lang.Exception
        Stops monitor profiling. If monitor profiling is not running, this method has no effect.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
        See Also:
        startMonitorProfiling(), captureSnapshot(long), clearCpuData()
      • clearMonitorData

        public void clearMonitorData()
                              throws java.lang.Exception
        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:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
        See Also:
        startMonitorProfiling(), stopMonitorProfiling(), captureSnapshot(long)
      • startStackTelemetry

        public void startStackTelemetry()
                                 throws java.lang.Exception
        Starts collecting thread stack and state telemetry. If this telemetry is already being collected, the method has no effect.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
        See Also:
        captureSnapshot(long), stopStackTelemetry()
      • stopStackTelemetry

        public void stopStackTelemetry()
                                throws java.lang.Exception
        Stops collecting thread stack and state telemetry. If this telemetry is not being collected, the method has no effect.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
        See Also:
        startStackTelemetry(), captureSnapshot(long)
      • startExceptionProfiling

        public void startExceptionProfiling()
                                     throws java.lang.Exception
        Starts exception profiling. If exception profiling is already running, this method has no effect.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
        See Also:
        captureSnapshot(long), stopExceptionProfiling()
      • stopExceptionProfiling

        public void stopExceptionProfiling()
                                    throws java.lang.Exception
        Stops exception profiling. If exception profiling is not running, this method has no effect.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
        See Also:
        startExceptionProfiling(), captureSnapshot(long)
      • clearEventTables

        public void clearEventTables​(@NotNull
                                     java.lang.String... tableNames)
                              throws java.lang.Exception
        Clears event table(s) by name. If the specified tables have dependent tables, they will be cleared too.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
      • advanceGeneration

        public void advanceGeneration​(@Nullable
                                      java.lang.String description)
                               throws java.lang.Exception
        Parameters:
        description - optional description associated with the generation
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
      • forceGc

        public long[] forceGc()
                       throws java.lang.Exception
        Forces garbage collection in the profiled application.
        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 - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
      • setTriggers

        public void setTriggers​(java.lang.String triggersDescription,
                                boolean append)
                         throws java.lang.Exception
        Parameters:
        triggersDescription - 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:
        java.lang.Exception - if failed. Possible reasons:
        • the trigger description is invalid
        • the profiled application has terminated
        • I/O error
      • getTriggers

        @NotNull
        public java.lang.String getTriggers()
                                     throws java.lang.Exception
        Obtains current trigger description
        Returns:
        description of triggers; never NULL; if there are no triggers, an empty string will be returned
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
      • getProbeActivityModes

        @NotNull
        public java.util.HashMap<java.lang.String,​ProbeActivityMode> getProbeActivityModes()
                                                                                          throws java.lang.Exception
        Obtains current probe activity modes
        Returns:
        the mapping of probe class names to the probe activity mode
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
      • setProbeActivityModes

        public void setProbeActivityModes​(@NotNull
                                          java.util.HashMap<java.lang.String,​ProbeActivityMode> probeClassName2mode)
                                   throws java.lang.Exception
        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:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
      • getTotalCreatedObjectCount

        public long getTotalCreatedObjectCount()
                                        throws java.lang.Exception
        Get total count of all objects created during object allocation recording. The returned value grows monotonically: the underlying counter is not zeroed when allocation recording is re-started or allocation results are cleared.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
      • getTotalCreatedObjectSize

        public long getTotalCreatedObjectSize()
                                       throws java.lang.Exception
        Get total size in bytes of all objects created during object allocation recording. Note: the value is only updated in the full recording mode, it is not updated in the object counting mode. The returned value grows monotonically: the underlying counter is not zeroed when allocation recording is re-started or allocation results are cleared.
        Throws:
        java.lang.Exception - if failed. Possible reasons:
        • the profiled application has terminated
        • I/O error
      • isSampling

        public static boolean isSampling​(long status)
        Checks whether classic (not async. sampling) CPU sampling is running.
        Parameters:
        status - pass the result of getStatus()
      • isAsyncSamplingCpu

        public static boolean isAsyncSamplingCpu​(long status)
        Checks whether asynchronous CPU sampling is running.
        Parameters:
        status - pass the result of getStatus()
      • isTracing

        public static boolean isTracing​(long status)
        Checks whether CPU tracing is running.
        Parameters:
        status - pass the result of getStatus()
      • isCallCounting

        public static boolean isCallCounting​(long status)
        Checks whether call counting is running.
        Parameters:
        status - pass the result of getStatus()
      • isMonitorProfiling

        public static boolean isMonitorProfiling​(long status)
        Checks whether monitor profiling is running.
        Parameters:
        status - pass the result of getStatus()
      • isAllocationRecording

        public static boolean isAllocationRecording​(long status)
        Checks whether object allocation recording is running.
        Parameters:
        status - pass the result of getStatus()
      • isStackTelemetry

        public static boolean isStackTelemetry​(long status)
        Checks whether stack telemetry is running.
        Parameters:
        status - pass the result of getStatus()
      • isExceptionProfiling

        public static boolean isExceptionProfiling​(long status)
        Checks whether exception profiling is running.
        Parameters:
        status - pass the result of getStatus()
      • isDeadlockDetected

        public static boolean isDeadlockDetected​(long status)
        Checks whether a Java-level deadlock has been detected
        Parameters:
        status - pass the result of getStatus()
      • isCPUCallCounting

        @Deprecated
        public static boolean isCPUCallCounting​(long status)
        Deprecated.
        Use isCallCounting(long) instead. Will be removed in the next release.
      • isCPUTracing

        @Deprecated
        public static boolean isCPUTracing​(long status)
        Deprecated.
        Use isTracing(long) instead. Will be removed in the next release.
      • isCPUSampling

        @Deprecated
        public static boolean isCPUSampling​(long status)
        Deprecated.
        Use isSampling(long) instead. Will be removed in the next release.
      • isCPUProfiling

        @Deprecated
        public static boolean isCPUProfiling​(long status)
        Deprecated.
        Use isCpuProfiling(long) instead. Will be removed in the next release.
      • isExceptionTelemetry

        @Deprecated
        public static boolean isExceptionTelemetry​(long status)
        Deprecated.
        Use isExceptionProfiling(long) instead. Will be removed in the next release.
      • captureHPROFSnapshot

        @Deprecated
        public java.lang.String captureHPROFSnapshot()
                                              throws java.lang.Exception
        Deprecated.
        Use captureHprofSnapshot() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • clearCPUData

        @Deprecated
        public void clearCPUData()
                          throws java.lang.Exception
        Deprecated.
        Use clearCpuData() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • disableExceptionTelemetry

        @Deprecated
        public void disableExceptionTelemetry()
                                       throws java.lang.Exception
        Deprecated.
        Use stopExceptionProfiling() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • disableStackTelemetry

        @Deprecated
        public void disableStackTelemetry()
                                   throws java.lang.Exception
        Deprecated.
        Use stopStackTelemetry() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • enableExceptionTelemetry

        @Deprecated
        public void enableExceptionTelemetry()
                                      throws java.lang.Exception
        Deprecated.
        Use startExceptionProfiling() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • enableStackTelemetry

        @Deprecated
        public void enableStackTelemetry()
                                  throws java.lang.Exception
        Deprecated.
        Use startStackTelemetry() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • forceGC

        @Deprecated
        public long[] forceGC()
                       throws java.lang.Exception
        Deprecated.
        Use forceGc() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • getPID

        @Deprecated
        public int getPID()
        Deprecated.
        Use getPid() instead. Will be removed in the next release.
      • startCPUCallCounting

        @Deprecated
        public void startCPUCallCounting()
                                  throws java.lang.Exception
        Deprecated.
        Use startCallCounting() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • startCPUSampling

        @Deprecated
        public void startCPUSampling​(@Nullable
                                     java.lang.String settings)
                              throws java.lang.Exception
        Deprecated.
        Use startSampling(String) instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • startCPUTracing

        @Deprecated
        public void startCPUTracing​(@Nullable
                                    java.lang.String settings)
                             throws java.lang.Exception
        Deprecated.
        Use startTracing(String) instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • stopCPUProfiling

        @Deprecated
        public void stopCPUProfiling()
                              throws java.lang.Exception
        Deprecated.
        Use stopCpuProfiling() instead. Will be removed in the next release.
        Throws:
        java.lang.Exception
      • main

        public static void main​(@NotNull
                                java.lang.String[] args)
                         throws java.lang.Exception
        An entry point implementing the command line interface to a limited subset of Controller functionality. Don't call this method directly.
        Throws:
        java.lang.Exception