Tracing user application

This topic describes tracing user applications.

The tracing operation depends on three logically different processes: the traced process, the controller process, and the analyzer process. A process can simultaneously be the traced process, the controller process and the analyzer process. When the traced process is running and a trace point is reached, a trace event is recorded into the trace streams created for that process if the trace event type identifier associated with this process is not filtered out.

The controller process controls the recording of trace events into trace streams. The controller process performs the following operations for an active trace stream:

Initializes the attributes of a trace stream.
Creates the trace stream for a specified traced process using the initialized attributes.
Starts and stops tracing for a trace stream.
Filters the type of trace events to be recorded.
Ends a trace stream.

The analyzer process retrieves the traced events either at runtime, when the trace stream is active and is recording trace events; or after opening a trace log that is previously recorded and closed.

The posix_trace_create, posix_trace_create_withlog, and the posix_trace_open subroutines create a trace stream identifier. The posix_trace_create and posix_trace_create_withlog subroutines are used only by a controller process. The posix_trace_open subroutine is used only by an analyzer process.

A traced process contains a mapping of the trace event names to the trace event type identifiers that are defined for the process. An active trace event records the system predefined trace event types, such as the POSIX_TRACE_START, and the trace event types that are defined for the traced processes but not filtered out by the trace stream. To define the mapping, call the posix_trace_eventid_open subroutine from the instrumented application, or call the posix_trace_trid_eventid_open subroutine from the controller process. For a prerecorded trace stream, the list of trace event types is obtained from the prerecorded trace log.

The tracing subroutines can be used in debugging the possibly pre-instrumented code and postmortem fault analysis. Debugging pre-instrumented code might require pre-filtering capabilities to avoid overwhelming the trace stream and permits focusing on expected information. Postmortem fault analysis requires comprehensive trace capabilities to be able to record all types of information.

The events to be traced belong to the following two classes:

User trace events that the instrumented application generated.
System trace events that the operating system generated in correspondence with the trace control operation.

In a file associated with an active trace stream, the st_ctime and st_mtime fields are marked for update every time any of the tracing operations modifies that file.

In a file associated with a trace stream, the st_atime field is marked for update every time any of the tracing operations causes data to be read from that file.

If an application performs any operation on a file descriptor associated with an active or prerecorded trace stream, the results are not defined until calling the posix_trace_shutdown or posix_trace_close subroutines for that trace stream.