Child pages
  • JDBC Monitoring Options
Skip to end of metadata
Go to start of metadata

Monitoring Options

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.

__fusionreactor_name

Value: string
Default: empty

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.

__fusionreactor_exclude

Value: boolean
Default: false

If true, the data source will NOT report SQL metrics to FusionReactor.

__fusionreactor_rowLimit

Value:  integer
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.

__fusionreactor_notifyAfter

Value: integer
Default: 0 (disabled).

This option instructs the FusionReactor to output a notification after 'n' rows have been retrieved for the query.

__fusionreactor_remindAfter

Value: integer
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.

__fusionreactor_inhibitReformat

Value: Boolean
Default: false.

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.

__fusionreactor_logToFusionReactor

Value: Boolean
Default: true.

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.

__fusionreactor_interpretObjects

Value: Boolean
Default: true.

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

{OBJECT java.class.name xyz}

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.

 

__fusionreactor_autoCommit

Value: Boolean
Default: true

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.

jdbc:sqlserver://int0007:1433;databaseName=frtest;__fusionreactor_notifyAfter=1000;__fusionreactor_remindAfter=200;__fusionreactor_name=DataWarehouse

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.

If you can add properties to the data source, it is the preferred over changing the JDBC URL.
Different JDBC drivers use different delimiter characters between arguments to the driver (common delimiters are ; & , : ). You must specify the FusionReactor options using the correct delimiter for the JDBC driver that you are configuring.

 

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).

jdbc:sqlserver://int0007:1433;databaseName=frtest;__fusionreactor_exclude=true

 

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.  

Oracle (Thin)

Using the Oracle Thin driver, with the name option (note that expanded syntax is used so that FusionReactor options can be added):

jdbc:oracle:thin:@(DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=192.168.1.56)(PORT=1521))(CONNECT_DATA=(SID=orcl)(__fusionreactor_name=orclthin)(__fusionreactor_rowlimit=12345)))

Oracle (Macromedia)

Using the Macromedia driver, with the notifyAfter FusionReactor Driver Wrapper option:

jdbc:macromedia:oracle://int0234:1521;SID=testdb;__fusionreactor_notifyAfter=10000

MySQL 4/5 (MySQL Commercial)

Using the MySQL commercial driver:

 

jdbc:mysql://int00d6.bbn.intergral.com:3306/TestApp?tinyInt1isBit=false&__fusionreactor_name=mysqldb

MySQL 5 Connector/J (MySQL)

Here's an example using the MySQL Connector/J driver, downloadable from mysql.com.

 

jdbc:mysql://int00d6.bbn.intergral.com:3306/TestApp?__fusionreactor_name=SQLServerDataSource

MySQL (Macromedia)

Using the MySQL GJT driver, with the inhibitReformat FusionReactor Driver Wrapper option:

jdbc:mysql://int0003:3306/webshopdb?defaultFetchSize=400;__fusionreactor_inhibitReformat=true

Microsoft JDBC Driver 4.0 for SQL Server (Microsoft)

Here's a URL using the Microsoft SQL Server 2005 JDBC Driver

jdbc:sqlserver://int00d0:1433;databaseName=AdventureWorks;__fusionreactor_name=testdb

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:

jdbc:sqlserver://int00d0:1433;databaseName=AdventureWorks;user=scott;password=tiger;__fusionreactor_name=testdb

Microsoft SQL Server (Macromedia)

Using the Macromedia driver, with the remindAfter (we've named this data source too):

jdbc:macromedia:sqlserver://int0007:1433;DatabaseName=frtest;__fusionreactor_remindAfter=500;__fusionreactor_name=SQLServerDataSource

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.

jdbc:derby:C:/ColdFusion10/cfusion/db/bookclub/;create=false;MaxPooledStatements=300;__fusionreactor_name=bookclubdb;__fusionreactor_autocommit=false
  • No labels