Records selected system events.
trace [ -a [ -g ] ] [ -f | -l ] [ -b | -B] [ -c] [ -C [ CPUList | all ]] [ -d ] [ -h ] [ -j Event [ ,Event ] ] [ -k Event [ ,Event ] ] [ -J Event-group [ ,Event-group ]] [ -K Event-group [ ,Event-group ]] [ -m Message ] [ -n ] [ -o Name ] [ -o- ] [ -p ] [ -s ] [ -L Size ] [ -T Size ]
The trace daemon configures a trace session and starts the collection of system events. The data collected by the trace function is recorded in the trace log. A report from the trace log can be generated with the trcrpt command.
When invoked with the -a flag, the trace daemon is run asynchronously (i.e. as a background task). Otherwise, it is run interactively and prompts you for subcommands.
You can use the System Management Interface Tool (SMIT) to run the trace daemon. To use SMIT, enter:
smit trace
There are three modes of trace data collection:
Alternate (the default) | All trace events are captured in the trace log file. |
Circular ( -l) | The trace events wrap within the in-memory buffers and are not captured in the trace log file until the trace data collection is stopped. |
Single ( -f) | The collection of trace events stops when the in-memory trace buffer fills up and the contents of the buffer are captured in the trace log file. |
Buffer Allocation | Trace buffers are allocated from either the kernel heap, or are put into separate segments. By default, buffers are allocated from the kernel heap unless the buffer size requested is too large for buffers to fit in the kernel heap, in which case they are allocated in separate segments. Allocating buffers from separate segments hinders trace performance somewhat. However, buffers in separate segments will not take up paging space, just pinned memory. The type of buffer allocation can be specified with the optional -b or -B flags. |
-a | Runs the trace daemon asynchronously (i.e. as a background task). Once trace has been started this way, you can use the trcon, trcoff, and trcstop commands to respectively start tracing, stop tracing, or exit the trace session. These commands are implemented as links to trace. |
-b | Allocate buffers from the kernel heap. If the requested buffer space
can not be obtained from the kernel heap, the command fails.
Note
The -b flag is only valid with the 32-bit kernel. |
-B | Allocate buffers in separate segments.
Note
The -B flag is only valid with the 32-bit kernel. |
-c | Saves the trace log file, adding .old to its name. |
-C [ CPUList | all ] | Traces using one set of buffers per CPU in the CPUList. The CPUs can be separated by commas, or enclosed in double quotation marks and separated by commas or blanks. To trace all CPUs, specify all. Since this flag uses one set of buffers per CPU, and produces one file per CPU, it can consume large amounts of memory and file space, and should be used with care. The files produced are named trcfile, trcfile-0, trcfile-1, etc., where 0, 1, etc. are the CPU numbers. If -T or -L are specified, the sizes apply to each set of buffers and each file. On a uniprocessor system, you may specify -C all, but -C with a list of CPU numbers is ignored. If -C is used to specify more than one CPU, such as -Call or -C "0 1", the associated buffers are not put into the system dump. |
-d | Disables the automatic start of trace data collection. Delays starting of trace data collection. Normally, the collection of trace data starts automatically when you issue the trace daemon. Use the trcon command to start the collection of trace data. |
-f | Runs trace in a single mode. Causes the collection of trace data to stop as soon as the in-memory buffer is filled up. The trace data is then written to the trace log. Use the trcon command to restart trace data collection and capture another full buffer of data. If you issue the trcoff subcommand before the buffer is full, trace data collection is stopped and the current contents of the buffer are written to the trace log. |
-g | Starts a trace session on a generic trace channel (channels 1 through 7). This flag works only when trace is run asynchronously (-a). The return code of the command is the channel number; the channel number must subsequently be used in the generic trace subroutine calls. To stop the generic trace session, use the command trcstop -<channel_number>. |
-h | Omits the header record from the trace log. Normally, the tracedaemon writes a header record with the date and time (from the date command) at the beginning of the trace log; the system name, version and release, the node identification, and the machine identification (from the uname -a command); and a user-defined message. At the beginning of the trace log, the information from the header record is included in the output of the trcrpt command. |
-j Event[,Event] | |
-k Event[,Event] | Specifies the user-defined events for which you want to collect (-j) or exclude (-k) trace data. The Event list items can be separated by commas, or enclosed
in double quotation marks and separated by commas or blanks.
|
-J Event-group [, Event-group ] | |
-K Event-group [ ,Event-group ] | Specifies the event groups to be included (-J) or excluded (-K). Event groups are described in "Debug and Performance Tracing". The -J and -K flags work like -j and -k, except with event groups instead of individual hook ids. All four flags, -j, -J, -k, and -K may be specified. |
-l | Runs trace in a circular mode. The trace daemon writes the trace data to the trace log when the collection of trace data is stopped. Only the last buffer of trace data is captured. When you stop trace data collection using the trcoff command, restart it using the trconcommand. |
-L Size | Overrides the default trace log file size of 1MB with the value stated.
Specifying a file size of zero sets the trace log file size to the default
size. HERE
Note: In the circular and the alternate modes, the trace log file size must be at least twice the size of the trace buffer. In the single mode, the trace log file must be at least the size of the buffer. See the -T flag for information on controlling the trace buffer size. |
-m Message | Specifies text to be included in the message field of the trace log header record. |
-n | Adds information to the trace log header: lock information, hardware information, and, for each loader entry, the symbol name, address, and type. |
-o Name | Overrides the /var/adm/ras/trcfile default trace log file and writes trace data to a user-defined file. |
-o - | Overrides the default trace log name and writes trace data to standard output. The -c flag is ignored when using this flag. An error is produced if -o - and -C are specified. |
-p | Includes the cpuid of the current processor with each hook. This flag
is only valid for 64-bit kernel traces.
Note: The trcrpt command can report the cpuid whether or not this option is specified. |
-s | Stops tracing when the trace log fills. The trace daemon normally wraps the trace log when it fills up and continues to collect trace data. During asynchronous operation, this flag causes the trace daemon to stop trace data collection. (During interactive operation, the quit subcommand must be used to stop trace.) |
-T Size |
Overrides the default trace buffer size of 128KB with the value stated. You must be root to request more than 1MB of buffer space. The maximum possible size is 268435184 bytes, unless the -f flag is used, in which case it is 536870368 bytes. The smallest possble size is 8192 bytes, unless the -f flag is used, in which case it is 16392 bytes. Sizes between 8192 and 16392 will be accepted when using the -f flag; however, the actual size used will be 16392 bytes. Note: In the circular and the alternate modes, the trace buffer size must be one-half or less the size of the trace log file. In the single mode, the trace log file must be at least the size of the buffer. See the -L flag for information on controlling the trace log file size. Also note that trace buffers use pinned memory, which means they are not pageable. Therefore, the larger the trace buffers, the less physical memory is available to applications. The -f flag actually uses two buffers, which behave as a single buffer (except that a buffer wraparound trace hook will be recorded when the first buffer is filled). |
When run interactively, trace recognizes the following subcommands:
The INTERRUPT signal acts as a toggle to start and stop the collection of trace data. Interruptions are set to SIG_IGN for the traced process.
trace > !anycmd > q
trace -a; anycmd; trcstop
trace -a; sleep 10; trcstop
trace -a -o /tmp/my_trace_log; anycmd; trcstop
trace -a -k "20e,20f"; cp /bin/track /tmp/junk; trcstop
In the example above, the -k option suppresses the collection of events from the lockl and unlockl functions (20e and 20f events).
trace -a -j 234 -J tidhkThis traces the hooks in the event-group "tidhk" plus hook 234.
trace -aC all
The files produced are /var/adm/ras/trcfile, /var/adm/ras/trcfile-0, /var/adm/ras/trcfile-1, etc. up to /var/adm/ras/trcfile-(n-1), where n is the number of CPUs in the system.
/usr/include/sys/trcmacros.h | Defines trchook and utrchook macros. |
/var/adm/ras/trcfile | Contains the default trace log file. |
The trcevgrp command, the trcnm command, the trcrpt command, the trcstop command.
The trchook subroutine, trcgen subroutine, trcstart subroutine, trcon subroutine, trcoff subroutine, trcstop subroutine.
The trcgenk kernel service.
Trace Facility Overview in AIX 5L Version 5.2 General Programming Concepts: Writing and Debugging Programs
Performance Analysis with the Trace Facility in AIX 5L Version 5.2 Performance Management Guide.
Debug and Performance Tracing in AIX 5L Version 5.2 Kernel Extensions and Device Support Programming Concepts.