com.rshtech.logging
Class EventTracker

java.lang.Object
  com.rshtech.logging.EventTracker

public class EventTracker
extends java.lang.Object

EventTracker provides a way to instrument your libraries with minimal work or overhead. Like a logging package, this class is intended to provide a simple, easy-to-use, drop-in solution for tracking how well your application performs. And also like logging packages, EventTracker causes no noticeable overhead in an application when it isn't turned on--its methods abort quickly, do nothing and generating no memory allocation when the level isn't set to trace (via the JCL/LoggingUtil packages).

Many times profilers will bog down an application to severely to reproduce a problem under load (as the profiler applies to everything in the VM). EventTracker provides a way to track that information without a profiler. It is not a replacement for a profiler, but meant to complement a profiler or provide information where a profiler would be too heavy.

If you think a profiler is fine for everything from tracking what's going on (often done by a logging package), you will probably not find this package very useful. But if you have had a profiler not prove to be useful in a few situations or if you were raised on the print-statement school of debugging, you may find this class very useful.

EventTracker will not track anything until startEventTracking() is called--and only if trace is enabled for the logger supplied to startEventTracking(). Until startEventTracking() is called and until the log level is set to trace, nothing will happen when the start() and stop() methods are called. When startEventTracking() is called and the log level is set to trace, event tracking is initialized, and a new StopWatchTree is started for the thread-space. That is, only the start() and stop() calls for the current thread are registered.

It is highly-recommended you specify the event name and do not force EventTracker to calculate it for you. While the event name calculation will not occur if tracking is disabled, it will still be fairly heavy in overhead when it finally is turned on--adding significant time to your event times. Instead, specify the event name specifically when you make the call.

Event names should be brief but descriptive. Uniqueness or readability should be your primary concerns when naming an event. A string of any length can be used. Static strings are recommended, as most dynamic strings will generate unneeded overhead even when tracking has been turned off. An example would be a data load; you could name the event "loading FooBar from DB".

Typical usage goes like this:

• Place start() and stop() calls throughout your code. Like logging calls, they will not add heavy overhead to your code when event tracking is disabled. Framework code is a prime candidate for event tracking, as you usually want to know how your application code performs and what it is doing with the frameworks. For example, Placing start() and stop() in data access methods allows you to track DB performance and how many times you hit the database.
• Choose your "main event" points for your application--where you want to know the end-to-end transaction time for a major piece of work. Usually this would be things like a "save operation", from where the data enters the system until the DB save is complete. Place a startEventTracking() and stopEventTracking() pair around the unit of work.
• Add an EventTracker.print(Log) call after the stopEventTracking() method to dump the event tracking information to the logging system.

With these steps completed, you can then turn event tracking on by enabling trace at the main event points. For instance, if you had a saveFooBar() operation that took a FooBar, did some checks, and then saved it, and you this method was in the FooBarDataAccess class, you would then set trace for FooBarDataAccess (e.g. -Dyou.package.FooBarDataAccess.level=TRACE). The event would then print to logging when ever it was called. Output might look something like this:

    # StopWatchHelper.printToLogger(): Time break down (in milliseconds)
    * [   500ms] save FooBar
    |  + [    10ms] data validation for FooBar
    |  |  + [     7ms] verify FooBar
    |  |  |  + [     1ms] validate fields
    |  |  |  + [     6ms] validate timestamps
    |  |  |___
    |  |  + [     3ms] check children
    |  |___
    |  + [   290ms] DataAccessObject.saveObject()
    |  + [   200ms] DataAccessObject.saveCollection()
    |  |  + [   150ms] DataAccessObject.loadCollection()
    |  |  + [    50ms] DataAccessObject.mergeCollection()
    |  |___
    |___
 

This output would only be printed if trace was enabled--so there will be no extra overhead when trace is not enabled.

Because EventTracker only tracks events within the same thread-space/current thread, you must call startEventTracking() again for each new thread spawned. The two thread-spaces will be tracked indpendently. There is no practical, thread-safe way to track event statuses across multiple threads without incurring lots of overhead and complexity (which may or may not be portable to all the situations EventTracker would be used in). If you want to figure out total time to finish a transaction, it is recommended you call start() before spawning and stop() after your wait/join is finished. While you will not have all the events in the thread recorded, you will have the total time. Another approach is to clearly label the starting event for your child threads and use an after-the-fact parser on the logging output to stitch them back together into one transaction and time-frame.

Version:

$Revision: 3133 $

Author:

$Author: kostya $

Method Summary

static void	print() Print the event stack and the times recorded for each event, using EventTracker's logger.
static void	print(org.apache.commons.logging.Log logger) Print the event stack and the times recorded for each event, using the specified logger.
static void	print(java.io.Writer writer) Print the event stack and the times recorded for each event, using the specified Writer.
static void	start() Track an event starting, where the event name is calculated from the caller (NOTE: calculating the caller is expensive; It is recommended you specify the event name).
static void	start(java.lang.String eventName) Track an event starting named eventName.
static void	startEventTracking(org.apache.commons.logging.Log logger) Starts event tracking, calculating the caller and using it as the event name (NOTE: calculating the caller is expensive; It is recommended you specify the event name).
static void	startEventTracking(org.apache.commons.logging.Log logger, java.lang.String eventName) Starts event tracking for the event name.
static void	stop() Track that the current event (as specified in the corresponding start() call) has stopped.
static void	stopEventTracking() Stop event tracking, stopping all currently open events and preventing any further event tracking.

Methods inherited from class java.lang.Object

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

Method Detail

startEventTracking

public static void startEventTracking(org.apache.commons.logging.Log logger)

Starts event tracking, calculating the caller and using it as the event name (NOTE: calculating the caller is expensive; It is recommended you specify the event name). This method initiates event tracking and allows subsequent start() calls to log event times. Without calling this method, all start() and stop calls will do nothing.

Parameters:

logger - logger for the caller or for the caller's "space". The logger is used to determing whether event tracking is enabled. If trace is enabled for the logger, event tracking will be started.

startEventTracking

public static void startEventTracking(org.apache.commons.logging.Log logger,
                                      java.lang.String eventName)

Starts event tracking for the event name. This method initiates event tracking and allows subsequent start() calls to log event times. Without calling this method, all start() and stop calls will do nothing.

Parameters:

logger - logger for the caller or for the caller's "space". The logger is used to determing whether event tracking is enabled. If trace is enabled for the logger, event tracking will be started.

start

public static void start()

Track an event starting, where the event name is calculated from the caller (NOTE: calculating the caller is expensive; It is recommended you specify the event name). If startEventTracking() has not already been called, this method will do nothing (very quickly) avoiding overhead.

start

public static void start(java.lang.String eventName)

Track an event starting named eventName. If startEventTracking() has not already been called, this method will do nothing (very quickly) avoiding overhead.

Parameters:

eventName - the name of the event (fairly descriptive or unique names are recommended)

stop

public static void stop()

Track that the current event (as specified in the corresponding start() call) has stopped. if startEventTracking() was not called, this method will do nothing (very quickly) to avoid overhead.

stopEventTracking

public static void stopEventTracking()

Stop event tracking, stopping all currently open events and preventing any further event tracking. To start tracking a new event sequence, call startEventTracking() again. If startEventTracking() was never called this method will do nothing (very quickly) to avoid overhead.

print

public static void print()

Print the event stack and the times recorded for each event, using EventTracker's logger. If the logger for EventTracker does not have trace enabled, no output will be generated. If startEventTracking() was never called, this method will do nothing regardless of the logger settings.

print

public static void print(org.apache.commons.logging.Log logger)

Print the event stack and the times recorded for each event, using the specified logger. If the logger does not have trace enabled, no output will be generated. If startEventTracking() was never called, this method will do nothing regardless of the logger settings.

print

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

Print the event stack and the times recorded for each event, using the specified Writer. If startEventTracking() was never called, this method will do nothing and will print nothing to the Writer.