com.clarkware.profiler
Class Profiler

java.lang.Object
  |
  +--com.clarkware.profiler.Profiler

public class Profiler

extends java.lang.Object

The Profiler class is a simple tool used to profile the performance of instrumented regions of source code by recording specific runtime performance measurements.

Profiling Code

A region of source code is instrumented by invoking the static methods begin() and end() around the source code, designating the beginning and ending of an event to measure. These methods require an event description used to uniquely indentify the event being measured. The event description can be any useful description, but it must be used consistently in the matching begin() and end() methods. The event description specified for the end() method must be exactly the same as the event description used in the corresponding begin() method.

Calls to begin() may be nested within other calls to begin() provided that calls to end() are matched up with their respective calls to begin(). In other words, matching pairs of begin() and end() calls must be well formed. In the case of a mismatch, the current thread's event stack trace is displayed and the profiler is disabled.

Profiler Modes

By default, the begin() and end() methods record the amount of time that elapsed between their invocations. When the profiler is disabled using the static setEnabled() method, the begin() and end() methods return immediately to minimize additional overhead.

Memory profiling can optionally be enabled using the static enableMemory() method to record the amount of memory consumed or garbage collected during an event. Memory profiling is disabled by default.

Profiler Output

At any time, the static print() method can be invoked to print out the performance measurements collected for each of the recorded events. Alternatively, the static printAndReset() method can be invoked to print out the performance measurements and then reset all event measurements. The static printAndClear() method prints out the performance measurements and then clears the event history. The raw data produced by these methods can then be formatted as appropriate.

At any time, the static printStackTrace() method can be invoked to print the event stack trace for the current thread. This is useful for identifying the exact event being recorded in an active or stalled thread.

Collected Measurements

The following performance measurements are collected for each instrumented event:

• Number of times the event occurred
• Total execution time of the event (in milliseconds)
• Average execution time of the event (in milliseconds)
• If memory profiling is enabled:
  • Total memory consumed during the event (in bytes)
  • Total memory garbage collected during the event (in bytes)

Multi-Threaded Profiling

This class is multi-thread safe to allow multiple threads to be profiled concurrently. Event measurements are collected globally for all active threads.

The profiler maintains a history of events in a thread-specific stack. The static printStackTrace() method can be invoked to print the event stack trace for the current thread. This is useful for identifying the exact event being recorded in an active or stalled thread.

Profiler Overhead

Recording performance measurements using this class is intended to be very efficient with negligible overhead. The total overhead incurred per combined invocation of begin() and end(), with memory profiling disabled, has been measured to not exceed 3 milliseconds using JDK 1.3.

The number of strings and objects created by the begin() and end() methods was kept to a bare minimum to minimize the memory footprint.

The calculation of overall performance measurements for recorded events is delayed until a print method is invoked.

Remember, however, that there's no way to avoid Heisenberg's Uncertainty Principle when measuring the performance of software (or anything obeying the laws of physics, for that matter). Therefore, this class can safely be used as a development tool, but it is not necessarily suitable for production systems under heavy load.

Example Uses

 Profiler.begin("String concatentation");
 String s = "";
 for (int i=0; i < 10000; i++) {
     s = s + "a";
 }
 Profiler.end("String concatentation");
 Profiler.print();


 Profiler.begin("StringBuffer append");
 StringBuffer s = new StringBuffer();
 for (int i=0; i < 10000; i++) {
     s.append("a");
 }
 Profiler.end("StringBuffer append");
 Profiler.print();

 

Example Output

 String concatentation:
 count = 1 total = 960 (ms) average = 960.0 (ms)

 StringBuffer append:
 count = 1 total = 79 (ms) average = 79.0 (ms)

 

Author:

Mike Clark (mike@clarkware.com), Clarkware Consulting, Inc.

Nested Class Summary

static class	Profiler.EventProfile The EventProfile class contains event-specific performance measurements.
static class	Profiler.ThreadTrace The ThreadTrace class contains thread-specific trace information.

Constructor Summary

Profiler()

Method Summary

static void	begin(java.lang.String event) Designates the beginning of an event to measure.
static void	clear() Clears all the events.
static void	enable(boolean enabled) Indicates whether the profiler is enabled.
static void	enableMemory(boolean isEnabled) Indicates whether memory profiling is enabled.
static long	end(java.lang.String event) Designates the ending of an event being measured.
protected static Profiler.EventProfile	getEventProfile(java.lang.String event) Returns the event profile for the specified event.
protected static java.util.Hashtable	getEvents() Returns the collection of events.
protected static java.util.Stack	getThreadStack() Returns the thread-specific event stack for the current thread.
static boolean	isEnabled() Determines whether the profiler is enabled.
static boolean	isMemoryEnabled() Determines whether memory profiling is enabled.
static void	main(java.lang.String[] args)
static void	print() Prints the collected event measurements to System.out.
static void	print(java.io.OutputStream out) Prints the collected event measurements to the specified Outputstream.
static void	print(java.io.PrintWriter writer) Prints the collected event measurements to the specified writer.
static void	printAndClear(java.io.PrintWriter writer) Prints the collected event measurements to the specified writer and clears all events.
static void	printAndReset(java.io.PrintWriter writer) Prints the collected event measurements to the specified writer and resets all event measurements.
static void	printStackTrace(java.io.PrintWriter writer) Prints the current thread's event stack to the specified writer.
static void	reset() Resets all the event measurements.

Methods inherited from class java.lang.Object

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

Constructor Detail

Profiler

public Profiler()

Method Detail

begin

public static final void begin(java.lang.String event)

Designates the beginning of an event to measure.

Parameters:

event - Event description.

end

public static final long end(java.lang.String event)

Designates the ending of an event being measured.

Parameters:

event - Event description.

Returns:

Event duration (in milliseconds).

reset

public static final void reset()

Resets all the event measurements.

clear

public static final void clear()

Clears all the events.

enable

public static final void enable(boolean enabled)

Indicates whether the profiler is enabled.

isEnabled

public static final boolean isEnabled()

Determines whether the profiler is enabled.

Returns:

true if the profiler is enabled; false otherwise.

enableMemory

public static final void enableMemory(boolean isEnabled)

Indicates whether memory profiling is enabled.

Parameters:

isEnabled - true to enable memory profiling; false otherwise.

isMemoryEnabled

public static final boolean isMemoryEnabled()

Determines whether memory profiling is enabled.

Returns:

true if memory profiling is enabled; false otherwise.

printStackTrace

public static void printStackTrace(java.io.PrintWriter writer)

Prints the current thread's event stack to the specified writer.

Parameters:

writer - Writer.

print

public static final void print()

Prints the collected event measurements to System.out. This convenience implementation delegates printing to print(PrintWriter).

print

public static final void print(java.io.OutputStream out)

Prints the collected event measurements to the specified Outputstream. This convenience implementation delegates printing to print(PrintWriter).

Parameters:

out - OutputStream to print to.

print

public static void print(java.io.PrintWriter writer)

Prints the collected event measurements to the specified writer.

Parameters:

writer - Writer.

printAndReset

public static final void printAndReset(java.io.PrintWriter writer)

Prints the collected event measurements to the specified writer and resets all event measurements.

Parameters:

writer - Writer.

printAndClear

public static final void printAndClear(java.io.PrintWriter writer)

Prints the collected event measurements to the specified writer and clears all events.

Parameters:

writer - Writer.

getEvents

protected static java.util.Hashtable getEvents()

Returns the collection of events.

Returns:

Events.

getThreadStack

protected static final java.util.Stack getThreadStack()

Returns the thread-specific event stack for the current thread.

If an event stack does not exist for the curren thread, then a new event stack is created and registered.

Returns:

Thread event stack.

getEventProfile

protected static final Profiler.EventProfile getEventProfile(java.lang.String event)

Returns the event profile for the specified event.

If an event profile does not exist for the specified event description, then a new event profile is created and registered.

Parameters:

event - Event description.

Returns:

Event profile.

main

public static void main(java.lang.String[] args)