org.threadly.util.debug

Class Profiler

java.lang.Object

org.threadly.util.debug.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 and 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

Modifier and Type	Method and Description
java.lang.String	dump() Output all the currently collected statistics to the provided output stream.
java.lang.String	dump(boolean dumpIndividualThreads) Deprecated. Use dump(boolean, int) with a value of 1
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) Deprecated. Use dump(OutputStream, boolean, int) with a value of 1
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) Deprecated. Use dump(PrintStream, boolean, int) with a value of 1
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.
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.
ListenableFuture<java.lang.String>	start(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

@Deprecated
public java.lang.String dump(boolean dumpIndividualThreads)

Deprecated. Use dump(boolean, int) with a value of 1

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

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

@Deprecated
public void dump(java.io.OutputStream out,
                             boolean dumpIndividualThreads)

Deprecated. Use dump(OutputStream, boolean, int) with a value of 1

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

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

@Deprecated
public void dump(java.io.PrintStream ps,
                             boolean dumpIndividualThreads)

Deprecated. Use dump(PrintStream, boolean, int) with a value of 1

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 threads is also dumped

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