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.

Enabling Tracing by Using the Logging.Properties File

You can also enable tracing by using the logging.properties file, which can be found in the lib directory 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.