The JDBC monitoring options allow you control many aspects of how FusionReactor tracks metrics from a data source including for example, how to name a data source in FusionReactor and how to exclude a JDBC data source from FusionReactor. The options can be configured using JDBC URL parameters or the JDBC properties of a data source.
If specified, the data source will report SQL metrics to FusionReactor with the given name. These names will be reported in the JDBC logfile (or as an empty value if not set). The name will also be reflected in the JDBC tab of the Request Details page, allowing the user to differentiate queries which ran against more than one datasource. This is useful when multiple databases are being used to aggregate results, or when different drivers are being tested.
If true, the data source will NOT report SQL metrics to FusionReactor.
Default: 0 (disabled).
This option instructs the FusionReactor to limit returned rows to the given value.
After the application has retrieved this number of rows from the result set, FusionReactor will discard any remaining rows.
Default: 0 (disabled).
This option instructs the FusionReactor to output a notification after 'n' rows have been retrieved for the query.
Default: 0 (disabled).
This option instructs the FusionReactor to periodically output a query reminder every 'n' rows. If notifyAfter is specified, FusionReactor will only begin reminding after the notification threshold has been reached.
E.g. notifyAfter=1000, remindAfter=100, actual rowcount 1350.
Notification occurs at row 1000, reminders at 1100, 1200 and 1300.
When tracking queries, the FusionReactor will reformat them for logging and presentation by attempting to make them fit on a single line.
This allows logs to be viewed more easily, but may hinder developers who are used to seeing queries formatted a certain way (as they are written in a web page, for example). Setting this option to 'true' stops FusionReactor reformatting statement text, and allows multi-line presentation in the FusionReactor interface and log.
If set to true (the default) and the FusionReactor detects a running FusionReactor instance, it will log the execution of a query to FusionReactors 'jdbc-X.log' (where 'X' is the current rolling log number).
If this option is enabled and FusionReactor was not detected, it has no effect.
If set to true (the default), when a PreparedStatement attempts to bind an Object type to a positional parameter using one of the setObject(...) methods, FusionReactor will attempt to interpret the data (for logging and reporting purposes only) by calling the toString() method on the object. This value will then be used in the log and FusionReactor administrator, as if the application had called a setString(...) method. If the object does not override the default toString() method, the default behavior is to return the hash code of the object.
If this parameter is false, the wrapper FusionReactor will use the format
where xyz is the .toString() representation. This makes it clear that the parameter is of type Object, but is perhaps less easy to read in the log and the Administrator.
If specified, the FusionReactor will turn off autocommit for all statements from this data source, regardless of the current status of autocommit, or the existence of any transactions. This option must be used with extreme caution as it alters the default behaviour of the JDBC system, and is provided as a workaround to J2EE servers which require it to be disabled. We do not recommend using this option to defeat autocommit. After enabling this option, you must verify the atomicity and transactional integrity of your application's JDBC statements.
How To Specify the JDBC Monitoring Options
Adding Data Source Properties
If you application server supports adding properties to the datasource, you can configure FusionReactor's JDBC monitoring options by adding a datasource property with the name of the option and the value as required. This is the preferred way of configuring options.
Altering the JDBC URL
If you application server does not support adding properties to the datasource, you can configure FusionReactor's JDBC monitoring options by altering the JDBC URL.
Here's an example of a SQL Server JDBC URL, using the Microsoft SQL driver, to which a couple of FusionReactor options have been added.
You can see that in this example, the notifyAfter, remindAfter and name options have all been specified. The databaseName option pertains to the JDBC driver.
Excluding a Data Source from Monitoring
In some cases you may not want FusionReactor to monitor a JDBC data source. To exclude a JDBC data source from being monitored, add the__fusionreactor_exclude property to the datsource properties with the value true.
If the application server does not support adding properties to the data source, below is an example of how to exclude a data source from monitoring by altering the JDBC URL (using the Microsoft SQL driver).
Sample JDBC URLs
Here are a few examples of URLs, wrapped with the FusionReactor Driver Wrapper. This section is not an exhaustive reference on the syntax of each URL - you should check the documentation for each individual driver. In general we recommend downloading and using vendor-specific drivers if possible.
Using the Oracle Thin driver, with the name option (note that expanded syntax is used so that FusionReactor options can be added):
Using the Macromedia driver, with the notifyAfter FusionReactor Driver Wrapper option:
MySQL 4/5 (MySQL Commercial)
Using the MySQL commercial driver:
MySQL 5 Connector/J (MySQL)
Here's an example using the MySQL Connector/J driver, downloadable from mysql.com.
Using the MySQL GJT driver, with the inhibitReformat FusionReactor Driver Wrapper option:
Microsoft JDBC Driver 4.0 for SQL Server (Microsoft)
Here's a URL using the Microsoft SQL Server 2005 JDBC Driver
In this example, the username and password must be specified separately during the connection process. Here's an example where the username and password is specified in the URL:
Microsoft SQL Server (Macromedia)
Using the Macromedia driver, with the remindAfter (we've named this data source too):
DerbyEmbedded (Apache Derby)
The Apache Derby embedded database is an in-process (no separate server) database. When this database driver is loaded, the database is started in the JVM process itself, a procedure which may only occur one time, until the database is subsequently stopped. You should therefore only used this database with a wrapped datasource; you should not mix wrapped and unwrapped access to this datasource. If you do mix these datasources, FusionReactor will attempt to share the connection with the wrapped and unwrapped datasource - which works in most cases - though this is an unsupported configuration.
This URL explicitly specifies the driver, together with its jar, and the autocommit option - also explained at the link above.