Tracing Driver Operation
The Microsoft SQL Server 2005 JDBC Driver supports the use of tracing (or logging) to help resolve issues and problems with the JDBC driver when it is used in your application. To enable the use of tracing, the JDBC driver uses the logging APIs in java.util.logging, which provides a set of classes for creating Logger and LogRecord objects.
Note
For the native component (sqljdbc_xa.dll) that is included with the JDBC driver, tracing is enabled by the Built-In Diagnostics (BID) framework. For information about BID, see Data Access Tracing in SQL Server 2005.
When you develop your application, you can make calls to Logger objects, which in turn create LogRecord objects, which are then passed to Handler objects for processing. Logger and Handler objects both use logging levels, and optionally logging filters, to regulate which LogRecords are processed. When the logging operations are complete, the Handler objects can optionally use Formatter objects to publish the log information.
By default, the java.util.logging framework writes its output to a file. This output log file must have write permissions for the context under which the JDBC driver is running.
Note
For more information about using the various logging objects for program tracing, see the Java Logging APIs documentation on the Sun Microsystems Web site.
The following sections describe the logging levels and the categories that can be logged, and provide information about how to enable tracing in your application.
Logging Levels
Every log message that is created has an associated logging level. The logging level determines the importance of the log message, which is defined by the Level class in java.util.logging. The following table describes each of the available logging levels.
| Name | Description |
|---|---|
SEVERE |
Indicates a serious failure and is the highest level of logging. In the JDBC driver, this level is used for reporting errors and exceptions. |
WARNING |
Indicates a potential problem. |
INFO |
Provides informational messages. |
CONFIG |
Provides configuration messages. In the JDBC driver, this level is used for configuration settings that are global in scope. |
FINE |
Provides tracing information. In the JDBC driver, this level is used for most log messages. |
FINER |
Provides detailed tracing information. |
FINEST |
Provides highly detailed tracing information. This is the lowest level of logging. |
OFF |
Turns off logging. |
ALL |
Enables logging of all messages. |
Logging Categories
When you create a Logger object, you must tell the object which named entity or category that you are interested in getting log information from. The JDBC driver supports the following logging categories.
| Name | Description |
|---|---|
SQLServerConnection |
Logs messages in the SQLServerConnection class. The default logging level is FINE. |
SQLServerStatement |
Logs messages in the SQLServerStatement class. The default logging level is FINE. |
TDS.DATA |
Logs TDS messages. This category creates very verbose and detailed messages, and can only be enabled by setting the logging level to FINEST. |
TDS.TOKEN |
Logs TDS messages. This category logs only the tokens within the TDS packets, and is less verbose than the TDS.DATA category. |
XA |
Logs messages for all XA transactions in the SQLServerXAConnection, SQLServerXAResource, and SQLServerXADataSource classes. The default logging level is FINE. |
SQLServerDataSource |
Logs messages in the SQLServerDataSource, SQLServerConnectionPoolDataSource, and SQLServerPooledConnection classes. The default logging level is FINE. |
Enabling Tracing Programmatically
Tracing can be enabled programmatically by creating a Logger object and indicating the category to be logged. For example, the following code shows how to enable logging for SQL statements:
Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.SQLServerStatement");
logger.setLevel(Level.FINE);
To turn off logging in your code, use the following:
logger.setLevel(Level.OFF);
To log all available categories, use the following:
Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc");
logger.setLevel(Level.FINE);
To disable a specific category from being logged, use the following:
Logger logger = Logger.getLogger("com.microsoft.sqlserver.jdbc.TDS");
logger.setLevel(Level.OFF);
Enabling Tracing by Using the Logging.Properties File
You can also enable tracing by using thelogging.propertiesfile, which can be found in thelibdirectory of your Java Runtime Environment (JRE) installation. This file can be used to set the default values for the loggers and handlers that will be used when tracing is enabled.
The following is an example of the settings that you can make in the logging.properties files:
# Specify the handlers to create in the root logger
# (all loggers are children of the root logger).
# The following creates two handlers.
handlers = java.util.logging.ConsoleHandler, java.util.logging.FileHandler
# Set the default logging level for the root logger.
.level = OFF
# Set the default logging level for new ConsoleHandler instances.
java.util.logging.ConsoleHandler.level = FINE
# Set the default logging level for new FileHandler instances.
java.util.logging.FileHandler.level = OFF
# Set the default formatter for new ConsoleHandler instances.
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
# Set the default logging level for the logger named ConnectionPool.
ConnectionPool.level = OFF
Note
You can set the properties in the logging.properties file by using the LogManager object that is part of java.util.logging.