How To Trace the JDBC driver

To Bottom

In this Document
Goal
Solution
Managing log files
References
APPLIES TO:
JDBC - Version 10.1.0 to 12.1.0.1.0
Information in this document applies to any platform.
GOAL
The purpose of this document is to illustrate the JDBC 10g/11g tracing feature. This is also
referred as JDBC logging.
JDBC logging is now documented in the JDBC Developer's guide:
Oracle Database JDBC Developer's Guide,
11g Release 2 (11.2)
Part Number E16548-02
31 Diagnosability in JDBC
Logging
Oracle Database JDBC Developer's Guide
12c Release 1 (12.1)
E49300-05
32 Diagnosability in JDBC
Logging

Prior to JDBC 10g, the JDBC 9i driver used a different method for logging. Starting with 10gR1
and as of current versions, the JDBC driver relies on the standard java.util.loggingframework
provided with JDK 1.4 and higher.

SOLUTION
The JDBC driver tracing facility utilizes package java.util.logging. There are two ways to initiate
JDBC tracing:

use system properties

java.util.logging API

This document introduces the tracing loggers and levels then describes two approaches to
implement tracing.
Tracing Loggers
The user has fine grained control over the tracing by setting specific loggers. The tracing loggers
are:

oracle.jdbc

oracle.jdbc.driver

oracle.jdbc.datum

oracle.jdbc.adt

oracle.jdbc.conversion

oracle.jdbc.thin

oracle.jdbc.kprb

oracle.jdbc.pool

oracle.jdbc.xa

oracle.jdbc.sqlj

oracle.jdbc.oci

oracle.jdbc.jpub

Tracing Levels
For every logger there are different levels one can set. Depending on the information required
one can specify general level with less output or very detailed output. The tracing levels can have
the following values:

INFO
o JDBC API level tracing
o expected volume: low

SEVERE
o

Program error eg. an unexpected value encountered in a switch statement

o Error conditions that usually lead to catastrophic or unrecoverable results

o expected volume: low

WARNING
o Error conditions that are usually recoverable
o expected volume: low

FINE
o Function entry/return information
o expected volume: medium

FINER
o High-level debug information
o expected volume: medium

FINEST
o Detail debug information

o expected volume: high

CONFIG
o SQL string
o expected volume: low

Tracing JDBC Using System Properties

To enable the logging by using System properties you will need a so called properties file. The
JDBC directory has a complete sample logging properties file calledOracleLog.properties. This
file is located in $ORACLE_HOME/jdbc/demo provided you have installed the demonstrations
using the Database Companion CD. This file controls the tracing levels, tracing loggers, and
output formatting. This approach offers the advantages of being able to set tracing without
having to recompile the application. Use either the properties file provided in the demo directory
or build your own based on the sample provided in this note. To use this way of tracing do
following steps:

1. Use a JDK 1.4.x or higher JDK version

2. Use the debug library of the JDBC Driver, such as ojdbc14_g.jar 10g driver
or ojdbc5_g.jar or ojdbc6_g.jar 11g driver
3. Create a properties file to set the different levels of tracing, for example:
handlers=java.util.logging.ConsoleHandler,java.util.logging.FileHandler
# default file output is in user's home directory.
java.util.logging.FileHandler.pattern = jdbc.log
# example of a full pathname in Windows
#java.util.logging.FileHandler.pattern=D:\\temp\\jdbc123.log
java.util.logging.FileHandler.limit = 50000
java.util.logging.FileHandler.count = 1
java.util.logging.FileHandler.formatter = java.util.logging.XMLFormatter
java.util.logging.FileHandler.append = true
# Predefined levels are: ALL, SEVERE, WARNING, INFO, CONFIG, FINE, FINER,
#
FINEST, OFF
# Setting this to SEVERE avoids duplicate output from default logger
java.util.logging.ConsoleHandler.level = SEVERE
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter

oracle.jdbc.level = FINEST

4. To run the test with tracing enabled use following command:

java -Doracle.jdbc.Trace=true -Djava.util.logging.config.file=<properties file location>
<program name>

Tracing JDBC Using java.util.logging API

This approach offers the advantage to toggle on/off tracing during program flow. However,
application code must be recompiled.
import oracle.jdbc.driver.OracleLog;
...
// set the file handler
FileHandler handler = new FileHandler("oracle.log");
// designate the module to be traced
Logger logger = Logger.getLogger("oracle.jdbc");
// set the tracing level
logger.setLevel(Level.FINE);
// Add file handler to the desired logger
logger.addHandler(handler);
// turn on trace
OracleLog.setTrace(true);
// do some jdbc stuff
...
// turn off trace
OracleLog.setTrace(false);
...