Capturing binary trace

The binary trace runs by default at a very low level, so that it can capture any basic first-failure data if a problem arises. The binary tracing system combines trace data into one contiguous store, and is used for tracing Java and VoiceXML components as well as some custom servers. As described below, two separate configuration files are used to set the default tracing level and the method by which the system stores the trace data. All the trace data is stored in binary format into a memory buffer, and also to disk in a managed list of files, which are limited to a configurable maximum amount of disk space. Once this space is used, the oldest file is discarded and reused.

Configuring the trace

You can either use dtjit to configure the trace (refer to the help for dtjit for more information) or follow the instructions below to configure the trace manually.

To set the tracing level for the Java and VoiceXML environment, edit the file $DTJ_HOME/dtj.ini to include the line

trace.option=<trace_level>

In the absence of this value being set, a default trace level of 2 is used.

After you have updated the file, you must restart the Java and VoiceXML environment environment for the changes to take effect.

To set the tracing level for any other code (such as custom servers), edit the file $DTJ_HOME/native/aix/trcserv.ini to include the line

trace.option=<trace_level>

You do not have to restart any programs after changing trcserv.ini, although you do need to run the command trcserv -ry. This resets the trace server so that it picks up any new settings.

In both the above cases, <trace level> is an integer that can be set to the following values:

0: All tracing off
1: All tracing off
2: Core trace points and errors only. It is recommended that trace level 2 is used for the first pass of tracing.
3: As for 2, plus important trace points and function entry/exit only (minor trace points and trace points with data excluded)
4: As for 2, plus important trace points (loop and CPU intensive trace points excluded)
5: As for 2, plus important trace points, no exclusions
6: As for 5, plus warnings
7: As for 5, plus function entry/exit
8: All trace on (loop and CPU intensive trace points excluded)
9: All trace on

There are other useful parameters that can be set (in the trcserv.ini file only) to alter the way in which the tracing works.

To change the way in which trace data is stored include the line:
```
 trace.mode=<mode_number>
```
where mode_number can take the following values:

1

All trace data is written to memory buffer only. This is the default value and is recommended for the first pass of tracing.

3

Trace data is written to memory, but continuously written out to disk in chunks.

5

All trace data is written to the AIX system trace instead. For this mode, the raw binary data is written to the AIX trace buffer instead of the binary trace system's own files. Because of this, you need to run an AIX system trace to capture the trace data, and then use the command print_trace | dtjtrcfmt > <filename> to format the trace correctly.
To alter the amount of disk space to be used for storing binary trace files include the line:
```
trace.max.disk=<number_of_kilobytes>
```
When this limit is reached, the oldest file is discarded and reused. Each file is typically 5 MB in size and has a naming convention of wvrtrace.<num>.trc, where <num> is an integer between one and the number of files that make up the maximum disk limit (the default is 100 MB). Trace files are stored in the directory $DTJ_HOME/dtj_logs.

The trace server memory buffer can be flushed to disk on demand by using trcserv -f command. This causes any trace data that was not previously written in the current memory buffer to be written to disk.

Collecting the trace

The process for collecting binary trace is as follows:

To start the trace: Either edit the appropriate configuration files (as described above) to have trace run automatically, or use the following command:
```
dtjtrcmod <trace_level>
```
This command sets the trace level dynamically, without requiring a restart of any program that uses this tracing system.
The trace mode should also be set to 3 to enable continuous data output to be collected. Depending on how busy the system is or the level of trace that is set, there may be a large amount of trace data created, and as a result the maximum disk space parameter may need to be increased to allow enough data to be captured. Also, you should monitor the extra CPU load that the system will experience if it is running at the highest trace level (9).
To stop the trace: Enter the command dtjtrcmod 0. This turns off all binary tracing.
Enter the command trcserv -f to flush any remaining trace data from memory to disk
To format the trace data: In the trace output directory ($DTJ_HOME/dtj_logs), enter the command
```
dtjtrcfmt wvrtrace.<n>.trc > <output filename>
```
or
```
dtjtrcfmt -o <output_filename> wvrtrace.<n>.trc
```
The output file contains the trace output in UTF-8 readable form.
Sending data to Blueworx Support: The dtbeProblem tool collects all the binary trace files. However, if you have been specifically asked to run a binary trace, then collect all the binary trace files that have been created, and send them unformatted together with the dtbeProblem output data.