an open source Java package by BerryWorks



JQuantify API

GPL License

SourceForge project

SourceForge.net Logo

What is JQuantify ?

JQuantify is a Java package providing lightweight statistics describing the frequency and duration of application-specific events. Developers use a simple API to insert count-points or start/stop boundaries at appropriate places within their system.

The two most important subclasses of a common Metric superclass are

  • EventCounter - for application-specific events that occur at arbitrary points in time

  • SessionCounter - for application-specific events that have arbitrary start and stop points and therefore duration

An EventCounter object is incremented from anywhere within the program with add(), equivalent to the ++ operator on an int. With no further programmer involvement the following statistics are available at any time from the object:

  • total number of times the add() has been called (the current count)

  • frequency of counted events over the life of the object

  • peak frequency observed, based on discrete time intervals (second, minute, hour, etc.) specified when the counter is constructed

  • when the peak frequency occurred

A SessionCounter object counts events marked by start() and stop(). The following statistics are available at any time from the object:

  • all of the EventCounter statistics for session starts (SessionCounter is actually a subclass of EventCounter)

  • mean and maximum session duration

  • when the maximum session occurred

  • duration of a recently completed session

  • with regard to the overlapping, or concurrent, sessions for this object

    • current number of concurrent sessions

    • peak number of concurrent sessions and when that peak occurred

In addition to EventCounter and SessionCounter, the primary subclasses of Metric, a VMUsage subclass is also provided such that each call to add() takes another sample of the number of threads and memory utilization. The following statistics are provided:

  • current, minimum, maximum, and mean number of threads for the JVM hosting the object

  • current, minimum, maximum, and mean bytes of memory used by the JVM (both total and free memory)

Where would I use JQuantify ?

Use it in your production Java systems in order to increase awareness of the number, frequency, duration, and concurrency of the units of work handled by the system.  Its algorithms are threadsafe and designed to have negligible impact on CPU resources, deferring computation whenever possible from the add(), start(), and stop() methods to the methods that access the statistics. Only a very small fixed amount of memory is required for each counter object.

How is this different from a profiler ?

Although JQuantify and profilers such as JProbe and JProfiler provide for quantitative measures of various aspects of running software, they typically are mesauring different things during a different phase of the project and for different purposes.

What is being measured
Profilers observe a system as it executes and collects data relating to the program itself: its classes and methods and the resources they consume. JQuantify helps you collect information about events and sequences meaningful to the application domain. For example, a system that automatially seaches web pages might use JQuantify to discover that it's rate of page hits peaked at 78.2 pages per minute at 3:05am and is currently hitting pages at only 7.1 per minute. A profiler, on the other hand, might discover that the program spent 11% of its CPU time in String concatenation. (Obviously, a developer could use JQuantify to count specific method calls and observe time spent within those methods in order to gather some profiling data, but true profiler tools are much more flexible for this purpose.)

When and where is it measured
JQuantify is carefully designed to have very low overhead, both in terms of memory and CPU resources, specifically to be well suited for use in production systems. It is recommended that system designers identify measurable units of work early in the design phase and that developers use JQuantify or similar tool for instrumenting the system as it is built. As the system is deployed to its production environment, that same instrumentation remains in place to help validate the system's performance. Profilers, in order to gather the data necessary to identify specific hot-spots and problem areas in the running program, introduce substantial additional overhead to the running programs and are therefore not recommended to be used in normal day-to-day operations.  A profiler is an extremely valuable tool that is used at certain points of a system's development and/or optimization, but is not considered to be part of the system during normal operations.

What is the purpose
In summary, a profiler's role is primarily exploratory and diagnostic in nature, whereas JQuantify is particularly useful in describing the volume and responsiveness of work units the software is performing during normal operation.

JQuantify 3.3 Release 

This 3.3 release of JQuantify addresses several bugs discovered in testing the earlier releases. It is licensed under the GPL agreement. If you need to use JQuantify within your product or application in a manner not authorized under the GPL, please contact us at berrypartners@comcast.net to arrange for a commercial license.

Questions, bug reports, and feature requests are all therefore greatly appreciated.