Debug Tracing

All ODP.NET providers include debug tracing support, which allows logging of all the ODP.NET activities into a trace file. Different levels of tracing are available.

Tracing can record the following information and more:

Entry and exit information for the ODP.NET public methods
User-provided SQL statements as well as SQL statements modified by the provider
Connection pooling statistics such as enlistment and delistment
Thread ID (entry and exit)
HA Events and Load Balancing information
Distributed Transactions
Self-tuning information
User-mode dumps upon unmanaged exceptions

The following properties enable and configure tracing for all ODP.NET providers:

TraceLevel – specifies which ODP.NET details to write to the trace file
TraceFileLocation – specifies the directory to write the trace to
TraceFileMaxSize – specifies the maximum file size of each trace file
TraceOption – specifies whether to use a separate trace file for each thread

By default, tracing is turned off (TraceLevel = 0). To enable tracing, set TraceLevel to the trace level you wish.

Managed ODP.NET and ODP.NET Core have the following trace levels:

1 = public APIs
2 = private APIs
4 = network APIs/data
8 = disables writing SQL statements and network packet contents

These values can be bitwise ORed. To enable all traces, set TraceLevel to 7.

Unmanaged ODP.NET has the following trace levels:

1 = Entry, exit, and SQL statement information
2 = Connection pooling statistics
4 = Distributed transactions (enlistment and delistment)
8 = User-mode dump creation upon unmanaged exception
16 = HA Event Information
32 = Load Balancing Information
64 = Self Tuning Information

These values can be bitwise ORed. To enable all traces, set TraceLevel to 127.

TraceFileLocation writes to a temporary operating system folder if no value is set.

ODP.NET Core
- Windows: <Windows user temporary folder>\ODP.NET\core\trace
- Linux: <current user temporary folder>/ODP.NET/core/trace
- macOS: <macOS temporary folder>\ODP.NET\core\trace
ODP.NET, Managed Driver: <Windows user temporary folder>\ODP.NET\managed\trace
ODP.NET, Unmanaged Driver: <Windows user temporary folder>\ODP.NET\unmanaged\trace

The Windows user temporary folder is determined by your local Windows settings, such as your Windows TMP or TEMP environment variable. Typically, it can be C:\temp or C:\Users\<user name>\AppData\Local\Temp.

TraceFileMaxSize defaults to 100 MB if no value is set. Administrators can use this setting to keep trace files down to a manageable size.

TraceOption will write all threads to a single trace file at a time by default (TraceOption=0).

ODP.NET will create an entry in the Windows event log where the trace was created anytime it creates a new trace file. An event log entry will be added every time in cases when TraceFileLocation changes, trace file size exceeds TraceFileMaxSize, TraceLevel changes, and TraceOption changes. In each of these cases, ODP.NET creates a new file and starts writing traces in the newly created file. ODP.NET Core does not support writing to the Windows event log.

To enable ODP.NET tracing, these trace properties must be set appropriately either in the OracleConfiguration class (all providers), in the .NET configuration file (managed and unmanaged ODP.NET), or in the Windows Registry (unmanaged ODP.NET).

ODP.NET begins writing to the trace file only after the OracleConnection.Open() call occurs.

Dynamic Tracing

Starting with ODAC 19c, applications can change ODP.NET OracleConfiguration class trace settings during runtime. Most commonly, this feature would permit enabling and disabling tracing dynamically while applications continue to run. Dynamic tracing is useful for errors that occur after applications are run for a considerable time. Customers can avoid collecting extremely large trace files and Oracle Support will find it easier to diagnose problems from more targeted trace files.

ODP.NET Core, managed, and unmanaged all support dynamic tracing.

To enable tracing at runtime, set OracleConfiguration.TraceLevel to the trace level desired. To disable tracing dynamically, set OracleConfiguration.TraceLevel to zero.

Only OracleConfiguration tracing properties can alter runtime tracing behavior. Windows Registry and .NET configuration file settings are only read when an application starts up.

As a general matter, tracing is not recommended for production use because writing to trace files affects performance. However, if a problem only occurs during production, use dynamic tracing to enable and disable tracing during the problem period to capture diagnostics for identifying the root cause.