Package org.javasimon.jdbc

Simon JDBC Proxy Driver for monitoring JDBC drivers through the Java Simon API.

See:
Description

Class Summary

Driver	Simon JDBC Proxy Driver.
Driver.Url	Class Url represents Simon JDBC url.
SimonCallableStatement	Simon JDBC proxy callable statement implemntation class.
SimonConnection	Class implements Simon JDBC proxy connection.
SimonPreparedStatement	Simon JDBC proxy prepared statement implementation class.
SimonResultSet	Simon JDBC proxy result set implementation class.
SimonStatement	Simon JDBC proxy statement implementation class.
SqlNormalizer	SqlNormalizer takes SQL statement and replaces parameters with question marks.

Package org.javasimon.jdbc Description

Simon JDBC Proxy Driver for monitoring JDBC drivers through the Java Simon API.

Main goal of monitoring the JDBC driver through the Simon JDBC Proxy Driver is to gain data about so-called monitored entities of the JDBC driver, which could provide reasonable information about their usage in the monitored system.

Following JDBC entities are monitored at this time:

• Connections,
• statements - objects in JVM,
• SQL commands - commands like select, insert, update, etc, but also create, truncate and others, so than you can know how many selects vs. inserts vs. updates are present in your system or how long took their execution,
• SQL command groups - command group means same command with different parameters, typically systems in general has final set of different select or updates (unless it is SQL editor).

Each entity has several monitoring parameters:

Connection:

• active conns - count of actual active opened connections;
• max active conns - maximum active opened connection at same time;
• opened - summary count of all opened connections - difference between this number and closed should equals active in any time, if not this could idicate unclosed connections (close was not invoked);
• closed - summary count of all closed connections - difference between this number and opened should equals active in any time;
• minimum lifespan - minimum time of all connections life (time between getConnection and close;
• average lifespan - average time of all connection life;
• maximum lifespan - maximum time of all connection life;
• commits - summary count of all commits issued by commit - this counter is incresed only by invoking method commit, therefore if autocommit is true counter is not representative;
• rollbacks - summary count of all rollbacks issued by rollback - this counter is incresed only by invoking method rollback, therefore if autocommit is true counter is not representative.

Statement:

• active stmt - count of actual active opened statements;
• max active stmt - maximum active opened statements at same time;
• opened - summary count of all opened statements - difference between this number and closed should equals active in any time, if not this could idicate unclosed statements close was not invoked;
• closed - summary count of all closed statements - difference between this number and opened should equals active in any time;
• minimum lifespan - minimum time of all statements life (time between createStatement, prepareStatement or prepareCall and close);
• average lifespan - average time of all statements life;
• maximum lifespan - maximum time of all statements life.

SQL command (select, insert, delete, call, ...):

• minimum execution - minimum time of all desired sql command execution times - typically execution time of executeQuery, executeUpdate or execute;
• average execution - average time of all desired sql command execution times;
• maximum execution - maximum time of all desired sql command execution times;
• first - time of first occurence of desired SQL command;
• last - time of last occurence of desired SQL command.

SQL:

• minimum execution - minimum time of all desired sql command execution times (typically execution time of executeQuery, executeUpdate or execute);
• average execution - average time of all desired sql command execution times;
• maximum execution - maximum time of all desired sql command execution times;
• first - time of first occurence of desired SQL command;
• last - time of last occurence of desired SQL command;
• note - "normalized" SQL command (SQL command without concrete values with question marks instead - similar to prepared statement syntax).

From technical point of view, Simon JDBC Proxy Driver is based on a simple idea of the proxy driver that delegates invocations to the real driver which is wrapped. This allows to intercept invocations to the real driver and measure (or count) them.

However, the goal is not to measure each invocation on every possible function of JDBC driver (there are another techniques like profiling for that purpose), but just monitor those functions of driver which somehow influence paramater values of monitored entities mentioned earlier.

Simon driver implements just a few basic JDBC interfaces, like Connection and all Statments. Rest of the JDBC interfaces (from java.sql.* package) are not implemented by Simon driver. Therefore result of some invocations are not Simon driver classes, but directly classes from real driver. For example, as result of invoke method Connection.createStatement is returned Simon driver class org.javasimon.jdbc.Statement, however result of invoking method Statement.executeQuery is returned concrete implementation class of real driver, i.e. for H2 driver class org.h2.jdbc.JdbcResultSet.

Simons are used to monitor aforementioned entities. To measure time parameters like execution time Stopwatch Simons are used. To count how many statements are open Counter Simons are used.

Each Simon is placed in the tree hierarchy (basic feature of Simon) and the place is strictly defined inside the driver. Therefore you can use static configuration of those Simons by defining their state in the config file (for more information see SimonConfigTest.java example).

Hierarchy of Simons in Simon JDBC proxy driver is following:

org.javasimon.jdbc
 |
 +-> .conn
 |     +-> .commits
 |     +-> .rollbacks
 |
 +-> .stmt
 |     +-> .active
 |
 +-> .sql
 |     +-> .<sql type (select, insert, ...)>
 |           +-> .<sql hash>

For choosing Simon's name is used prefix. If non is defined, default is org.javasimon.jdbc. If default prefix value is not suficient or you need to differentiate between two different drivers (or its configuration) you can define your own prefix as parameter SIMON_PREFIX=<prefix> within JDBC connection string. For example, jdbc:simon:....;SIMON_PREFIX=com.foo.bar. More about setuping Simon JDBC proxy driver see Driver.

For printing information from Simons to standard output you can use:

 SimonUtils.printSimonTree(SimonManager.getRootSimon());

Also see examples classes examples.jdbc.Simple and examples.jdbc.Complex.