ODP.NET Tracing — Let’s Get Dynamic
ODP.NET debug tracing is not a feature you ever plan to use. Enabling it means you’ve hit a problem and need to collect diagnostic information to determine the root cause. ODP.NET can be directed to log some or all its activities into one or multiple trace files.
One challenge in using tracing can be very large file sizes. If a problem occurs early on in an app’s use, a small trace file is generated. A small file is easy to upload and evaluate. No problem there. Now, if the problem reproduces only after hours of operation, the trace file will be very large. When files are hundreds of megabytes or gigabytes in size, they are harder to upload and to debug with.
Another tracing problem occurs with production apps. Ideally, you don’t want to debug in a production setting. However, if a problem only occurs in production, you have no other choice. Tracing adds a performance overhead as a result of the frequent disk writes. App owners dislike the side effect of lowering their end users’ service level in production.
In ODAC 19c Release 1, ODP.NET has added two new tracing features to address these challenges:
- Dynamic tracing
- Trace file size limit
Dynamic tracing permits enabling and disabling trace output at runtime. Developers can turn on tracing only when the problem occurs, saving disk space and making it easier to share the final trace file. Moreover, the additional performance overhead need only occur for the small window of time when tracing is enabled.
To prevent any file from becoming too large, a trace file size limit can be set. When ODP.NET reaches the size limit, it creates a new trace file to continue writing the trace output.
These features are available in all three ODP.NET driver types: Core, managed, and unmanaged.
Dynamic Tracing
ODP.NET tracing uses three traditional settings:
TraceFileLocation— trace file directory locationTraceLevel— tracing levelTraceOption— generate a single trace file or one file per thread
These settings can be modified in .NET configuration files and in code via the OracleConfiguration class.
There are no new APIs introduced for dynamic tracing. Rather, to enable or disable tracing at runtime, a developer modifies the value of OracleConfiguration.TraceLevel. By default, tracing is disabled (TraceLevel=0). When an application changes the value of TraceLevel, such as setting TraceLevel=7, ODP.NET will then begin writing to the specified trace file directory. To disable tracing again, just set the property value back to zero.
Dynamic tracing only works with the OracleConfiguration.TraceLevel property. It can not be enabled with .NET configuration files nor Windows Registry as their values are only read upon application startup in most cases. Dynamic tracing, of course, requires being able to enable and disable tracing while the app runs.
Limiting Trace File Sizes
Dynamic tracing eliminates most reasons individual trace files become large, but not all. Some intermittent ODP.NET problems may occur that make knowing when to turn on tracing difficult. In some instances, developers do not want to modify the code, rebuild, and redeploy to enable tracing.
To address these scenarios, traces can be limited to a maximum file size by using the TraceFileMaxSize setting. By default, its value is 100, which represents a maximum file size of 100 megabytes. When ODP.NET hits the maximum file size limit, it creates a new trace file in the trace file directory and begins writing to that new file.
The TraceFileMaxSize setting is available as a property on OracleConfiguration class (all ODP.NET providers), .NET configuration file (managed and unmanaged ODP.NET), and Windows Registry (unmanaged ODP.NET).
For managed and unmanaged ODP.NET, TraceFileMaxSize can be modified without code changes, meaning no recompile is necessary. Just make the .NET configuration file or Windows Registry change, then (re)start the app. If you are enabling tracing at the same time, be sure to set TraceLevel value too. In the future, ODP.NET Core will also allow enabling these tracing options in a configuration file.
Conclusion
With smaller ODP.NET trace files, it is easier to manage them, analyze them, and find the problem root causes. Hopefully, you will never have to use ODP.NET tracing. If you do, these new features should make it easier for you to configure and use debug tracing.
