Overview (Java Simon 4.1.4 API)

Packages
Package	Description
org.javasimon	Core package, contains `Simon` implementations, with the `SimonManager` as the center point of the API.
org.javasimon.aop	Contains AOP related annotation `Monitored`.
org.javasimon.callback	`Callback` is an event listener registered with the `Manager`, listening for manager or Simon events.
org.javasimon.callback.async
org.javasimon.callback.calltree	`CallTreeCallback` gathers information for current thread and displays it subsequent calls like a tree.
org.javasimon.callback.lastsplits	`LastSplitsCallback` retains last splits in a ring a buffer (fixed size FIFO queue).
org.javasimon.callback.logging	`LoggingCallback` is able to log stopwatch splits and statistics once in a while (N per millisecond, every N split, when split is longer than N ms, etc.) and to various outputs (SLF4J, JUL).
org.javasimon.callback.quantiles	`QuantilesCallback` sorts splits to categories (`Bucket`s) based on time ranges.
org.javasimon.callback.timeline
org.javasimon.clock
org.javasimon.console	Java Simon embeddable Web console base package.
org.javasimon.console.action	All controllers (aka Action beans in Struts world) are located in this package.
org.javasimon.console.html	HTML generation helper classes.
org.javasimon.console.json	Simplified JSON serializer used for Ajax communication and the REST API
org.javasimon.console.plugin
org.javasimon.console.reflect	Reflection tools to dynamically extract information from Simons.
org.javasimon.console.text	Machinery to convert potentially anything to a String (said differently a configurable toString() API).
org.javasimon.javaee	Java EE support for Simons contains Java EE components (servlet filter and EJB/CDI interceptor) that can be used or extended.
org.javasimon.javaee.reqreporter	Package contains classes reporting slow HTTP requests - interface `RequestReporter` and various (default) implementations.
org.javasimon.jdbc4	Simon JDBC 4.1 (Java SE 7) Proxy Driver for monitoring JDBC drivers through the Java Simon API.
org.javasimon.jdbc4.jmx	Work in progress: MX beans specific to Simon JDBC driver.
org.javasimon.jdbcx4	Simon DataSources for JavaEE JDBC monitoring.
org.javasimon.jmx	JMX capabilities for Simons.
org.javasimon.proxy	Provides everything to wrap any class a Proxy generated with java.lang.reflect.
org.javasimon.source	`MonitorSource` is the interface used as function to transform execution context (method invocation, HTTP request...) into a Simon.
org.javasimon.spring	Support classes to automatically monitor Spring beans with the `Monitored` annotation.
org.javasimon.spring.webmvc	`MonitoringHandlerInterceptor` is a Spring MVC interceptor which can be used to monitor time spent in Controller and View.
org.javasimon.utils	Java Simon supporting utilities and tools.
org.javasimon.utils.bean

Java Simon API provides support for implementing an internal application performance monitoring. Monitors (called Simons) have to be incorporated directly into the code and API provides additional management features for these monitors.

Java Simon is not a tool for profiling in the first place - it is rather a library that helps to implement performance (and other metrics) monitoring directly in the application as the integral part of it. Measured metrics can be sampled and stored persistently for later processing, trend analyzing, problem tracking, etc. It helps to give an additional perspective (history) to the application.

Using Stopwatch

Stopwatch is probably the most often used monitor. Simple use case looks like this:

    Stopwatch stopwatch = SimonManager.getStopwatch("stopwatch-name");
    Split split = stopwatch.start();
    //... measured code
    split.stop();

Monitors are always obtained from the Manager - in this case so called "default manager" is used via convenient utility class SimonManager. Every time the same name of the monitor is requested the same monitor is returned.

If there is no need for explicit stopwatch reference, the first two lines can be shortened to:

    Split split = SimonManager.getStopwatch("stopwatch-name").start();

Instead of stopping the stopwatch directly, there is the Split object that represents the measured time-span. Client code has to keep this reference in order to stop the measuring, but it also allows for multiple splits measured in parallel without binding them to specific threads.

How are Simons organized

Simon names form a hierarchy similar to Java Logging API. It is possible to disable whole subtrees of Simons to minimiaze performance penalty (mostly neglectable) or use SimonUtils to perform other operations on the hierarchy (print Simon tree, aggregations, ...).

Example of the Simon tree (partial) printed with the help of SimonUtils.simonTreeString(org.javasimon.Simon):

jdbc(+): Unknown Simon:  [org.javasimon.jdbc INHERIT]
  conn(+): Simon Stopwatch: total 41.4 ms, counter 1, max 41.4 ms, min 41.4 ms, mean 41.4 ms [org.javasimon.jdbc.conn INHERIT]
        commits(+): Simon Counter: counter=2, max=2, min=undef [org.javasimon.jdbc.conn.commits INHERIT]
        rollbacks(+): Simon Counter: counter=0, max=undef, min=undef [org.javasimon.jdbc.conn.rollbacks INHERIT]
  stmt(+): Simon Stopwatch: total 26.6 ms, counter 3, max 13.7 ms, min 3.81 ms, mean 8.88 ms [org.javasimon.jdbc.stmt INHERIT]
  sql(+): Unknown Simon:  [org.javasimon.jdbc.sql INHERIT]
        insert(+): Simon Stopwatch: total 1.18 ms, counter 2, max 1.02 ms, min 161 us, mean 592 us [org.javasimon.jdbc.sql.insert INHERIT]
          125069376(+): Simon Stopwatch: total 1.18 ms, counter 2, max 1.02 ms, min 161 us, mean 592 us [org.javasimon.jdbc.sql.insert.125069376 INHERIT "insert into foo values (?, ?)"]
        call(+): Simon Stopwatch: total 8.50 ms, counter 1, max 8.50 ms, min 8.50 ms, mean 8.50 ms [org.javasimon.jdbc.sql.call INHERIT]
          519218118(+): Simon Stopwatch: total 8.50 ms, counter 1, max 8.50 ms, min 8.50 ms, mean 8.50 ms [org.javasimon.jdbc.sql.call.519218118 INHERIT "call foo_proc(?, ?)"]
        select(+): Simon Stopwatch: total 13.1 ms, counter 1, max 13.1 ms, min 13.1 ms, mean 13.1 ms [org.javasimon.jdbc.sql.select INHERIT]
          -402642902(+): Simon Stopwatch: total 13.1 ms, counter 1, max 13.1 ms, min 13.1 ms, mean 13.1 ms [org.javasimon.jdbc.sql.select.-402642902 INHERIT "select * from foo"]
                next(+): Simon Stopwatch: total 46.5 us, counter 4, max 32.4 us, min 4.27 us, mean 11.6 us [org.javasimon.jdbc.sql.select.-402642902.next INHERIT]
  rset(+): Simon Stopwatch: total 195 us, counter 1, max 195 us, min 195 us, mean 195 us [org.javasimon.jdbc.rset INHERIT]

Hierarchy is held by Manager that is most easily accessed via convenient static class SimonManager (but there can be more managers, it is up to the user how to organize them). Manager provides access to the Simons (one manager, one hierarchy) and other management operations related to one set of Simons. Whole manager can be disabled which is even stronger form of disabled Simon (with close to no performance overhead - see DisabledEnabledComparison from example classes).

Support components

Being able to put a Stopwatch anywhere is powerful because one is not limited to method beginning or end, split allows to stop the stopwatch in a different thread, etc. Drawback is that the code might get poluted with various Simon code. Simon API provides a few tools how to get results quickly with minimal to no coding:

SimonServletFilter measures HTTP requests and provides simple way how to display tree of all Simons or clear the Manager. Filter can also report long requets along with all splits collected during the request.
Embeddable (servlet/filter) or standalone (war) web console is provided that can show all Simons in the table or tree, sort them, filter them, etc.
Spring integration (package org.javasimon.spring) helps monitor calls to beans - poitcut can be configured in Spring config or application can be scanned for Monitored annotations (Spring AOP). Annotation can be also used to further configure Stopwatch names.
Spring Web MVC integration is provided in org.javasimon.spring.webmvc.
JDBC proxy driver is provided (Driver) - monitors virtually all JDBC API calls. In simple scenarios only the change of the JDBC URL is required - just add simon: in front of the real name of the driver (e.g. jdbc:simon:h2:...). In more complex scenarios configuration change may be required - for example, original data source class has to be switched to Java Simon data source and original datasource will be provided as a parameter.

In addition to this Simon provides JMX support (see org.javasimon.jmx) or simple EJB/CDI intercpetor.

It is also very easy to hook onto Simon events (create/destroy of the Simon, measuring, start/stop, ...) using Callback facility (set up on the Manager object).