README.md

Small Java library for sampling code.

There are multiple ways for measuring the performance of code, sampling and instrumentation. Instrumentation modifies the original program's byte code by inserting measurement code. Sampling is done by programming the measurement code manually.

This is a sampling library that provides:

• counters; keeping track of how many times something has taken place
• sampling; collecting samples and describing their distribution
• durations; measuring the duration of a task as a special case of sampling
• no transitive dependencies!

The library provides an API and comes with a default implementation safe to be used in a multi-threaded environment.

Java 6+

Some examples:

 // you can expose this instance application wide using an Enum, Singleton or perhaps as a spring-bean
 public static final Statistics STATISTICS = StatisticsFactory.createThreadsafeStatistics();
 ...

 // counters
 public void onMessage(Message message) {
    STATISTICS.addOccurrence("jms.message.received");
 }


 // durations
 public void onMessage(Message message) {
    Stopwatch onMessageStopwatch = STATISTICS.startStopwatch();

    //expensive method that takes long
    processMessage(message);

    long elapsedTime = STATISTICS.recordElapsedTime("jms.message.received.duration", onMessageStopwatch);
        
    // elapsedTime is the value read from the onMessageStopwatch.
 }

 // samples
 public void onLogin(Message message) {
    int loggedInUsers = System.countUsersLoggedIn();
    STATISTICS.addSample("users.logged.in", loggedInUsers);    
 }

 // retrieve results
 public void printResults() {
    Snapshot snapshot = STATISTICS.getSnapshot();
    
    snapshot.getOccurrences();   // each key has a Long with the corresponding value of "timesOccurred"  
    snapshot.getDurations();     // each key has a corresponding statistic which provides samplecount/min/max/avg/variance/standarddeviation
    snapshot.getSamples();       // each key has a corresponding statistic which provides samplecount/min/max/avg/variance/standarddeviation
 }

Java 8 users can measure the duration of a lambda:

// measuring durations of methods without a return type
public void onMessage(Message message) {
    STATISTICS.recordElapsedTime("jms.message.received.duration", () -> processMessage(message));
}

// measuring durations of methods with a return type
public Result convert(Message message) {
    return STATISTICS.recordElapsedTime("jms.message.convertion.duration", () -> return convertMessageIntoResult(message));
}

public Result convertMessageIntoResult(Message message) {
    return new Result(expensiveTransform(message));
}