Package org.threadly.util.debug

Class Profiler

  • Direct Known Subclasses:
    ControlledThreadProfiler, FilteredStackProfiler
    public class Profiler
extends java.lang.Object
    Tool for profiling a running java application to get an idea of where the slow points (either because of lock contention, or because of high computational demand).

    This tool definitely incurs some load within the system, so it should only be used while debugging, and not as general use. In addition if it is left running without being reset, it will continue to consume more and more memory.

    Since:
    1.0.0

    • Constructor Summary

      Constructors 
      Constructor Description
      Profiler()
      Constructs a new profiler instance.
      Profiler​(int pollIntervalInMs)
      Constructs a new profiler instance.
      Profiler​(int pollIntervalInMs, java.util.function.Function<? super Profiler,​java.lang.String> startFutureResultSupplier)
      Constructs a new profiler instance.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String dump()
      Output all the currently collected statistics to the provided output stream.
      java.lang.String dump​(boolean dumpIndividualThreads, int minimumStackWitnessCount)
      Output all the currently collected statistics to the provided output stream.
      void dump​(java.io.OutputStream out)
      Output all the currently collected statistics to the provided output stream.
      void dump​(java.io.OutputStream out, boolean dumpIndividualThreads, int minimumStackWitnessCount)
      Output all the currently collected statistics to the provided output stream.
      void dump​(java.io.PrintStream ps)
      Output all the currently collected statistics to the provided output stream.
      void dump​(java.io.PrintStream ps, boolean dumpIndividualThreads, int minimumStackWitnessCount)
      Output all the currently collected statistics to the provided output stream.
      int getCollectedSampleQty()
      Call to get an estimate on how many times the profiler has collected a sample of the thread stacks.
      int getPollInterval()
      Call to get the currently set profile interval.
      boolean isRunning()
      Call to check weather the profile is currently running/started.
      void reset()
      Reset the current stored statistics.
      void setPollInterval​(int pollIntervalInMs)
      Change how long the profiler waits before getting additional thread stacks.
      void start()
      Starts the profiler running in a new thread.
      ListenableFuture<java.lang.String> start​(long sampleDurationInMillis)
      Starts the profiler running in a new thread.
      void start​(java.util.concurrent.Executor executor)
      Starts the profiler running in a new thread.
      ListenableFuture<java.lang.String> start​(java.util.concurrent.Executor executor, long sampleDurationInMillis)
      Starts the profiler running in a new thread.
      void stop()
      Stops the profiler from collecting more statistics.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • Profiler

        public Profiler()
        Constructs a new profiler instance. The only way to get results from this instance is to call dump() with a provided output stream to get the results to.

        This uses a default poll interval of 100 milliseconds.

      • Profiler

        public Profiler​(int pollIntervalInMs)
        Constructs a new profiler instance. The only way to get results from this instance is to call dump() with a provided output stream to get the results to.
        Parameters:
        pollIntervalInMs - frequency to check running threads

      • Profiler

        public Profiler​(int pollIntervalInMs,
                java.util.function.Function<? super Profiler,​java.lang.String> startFutureResultSupplier)
        Constructs a new profiler instance. The only way to get results from this instance is to call dump() with a provided output stream to get the results to.

        This constructor allows you to change the behavior of the ListenableFuture result when start(long) or start(Executor, long) is used. Generally this will provide the complete result of dump(). This can be replaced with calling dump(OutputStream, boolean, int) with parameters to reduce the output, or even null so long as the consumers of the future can handle a null result.

        Parameters:
        pollIntervalInMs - frequency to check running threads
        startFutureResultSupplier - Supplier to be used for providing future results

    • Method Detail

      • setPollInterval

        public void setPollInterval​(int pollIntervalInMs)
        Change how long the profiler waits before getting additional thread stacks. This value must be greater than or equal to 0.
        Parameters:
        pollIntervalInMs - time in milliseconds to wait between thread data dumps

      • getPollInterval

        public int getPollInterval()
        Call to get the currently set profile interval. This is the amount of time the profiler waits between collecting thread data.
        Returns:
        returns the profile interval in milliseconds

      • getCollectedSampleQty

        public int getCollectedSampleQty()
        Call to get an estimate on how many times the profiler has collected a sample of the thread stacks. This number may be lower than the actual sample quantity, but should never be higher. It can be used to ensure a minimum level of accuracy from within the profiler.
        Returns:
        the number of times since the start or last reset we have sampled the threads

      • reset

        public void reset()
        Reset the current stored statistics. The statistics will continue to grow in memory until the profiler is either stopped, or until this is called.

      • isRunning

        public boolean isRunning()
        Call to check weather the profile is currently running/started.
        Returns:
        true if there is a thread currently collecting statistics.

      • start

        public void start()
        Starts the profiler running in a new thread.

        If this profiler had previously ran, and is now sitting in a stopped state again. The statistics from the previous run will still be included in this run. If you wish to clear out previous runs you must call reset() first.

      • start

        public void start​(java.util.concurrent.Executor executor)
        Starts the profiler running in a new thread.

        If this profiler had previously ran, and is now sitting in a stopped state again. The statistics from the previous run will still be included in this run. If you wish to clear out previous runs you must call reset() first.

        If an executor is provided, this call will block until the the profiler has been started on the provided executor.

        Parameters:
        executor - executor to execute on, or null if new thread should be created

      • start

        public ListenableFuture<java.lang.String> start​(long sampleDurationInMillis)
        Starts the profiler running in a new thread.

        If this profiler had previously ran, and is now sitting in a stopped state again. The statistics from the previous run will still be included in this run. If you wish to clear out previous runs you must call reset() first.

        If sampleDurationInMillis is greater than zero the Profiler will invoke stop() in that many milliseconds.

        The returned ListenableFuture will be provided the dump when stop() is invoked next. Either from a timeout provided to this call, or a manual invocation of stop().

        Parameters:
        sampleDurationInMillis - if greater than 0 the profiler will only run for this many milliseconds
        Returns:
        Future that will be completed with the dump string when the profiler is stopped

      • start

        public ListenableFuture<java.lang.String> start​(java.util.concurrent.Executor executor,
                                                long sampleDurationInMillis)
        Starts the profiler running in a new thread.

        If this profiler had previously ran, and is now sitting in a stopped state again. The statistics from the previous run will still be included in this run. If you wish to clear out previous runs you must call reset() first.

        If an executor is provided, this call will block until the the profiler has been started on the provided executor.

        If sampleDurationInMillis is greater than zero the Profiler will invoke stop() in that many milliseconds.

        The returned ListenableFuture will be provided the dump when stop() is invoked next. Either from a timeout provided to this call, or a manual invocation of stop().

        Parameters:
        executor - executor to execute on, or null if new thread should be created
        sampleDurationInMillis - if greater than 0 the profiler will only run for this many milliseconds
        Returns:
        Future that will be completed with the dump string when the profiler is stopped

      • stop

        public void stop()
        Stops the profiler from collecting more statistics. If a file was provided at construction, the results will be written to that file. It is possible to request the results using the dump() call after it has stopped.

      • dump

        public java.lang.String dump()
        Output all the currently collected statistics to the provided output stream.
        Returns:
        The dumped results as a single String

      • dump

        public java.lang.String dump​(boolean dumpIndividualThreads,
                             int minimumStackWitnessCount)
        Output all the currently collected statistics to the provided output stream.
        Parameters:
        dumpIndividualThreads - If true then a report of stacks seen for individual threads is also dumped
        minimumStackWitnessCount - Minimum times profiler must have seen the stack to include in the dump
        Returns:
        The dumped results as a single String

      • dump

        public void dump​(java.io.OutputStream out)
        Output all the currently collected statistics to the provided output stream.
        Parameters:
        out - OutputStream to write results to

      • dump

        public void dump​(java.io.OutputStream out,
                 boolean dumpIndividualThreads,
                 int minimumStackWitnessCount)
        Output all the currently collected statistics to the provided output stream.
        Parameters:
        out - OutputStream to write results to
        dumpIndividualThreads - If true then a report of stacks seen for individual threads is also dumped
        minimumStackWitnessCount - Minimum times profiler must have seen the stack to include in the dump

      • dump

        public void dump​(java.io.PrintStream ps)
        Output all the currently collected statistics to the provided output stream.
        Parameters:
        ps - PrintStream to write results to

      • dump

        public void dump​(java.io.PrintStream ps,
                 boolean dumpIndividualThreads,
                 int minimumStackWitnessCount)
        Output all the currently collected statistics to the provided output stream.
        Parameters:
        ps - PrintStream to write results to
        dumpIndividualThreads - If true then a report of stacks seen for individual mthreads is also dumped
        minimumStackWitnessCount - Minimum times profiler must have seen the stack to include in the dump