trace
strace Command
Purpose
Prints STREAMS trace messages.
Syntax
strace [ mid sid level ] ...
Description
The strace command without parameters writes all STREAMS event trace
messages from all drivers and modules to its standard output . These
messages are obtained from the STREAMS log driver. If parameters are
provided, they must be in triplets. Each triplet indicates that tracing
messages are to be received from the given module or driver, subID
(usually indicating minor device), and priority level equal to or
less than the given level. The all token may be used for any member
to indicate no restriction for that attribute.
Parameters
mid Specifies a STREAMS module ID number.
sid Specifies a subID number.
level Specifies a tracing priority level.
Output Format
The format of each trace message output is:
Trace sequence number
Time of message in hh:mm:ss
Time of message, in machine ticks, since system was started
Tracing priority level
Has one of the following values:
E Message is also in the error log
F Indicates a fatal error
N Mail was sent to the system administrator
Module ID number of source
SubID number of source
Formatted text of the trace message
On multiprocessor systems, is composed of two parts:
* the number of the processor where the owner of the message
has sent it,
* the formatted text itself.
Once initiated, the strace command continues to execute until terminated
by the user.
Note: Due to performance considerations, only one strace command is
permitted to open the STREAMS log driver at a time. The log driver
has a list of the triplets specified in the command invocation, and
compares each potential trace message against this list to decide
if it should be formatted and sent up to the strace process. Hence,
long lists of triplets have a greater impact on overall STREAMS performance.
Running the strace command has the most impact on the timing of the
modules and drivers generating the trace messages that are sent to
the strace process. If trace messages are generated faster than the
strace process can handle them, some of the messages will be lost.
This last case can be determined by examining the sequence numbers
on the trace messages output.
Examples
1. To output all trace messages from the module or driver whose module
ID is 41, enter:
strace 41 all all
2. To output those trace messages from driver or module ID 41 with
sub-IDs 0, 1, or 2:
strace 41 0 1 41 1 1 41 2 0
Messages from sub-IDs 0 and 1 must have a tracing level less than
or equal to 1. Those from sub-ID 2 must have a tracing level of 0.
Related Information
List of Streams Commands, STREAMS Overview, Understanding the log
Device Driver in AIX Version 4 Communications Programming Concepts.
=================================================================
=================================================================
trace Daemon
Purpose
Records selected system events.
Syntax
trace [ -a [ -g ] ] [ -f | -l ] [-c] [ -d ] [ -h ] [-j
Event [ ,Event ] ] [-k Event [ ,Event ] ] [ -m Message ]
[ -n ] [ -o Name ] [ -o- ] [ -s ] [ -L Size ] [ -T Size
]
Description
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.
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.
-c Saves the trace log file, adding .old to its name.
-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 -.
-h Omits the header record from the trace log. Normally, the trace
daemon 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.
Note: The following events are used to determine the pid, the cpuid
and the exec path name in the trcrpt report:
001 TRACE ON
002 TRACE OFF
106 DISPATCH
10C DISPATCH IDLE PROCESS
134 EXEC SYSTEM CALL
139 FORK SYSTEM CALL
465 KTHREAD CREATE
If any of these events is missing, the information reported by the
trcrpt command will be incomplete. Consequently: when using the -j
flag, you should include all these events in the Event list; conversely,
when using the -k flag, you should not include these events in the
Event list.
-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 trcon
command.
-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.
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.
-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.
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 kernel memory, in othe
words, they are not pageable. Therefore, the larger the trace buffers,
the less physical memory is available to applications.
Subcommands
When run interactively, trace recognizes the following subcommands:
trcon Starts the collection of trace data.
trcoff Stops the collection of trace data.
q or quit Stops the collection of trace data and exits trace.
! Command Runs the shell command specified by the Command parameter.
? Displays the summary of trace subcommands.
Signals
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.
Examples
1. To use trace interactively, enter trace, (the > prompt is displayed),
then specify the subcommands you want. For example, to trace system
events during the run of the anycmd command, enter:
trace
> !anycmd
> q
2. To avoid delays when the command finishes, start trace asynchronously
(-a), using only one command line. Enter:
trace -a; anycmd; trcstop
3. To trace the system itself for a period of 10 seconds, enter:
trace -a; sleep 10; trcstop
4. To output trace data to a specific trace log file (instead of the
/var/adm/ras/trcfile default trace log file), :
trace -a -o /tmp/my_trace_log; anycmd; trcstop
5. To capture the execution of a cp command, excluding specific events
from the collection process:
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).
Files
/usr/include/sys/trcmacros.h Defines trchook and utrchook macros.
/var/adm/ras/trcfile Contains the default trace log file.
Related Information
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 Version 4 General Programming Concepts:
Writing and Debugging Programs.
Performance Analysis with the Trace Facility in AIX Versions 3.2 and
4 Performance Tuning Guide.