org.javasimon.jdbc4.package-info Maven / Gradle / Ivy
Show all versions of javasimon-jdbc41 Show documentation
/**
* Simon JDBC 4.1 (Java SE 7) 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 indicate unclosed connections
* ({@code 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 {@code getConnection}
* and {@code 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 {@code commit} - this counter is increased
* only by invoking method {@code commit}, therefore if autocommit is true counter is not representative;
*
- rollbacks - summary count of all rollbacks issued by {@code rollback} - this counter is
* increased only by invoking method {@code 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 indicate unclosed statements {@code 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 {@code createStatement},
* {@code prepareStatement} or {@code prepareCall} and {@code 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 {@code executeQuery}, {@code executeUpdate} or {@code 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 occurrence of desired SQL command;
*
- last - time of last occurrence of desired SQL command.
*
*
* SQL:
*
* - minimum execution - minimum time of all desired sql command execution times (typically
* execution time of {@code executeQuery}, {@code executeUpdate} or {@code 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 occurrence of desired SQL command;
*
- last - time of last occurrence 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.
*
* 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 parameter values of monitored entities mentioned earlier.
*
* Simon driver implements just a few basic JDBC interfaces, like Connection and all Statements. 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 {@code Connection.createStatement} is returned Simon driver
* class {@code org.javasimon.jdbc4.Statement}, however result of invoking method {@code Statement.executeQuery}
* is returned concrete implementation class of real driver, i.e. for H2 driver class {@code 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 {@code SimonConfigTest.java} example).
*
* Hierarchy of Simons in Simon JDBC proxy driver is following:
*
{@code
* org.javasimon.jdbc
* |
* +-> .conn
* | +-> .commits
* | +-> .rollbacks
* |
* +-> .stmt
* | +-> .active
* |
* +-> .sql
* | +-> .
* | +-> .}
*
* For choosing Simon's name is used prefix. If non is defined, default is {@code org.javasimon.jdbc}.
* If default prefix value is not sufficient or you need to differentiate between two different drivers
* (or its configuration) you can define your own prefix as parameter {@code SIMON_PREFIX=}
* within JDBC connection string. For example, {@code jdbc:simon:....;SIMON_PREFIX=com.foo.bar}. More
* about setting up Simon JDBC proxy driver see {@link org.javasimon.jdbc4.Driver}.
*
* For printing information from Simons to standard output you can use:
*
* SimonUtils.printSimonTree(SimonManager.getRootSimon());
*
* Also see examples classes {@code org.javasimon.examples.jdbc.Simple} and {@code org.javasimon.examples.jdbc.Complex}.
*
* @author Radovan Sninsky
* @author Richard "Virgo" Richter
* @since 2.4
*/
package org.javasimon.jdbc4;