General Programming Concepts:
Writing and Debugging Programs

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. The syntax of this command is:

trace [-fl] [-ad] [-s] [-h] [-jk events] [,events] [-m message] [-o outfile][-g] [-T buf_sz] [-L log_sz]

The various options of the trace command are:

-f or -l	Controls the capture of trace data in system memory. If you specify neither the -f nor -l option, the trace facility creates two buffer areas in system memory to capture the trace data. The trace log files and the internal trace buffers that collect trace event data can be managed, including their size, by this command. The -f or -l flag provides the ability to prevent data from being written to the file during data collection. The options are to collect data only until the memory buffer becomes full (-f for first), or to use the memory buffer as a circular buffer that captures only the last set of events that occurred before trace was terminated (-l). The -f and -l options are mutually exclusive. With either the -f or -l option, data is not transferred from the memory collection buffers to file until trace is terminated.
-a	Runs the trace collection asynchronously (as a background task), returning a normal command line prompt. Without this option, the trace command runs in a subcommand mode and returns a > prompt. You can issue subcommands and regular shell commands from the trace subcommand mode by preceding the shell commands with an ! (exclamation point).
-d	Delays data collection. The trace facility is only configured. Data collection is delayed until one of the collection trigger events occurs. Various methods for triggering data collection on and off are provided. These include the following: trace subcommands trace commands trace subroutines.
-j events or -k events	Specifies a set of events to include (-j) or exclude (-k) from the collection process. Specifies a list of events to include or exclude by a series of three-digit hexadecimal event IDs separated by a space.
-s	Terminate trace data collection if the trace log file reaches its maximum specified size. The default without this option is to wrap and overwrite the data in the log file on a FIFO basis.
-h	Does not write a date/sysname/message header to the trace log file.
-m message	Specifies a text string (message) to be included in the trace log header record. The message is included in reports generated by the trcrpt command.
-o outfile	Specifies a file to use as the log file. If you do not use the -o option, the default log file is /var/adm/ras/trcfile. To direct the trace data to standard output, code the -o option as -o -. Use this technique only to pipe the data stream to another process since the trace data contains raw binary events that are not displayable.
-g	Duplicates the trace design for multiple channels. Channel 0 is the default channel and is always used for recording system events. The other channels are generic channels, and their use is not predefined. There are various uses of generic channels in the system. The generic channels are also available to user applications. Each created channel is a separate events data stream. Events recorded to channel 0 are mixed with the predefined system events data stream. The other channels have no predefined use and are assigned generically. A program typically requests that a generic channel be opened by using the trcstart subroutine. A channel number is returned, similar to the way a file descriptor is returned when a file is opened (the channel ID). The program can record events to this channel and, thus, have a private data stream. Less frequently, the trace command allows a generic channel to be specifically configured by defining the channel number with this option.
-T size and -L size	Specifies the size of the collection memory buffers and the maximum size of the log file in bytes. Note: Because the trace facility pins the data collection buffers, making this amount of memory unavailable to the rest of the system, the trace facility can impact performance in a memory-constrained environment. If the application being monitored is not memory-constrained, or if the percentage of memory consumed by the trace routine is small compared to what is available in the system, the impact of trace "stolen" memory should be small. If you do not specify a value, trace uses a default size.

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-digit hexadecimal number that identifies an event being traced. You specify the trace hook identifier in the first 12 bits of the hook word. The values 0x010 through 0x0FF are available for use by user applications. All other values are reserved for system use. The trace hook identifiers for the installed software can be listed using the trcrpt -j command.

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.

Hook Types

The hook type identifies the composition of the event data and is user-specified. Bits 12 through 16 of the hook word constitute the hook type. For more information on hook types, refer to the trcgen, trcgenk, and trchook subroutines.

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 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 for activating and deactivating subsystem tracing.

Starting a Trace

Use the 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
```

General Programming Concepts: Writing and Debugging Programs