Flight recorders
A useful way to debug multithreaded applications is to write data to a flight recorder. A flight recorder is a file, output buffer, or some other object where trace information is written so that problems in the application can be tracked.
Entries to and exits from a function are typical information that is traced in a flight recorder. Parameters that are passed to functions, major changes in control flow, and error conditions are often tracked as well.
The Pthread library provides a way for your application to trace problems. You can use tracing to cut optional trace points, turn the recorder on or off, and recompile your application so that all of the tracing code is removed.
You can use different levels of tracing. If your application wants to honor the trace levels, it is the application's responsibility to cue trace points at the appropriate trace levels, or manage the trace level. The Pthread library provides APIs, macros, and trace level variables to assist you.
For Pthread tracing, an error-level tracing displays only those trace points that have error-level severity. An informational-level tracing displays the informational trace points in addition to all error-level trace points. A verbose-level tracing displays trace points of all levels. Each trace point automatically includes the thread ID, a timestamp of millisecond granularity, and the trace data.
The CL commands that enable, display, and work with the tracing are part of the IBM® i operating system.
The tracing buffers for your tracepoints are created as user space objects in the QUSRSYS library. The trace buffers are named QP0Zxxxxxx, in which xxxxxx is the six-digit job number of the job that performed the tracing.
The following APIs relate to tracing and are detailed in the UNIX-Type APIs guide:
- Qp0zUprintf - print formatted trace data
- Qp0zDump - dump formatted hexadecimal data
- Qp0zDumpStack - dump the call stack of the calling thread
- Qp0zDumpTargetStack - dump the call stack of the target thread
- Qp0zLprintf - print formatted job log message
The following CL commands that allow you to manipulate tracing:
- DMPUSRTRC - dump the contents of a specified job's trace
- CHGUSRTRC - change attributes (size, wrapping, clear) of a specified job's trace
- DLTUSRTRC - delete the persistent trace object that is associated with a job's trace