Network client tracing

The Derby Network client provides a tracing facility to collect JDBC trace information and view protocol flows.

There are various ways to obtain trace output. However, the easiest way to obtain trace output is to use the traceFile=path attribute on the URL in ij. The following example shows all tracing going to the file trace.out from an ij session.

ij>connect 'jdbc:derby://localhost:1527/mydb;
create=true;traceFile=trace.out;user=user1;password=secret4me';

To append trace information to the specified file, use the traceFileAppend=true URL attribute in addition to traceFile=path.

For more information, see "traceFile=path attribute" and "traceFileAppend=true attribute" in the Derby Reference Manual.

Implementing ClientDataSource tracing

You can use one of three methods to collect tracing data while obtaining connections from the ClientDataSource:
  • Use the setLogWriter(java.io.PrintWriter) method of ClientDataSource and set the PrintWriter to a non-null value.
  • Use the setTraceFile(String filename) method of ClientDataSource.
  • Use the setTraceDirectory(String dirname) method of ClientDataSource to trace each connection flow in its own file for programs that have multiple connections.

Derby provides two ClientDataSource implementations. You can use the org.apache.derby.jdbc.ClientDataSource class on all supported Java SE versions except Java SE 8 Compact Profile 2. On Java SE 8 Compact Profile 2, you must use the org.apache.derby.jdbc.BasicClientDataSource40 class. For more information, see "JDBC support for Java SE 8 Compact Profiles" in the Derby Reference Manual.

Implementing DriverManager tracing

Use one of the following two options to enable and collect tracing information while obtaining connections using the DriverManager:
  • Use the setLogWriter(java.io.PrintWriter) method of DriverManager and set the PrintWriter to a non null-value.
  • Use the traceFile=path or traceDirectory=path URL attributes to set these properties prior to creating the connection with the DriverManager.getConnection() method. For more information, see "traceFile=path attribute" and "traceDirectory=path attribute" in the Derby Reference Manual.

Changing the default trace level

The default trace level is ClientDataSource.TRACE_ALL. You can choose the tracing level by calling the setTraceLevel(int level) method or by setting the traceLevel=value URL attribute:

String url = "jdbc:derby://samplehost.example.com:1528/mydb" +
 ";traceFile=/u/user1/trace.out" +
 ";traceLevel=" +
 org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS;
DriverManager.getConnection(url,"user1","secret4me");

The following table shows the tracing levels you can set.

Table 1. Available tracing levels and values
Trace Level Value
org.apache.derby.jdbc.ClientDataSource.TRACE_NONE 0x0
org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTION_CALLS 0x1
org.apache.derby.jdbc.ClientDataSource.TRACE_STATEMENT_CALLS 0x2
org.apache.derby.jdbc.ClientDataSource.TRACE_RESULT_SET_CALLS 0x4
org.apache.derby.jdbc.ClientDataSource.TRACE _DRIVER_CONFIGURATION 0x10
org.apache.derby.jdbc.ClientDataSource.TRACE_CONNECTS 0x20
org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS 0x40
org.apache.derby.jdbc.ClientDataSource.TRACE _RESULT_SET_META_DATA 0x80
org.apache.derby.jdbc.ClientDataSource.TRACE _PARAMETER_META_DATA 0x100
org.apache.derby.jdbc.ClientDataSource.TRACE_DIAGNOSTICS 0x200
org.apache.derby.jdbc.ClientDataSource.TRACE_XA_CALLS 0x800
org.apache.derby.jdbc.ClientDataSource.TRACE_ALL 0xFFFFFFFF

To specify more than one trace level, use one of the following techniques:

For more information, see "traceLevel=value attribute" in the Derby Reference Manual.

Related reference
Network client driver examples