The trace facility helps you isolate system problems by monitoring selected system events. Events that can be monitored include: entry and exit to selected subroutines, kernel routines, kernel extension routines, and interrupt handlers. When the trace facility is active, information about these events is recorded in a system trace log file. The trace facility includes commands for activating and controlling traces and generating trace reports. Applications and kernel extensions can use several subroutines to record additional events.
The diagram illustrates the processes of the trace facility:
For more information on the trace facility, refer to the following:
The following commands are part of the trace facility:
| trace | Starts the tracing of system events. With this command, you can control the size and manage the trace log file as well as the internal trace buffers that collect trace event data. |
| trcdead | Extracts trace information from a system dump. If the system halts while the trace facilities are active, the contents of the internal trace buffers are captured. This command extracts the trace event data from the dump and writes it to the trace log file. |
| trcnm | Generates a kernel name list used by the trcrpt command. A kernel name list is composed of a symbol table and a loader symbol table of an object file. The trcrpt command ues the kernel name list file to inerpret addresses when formatting a report from a trace log file. |
| trcrpt | Formats reports of trace event data contained in the trace log file. You can specify the events to be included (or omitted) in the report, as well as determine the presentation of the output with this command. The trcrpt command uses the trace formatting templates stored in the /etc/trcfmt file to determine how to interpret the data recorded for each event. |
| trcstop | Stops the tracing of system events. |
| trcupdate | Updates the trace formatting templates stored in the /etc/trcfmt file. When you add applications or kernel extensions that record trace events, templates for these events must be added to the /etc/trcfmt file. The trcrpt command will use the trace formatting templates to determine how to interpret the data recorded for each event. Software products that record events usually run the trcupdate command as part of the installation process. |
The following calls and subroutines are part of the trace facility:
| trcgen, trcgent | Records trace events of more than five words of data. The trcgen subroutine may be used to record an event as part of the system event trace (trace channel 0) or to record an event on a generic trace channel (channels 1 through 7). You specify the channel number in a subroutine parameter when you record the trace event. The trcgent subroutine appends a time stamp to the event data. |
| trchook, utrchook | Records trace events of up to five words of data. These subroutines may be used to record an event as part of the system event trace (trace channel 0). The utrchook subroutine uses a special FAST-SVC path to improve performance and should be used by programs at the user (application) level. |
| trcgenk, trcgenkt | Records trace events of more than five words of data. The trcgenk subroutine may be used to record an event as part of the system event trace (trace channel 0) or to record an event on a generic trace channel (channels 1 through 7). You specify the channel number in a subroutine parameter when you record the trace event. The trcgenkt subroutine appends a time stamp to the event data. |
| trcoff | Suspends the collection of trace data on either the system event trace channel (channel 0) or a generic trace channel (1 through 7). The trace channel remains active and trace data collection can be resumed by using the trcon subroutine. |
| trcon | Starts the collection of trace data on a trace channel. The channel may be either the system event trace channel (0) or a generic channel (1 through 7). The trace channel, however, must have been previously activated by using the trace command or the trcstart subroutine. You can suspend trace data collection by using the trcoff subroutine. |
| trcstart | Requests a generic trace channel. This subroutine activates a generic trace channel and returns the channel number to the calling application to use in recording trace events using the trcgen, trcgent, trcgenk, and trcgenkt subroutines. |
| trcstop | Frees and deactivates a generic trace channel. |
| /etc/trcfmt | Contains the trace formatting templates used by the trcrpt command to determine how to interpret the data recorded for each event. |
| /var/adm/ras/trcfile | Contains the default trace log file. The trace command allows you to specify a different trace log file. |
| /usr/include/sys/trchkid.h | Contains trace hook identifier definitions. |
| /usr/include/sys/trcmacros.h | Contains commonly used macros for recording trace events. |
The data recorded for each traced event consist of a word containing the trace hook identifier and the hook type followed by a variable number of words of trace data optionally followed by a time stamp. The word containing the trace hook identifier and the hook type is called the hook word. The remaining two bytes of the hook word are called hook data and are available for recording event data.
A trace hook identifier is a three-digit hexadecimal number that identifies an event being traced. You specify the trace hook identifier in the first twelve bits of the hook word. Trace hook identifiers are defined in the /usr/include/sys/trchkid.h file. The values 0x010 through 0x0FF are available for use by user applications. All other values are reserved for system use. The currently defined trace hook identifiers can be listed using the trcrpt -j command.
The hook type identifies the composition of the event data and is user-specified. The twelfth through the sixteenth bits of the hook word constitute the hook type. For more information on hook types, refer to the trcgen, trcgenk, and trchook subroutines.
The trace facility supports up to eight active trace sessions at a time. Each trace session uses a channel of the multiplexed trace special file, /dev/systrace. Channel 0 is used by the trace facility to record system events. The tracing of system events is started and stopped by the trace and trcstop commands. Channels 1 through 7 are referred to as generic trace channels and may be used by subsystems for other types of tracing such as data link tracing.
To implement tracing using the generic trace channels of the trace facility, a subsystem calls the trcstart subroutine to activate a trace channel and to determine the channel number. The subsystem modules can then record trace events using the trcgen, trcgent, trcgenk, or trcgenkt subroutine. The channel number returned by the trcstart subroutine is one of the parameters that must be passed to these subroutines. The subsystem can suspend and resume trace data collection using the trcoff and trcon subroutines and can deactivate a trace channel using the trcstop subroutine. The trace events for each channel must be written to a separate trace log file, which must be specified in the call to the trcstart subroutine. The subsystem must provide the user interface to activating and deactivating subsystem tracing.
The trace hook IDs, which are stored in the /usr/include/sys/trchkid.h file, and the trace formatting templates, which are stored in the /etc/trcfmt file, are shared by all the trace channels.
The trace daemon in AIX Version 4.3 Commands Reference.
The trcdead command, trcnm command, trcrpt command, trcstop command, trcupdate command in AIX Version 4.3 Commands Reference.
The trchook subroutine, trcgen subroutine, trcoff subroutine, trcon subroutine, trcstart subroutine, trcstop subroutine in AIX Version 4.3 Technical Reference: Base Operating System and Extensions Volume 2.
