com.github.susom.database

Class Metric

java.lang.Object

com.github.susom.database.Metric

public class Metric
extends Object

This class provides explicit instrumentation functionality.

Author:

garricko

Constructor Summary

Constructors

Constructor and Description
Metric(boolean enabled) Create a metric tracking object and start the nanosecond timer.

Method Summary

Modifier and Type	Method and Description
void	checkpoint(String description, Object... args) Set a mark for timing.
long	done() Indicate we are done (stop the timer).
long	done(String description, Object... args) Set a final mark for timing and stop the timer.
long	elapsedMillis() Find out how many milliseconds have elapsed since this timer was started.
long	elapsedNanos() Find out how many nanoseconds have elapsed since this timer was started.
String	getMessage() Construct and return a message based on the timing and checkpoints.
void	printMessage(StringBuilder buf) Construct and print a message based on the timing and checkpoints.

Methods inherited from class java.lang.Object

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

Constructor Detail

Metric

public Metric(boolean enabled)

Create a metric tracking object and start the nanosecond timer. Times are obtained using System.nanoTime(). The canonical way to use this looks something like this:

   Metric metric = new Metric(log.isDebugEnabled);
   ...
   metric.checkpoint("received");
   ...
   metric.checkpoint("processed");
   ...
   metric.done("sent");
   ...
   if (log.isDebugEnabled()) {
    log.debug("Processed: " + metric.getMessage());
   }
 

Parameters:

enabled - true if timings will be taken, false to optimize out the time tracking

Method Detail

elapsedMillis

public long elapsedMillis()

Find out how many milliseconds have elapsed since this timer was started.

Returns:

the number of milliseconds elapsed, or -1 if false was passed in the constructor

elapsedNanos

public long elapsedNanos()

Find out how many nanoseconds have elapsed since this timer was started.

Returns:

the number of nanoseconds elapsed, or -1 if false was passed in the constructor

checkpoint

public void checkpoint(String description,
                       Object... args)

Set a mark for timing. It is strongly recommended to use a short, simple alphanumeric description. For example, "sent" or "didThat". With this version you can provide additional arguments, such as byte counts, which will be appended comma-separated within brackets. For example, checkpoint("sent", 25, 3) will result in a description "sent[25,3]". The string evaluation and concatenation is lazy, and won't be done if this metric is disabled.

Parameters:

description - a label for this mark; may not be null; spaces and tabs will be converted to underscores

args - additional information to append to the description; will print "null" if null; evaluated with String.valueOf() lazily and sanitized of most non-alphanumeric characters

done

public long done(String description,
                 Object... args)

Set a final mark for timing and stop the timer. Once you call this method, subsequent calls have no effect.

Parameters:

description - a label for this mark; may not be null; spaces and tabs will be converted to underscores

Returns:

time in nanoseconds from the start of this metric, or -1 if false was passed in the constructor

done

public long done()

Indicate we are done (stop the timer). Once you call this method, subsequent calls have no effect.

Returns:

time in nanoseconds from the start of this metric, or -1 if false was passed in the constructor

getMessage

public String getMessage()

Construct and return a message based on the timing and checkpoints. This will look like "123.456ms(checkpoint1=100.228ms,checkpoint2=23.228ms)" without the quotes. There will be no spaces or tabs in the output.

This will automatically call the done() method to stop the timer if you haven't already done so.

Returns:

a string with timing information, or "metricsDisabled" if false was passed in the constructor.

See Also:

printMessage(StringBuilder)

printMessage

public void printMessage(StringBuilder buf)

Construct and print a message based on the timing and checkpoints. This will look like "123.456ms(checkpoint1=100.228ms,checkpoint2=23.228ms)" without the quotes. There will be no spaces or tabs in the output. A value of "metricsDisabled" will be printed if false was passed in the constructor.

This will automatically call the done() method to stop the timer if you haven't already done so.

Parameters:

buf - the message will be printed to this builder

See Also:

getMessage()