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 three ClientDataSource implementations. You can use the org.apache.derby.jdbc.ClientDataSource class on Java SE 5 and above (except Java SE 8 Compact Profiles), in applications that call JDBC 3 or JDBC 4.0 methods. You can use the org.apache.derby.jdbc.ClientDataSource40 class on Java SE 6 and above (except Java SE 8 Compact Profiles), in applications that call JDBC 4.1 or JDBC 4.2 methods. You must use the org.apache.derby.jdbc.BasicClientDataSource40class on Java SE 8 Compact Profile 2 or 3.

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:

Use bitwise OR operators ( | ) with two or more trace values. For example, to trace PROTOCOL flows and connection calls, specify this value for traceLevel:
```
TRACE_PROTOCOL_FLOWS | TRACE_CONNECTION_CALLS
```
Use a bitwise complement operator ( ~ ) with a trace value to specify all except a certain trace. For example, to trace everything except PROTOCOL flows, specify this value for traceLevel:
```
~TRACE_PROTOCOL_FLOWS
```

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