Start the trace facility

Use the following procedures to configure and start a system trace:

Configuring the trace command

The trace command starts the tracing of system events and controls the size of and manages the trace log file, as well as the internal trace buffers that collect trace event data. For information on the syntax of this command, see trace Daemon.

Recording trace event data

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.

Trace hook identifiers

A trace hook identifier is a three- or four-digit hexadecimal number that identifies an event being traced. Prior to AIX 6.1 and on 32-bit applications running on AIX 6.1 and above, only three-digit hook identifiers can be used. When using a tracing macro such as TRCHKL1, the trace hook is specified as:

hhh0000

where hhh is the hook identifier.

On 64-bit applications and kernel routines running on AIX 6.1 and above, three- and four-digit hook identifiers can be used. When using a tracing macro such as TRCHKL1, the trace hook is specified as:

hhhh0000

where hhhh is the hook identifier.

Note: If a four-digit identifier is used and the identifier is less than 0x1000, the least-significant digit must be 0 (of the form 0x0hh0).

A three-digit identifier has an implicit 0 in its least-significant digit such that a 32-bit hook identifier of hhh is equivalent to a 64-bit hook identifier of hhh0.

Most trace hook identifiers are defined in the /usr/include/sys/trchkid.h file. The values 0x0100 through 0x0FF0 are available for use by 64-bit applications. The values 0x010 through 0x0FF are available for use by 32-bit user applications. All other values are reserved for system use. The currently defined trace hook identifers can be listed with the trcrpt -j command.

Using generic trace channels

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 TRCGEN or TRCGENT macros, or the trcgen, trcgent, trcgenk, or trcgenkt subroutines. 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 are written to a separate trace log file, which, by default, is named /var/adm/ras/trcfile.n, where n is the channel number. The subsystem must provide the user interface to activate and deactivate subsystem tracing.

Starting a trace

Use one of the following procedures to start the trace facility.

Start the trace facility by using the trace command.
Start the trace asynchronously. For example:
```
trace -a
mycmd
trcstop
```
When using the trace facility asynchronously, use the trace daemon to trace the selected system events (such as the mycmd command); then, use the trcstop command to stop the trace.

OR
Start the trace interactively. For example:
```
trace
->!mycmd
->quit
```
When using the trace facility interactively, get into the interactive mode as denoted by the -> prompt, and use the trace subcommands (such as !) to trace the selected system events. Use the quit subcommand to stop the trace.
Use smit trace, and choose the Start Trace option.
```
smit trace
```

Stopping a trace

Use one of the following procedures to stop the trace you started earlier.

When using trace asynchronously at the command line, use the trcstop command:
```
trace -a
mycmd
trcstop
```
When using the trace facility asynchronously, use the trace daemon to trace the selected system events (such as the mycmd command); then, use the trcstop command to stop the trace.
When using trace interactively at the command line, use the quit subcommand:
```
trace
->!mycmd
->quit
```
The interactive mode is denoted by the -> prompt. Use the trace subcommands (such as !) to trace the selected system events. Use the quit subcommand to stop the trace.
Use smit trace and choose the Stop Trace option:
```
smit trace
```

Generating a trace report

Use either of the following procedures to generate a report of events that have been traced.

Use the trcrpt command:
```
trcrpt>/tmp/NewFile
```
The previous example formats the trace log file and sends the report to /tmp/newfile. The trcrpt command reads the trace log file, formats the trace entries, and writes a report.
Use the smit trcrpt command:
```
smit trcrpt
```