# 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.

#### 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.sampledomain.com:1528/mydb" +
     ";traceFile=/u/user1/trace.out" +
     ";traceLevel=" +
     org.apache.derby.jdbc.ClientDataSource.TRACE_PROTOCOL_FLOWS;
    DriverManager.getConnection(url,"user1","secret4me");

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.

Parent topic: Accessing the Network Server by using the network client driver
Related concepts
Network client security
Related reference
Network client driver examples