trcrpt Command

Purpose

Formats a report from the trace log.

Syntax

trcrpt [ -c ] [ -C [ processorList | all ]] [ -d List ] [ -D Event-group-list ] [ -e Date ] [ -G ] [ -h ] [ -j ] [ -k List ] [ -K Group-list ] [-m] [ -n Name ] [ -o File ] [ -p List ] [ -r ] [ -s Date ] [ -t File ] [ -T List ] [ -v ] [ -O Options ] [ -x ] [-@ WparList] [-M common | rare | all[:LMT_dir]] [ -l ComponentList | all[:CT_dir] ] [ FileOrDirectory ]

Description

The trcrpt command reads the trace log specified by the -M, -l and File or Directory parameters, formats the trace entries, and writes a report to standard output. The default file from which the system generates a trace report is the /var/adm/ras/trcfile file, but you can specify an alternate log file using the -M, -l and File or Directory parameters. You can specify one or more files or directories. If you specify a file, it must be a valid trace log file, which is any file that is produced by a trace-related command. If you specify a directory, it must contain a component trace master file. If you specify the -m flag, all specified traces will be merged in chronological order.

To include trace entries in a report for the specified workload partition (WPAR), use the -@ flag.

In AIX® 6.1 and later, four-hex-digit hook IDs can be displayed. However, if a four-hex-digit hook ID has a digit of zero, the zero is removed to display only three hex digits. This occurs because four-hex-digit hook IDs in the form hhh0 are equivalent to three-hex-digit hook IDs in the form hhh.

You can use the System Management Interface Tool (SMIT) to run the trcrpt command by entering the SMIT fast path:

smit trcrpt

Flags

Item	Description
-@ WparList	Generates a report containing events that occurred on the workload partitions that you specified. You can specify a list of WPAR configured IDs (CID) or a list of WPAR names with the WparList parameter. The list items can either be separated by commas or enclosed in quotation marks and separated by commas or spaces. Specify 0 or Global in the list to include the Global system in the report.
-c	Checks the template file for syntax errors.
-C [ processorList \| all ]	Generates a report containing events that occur on the processors specified. The processors can be separated by commas, or enclosed in double quotation marks and separated by commas or blanks. To report on all processors, specify `trace -C all`. The -C flag is not necessary unless you want to see only a subset of the processors traced, or have the processor number show up in the report. If -C is not specified, and the trace is a multi-processor trace, trcrpt generates the trace report for all processors, but the processor number is not shown for each hook unless you specify `-O cpuid=on`.
-d List	Limits the report to hook IDs specified with the List variable. The List parameter items can be separated by commas or enclosed in double quotation marks and separated by commas or blanks. In AIX 6.1 and later, four-hex-digit hook IDs can be displayed. However, if a four-hex-digit hook ID has a digit of zero, the zero is removed to display only three hex digits. This occurs because four-hex-digit hook IDs in the form hhh0 are equivalent to three-hex-digit hook IDs in the form hhh.
-D Event-group-list	Limits the report to hook IDs in the Event groups list, plus any hook IDs specified with the -d flag. The list parameter items can be separated by commas or enclosed in double quotation marks and separated by commas or blanks. Event groups are described in Debug and Performance Tracing. The -D flag also reports the trace utility hook id for LMT Restart and LMT Suspend.
-e Date	Ends the report time with entries on, or before, the specified date. The Date variable has the form mmddhhmmssyy (month, day, hour, minute, second, and year). Date and time are recorded in the trace data only when trace data collection is started and stopped. If you stop and restart trace data collection multiple times during a trace session, date and time are recorded each time you start or stop a trace data collection. Use this flag in combination with the -s flag to limit the trace to data collected during a certain time interval. Restriction: The -e and -s flags are only valid for trace log files collected without the trace -C flag.
-G	Lists all event groups. The list of groups, the hook ids in each group, and each group's description is listed to standard output.
-h	Omits the header information from the trace report and writes only formatted trace entries to standard output.
-j	Displays the list of hook IDs. The trcrpt -j command can be used with the trace -j command that includes IDs of trace events or the trace -k command that excludes IDs of trace events.
-k List	Excludes from the report hook IDs specified with the List variable. The List parameter items can be separated by commas or enclosed in double quotation marks and separated by commas or blanks. In AIX 6.1 and above, specifying a two-digit hook ID in the `hh` form results in `hh00`, `hh10`,...,`hhF0`. Specifying a three-digit hook ID in the `hhh` form results in `hhh0`. Specifying a four-digit hook ID in the `hhhh` form results in `hhhh`.
-K Event-group-list	Excludes from the report hook IDs in the event-groups list, plus any hook IDs specified with the -k flag. List parameter items can be separated by commas or enclosed in double quotation marks and separated by commas or blanks. Event groups are described in Debug and Performance Tracing.
-l ComponentList	Generates a report for a multi-component trace with ctctrl -D or trcdead. The components can be separated by commas, or enclosed in double quotation marks and separated by commas or blanks. The -l flag is not necessary unless you want to see only a subset of the components traced. If -l is not specified, the command assumes the trace is a multi-component trace if a directory is given as input on the command line. Multi-component trace log files not in the default directory must either have their directory specified on the command line or with the CT_dir parameter in conjunction with the -l flag. The -l all option can be used to select all available components. Multiple -l flags can be used to specify components in different directories.
-m	Merges all specified trace files based on time stamps. Files merged from another partition, system or from two or more separate boots of the same system will produce unpredictable results. Without the -m flag, reports for each log file are appended to the specified output file.
-M common \| rare \| all[:LMT_dir]	Generates a report from the LMT log files obtained via the mtrcsave or trcdead command. Use the common keyword if you only want events from the common LMT buffers to be reported; use the rare keyword if you only want events from the rare LMT buffers to be reported; use the all keyword if you want common and rare events to be reported. This flag searches only the default LMT log directory unless the LMT_dir parameter is specified. With this parameter, the trcrpt command will search for the LMT files in the specified directory rather than the default LMT log directory. To merge common and rare buffers you must use the all keyword and the -m flag. The -M flag can only appear once.
-n Name	Specifies the kernel name list file to be used to interpret address for output. Usually, this flag is used when moving a trace log file to another system.
-o File	Writes the report to a file instead of to standard output.
-O Options	Specifies options that change the content and presentation of the trcrpt command. Arguments to the options must be separated by commas or enclosed in double quotation marks and separated by commas or spaces. Valid options are: 2line=[on\|off] Uses two lines per trace event in the report instead of one. The default value is off. component=[on\|off] Displays the full component name in the trace report. The default value is off. cpuid=[on\|off] Displays the physical processor number in the trace report. The default value is off. cid=[on\|off] Displays the workload partition configured ID (CID) in the trace report. The default value is off. endtime=Seconds Displays the trace report data for events recorded before the seconds specified. Seconds can be given in either an integral or rational representation. If this option is used with the starttime option, a specific range can be displayed. exec=[on\|off] Displays the exec path names in the trace report. The default value is off.
	filename=[on\|off] Displays the file name from which an event was retrieved. The file name will be truncated from the left if it exceeds 40 characters. The default value is off. hist=[on\|off] Logs the number of instances that each hook ID is encountered. This data can be used for generating histograms. The default value is off. This option cannot be run with any other option. ids=[on\|off] Displays the trace hook identification numbers in the first column of the trace report. The default value is on. pagesize=Number Controls the number of lines per page in the trace report and is an integer within the range of 0 through 500. The column headings are included on each page. No page breaks are present when the default value of 0 is set. pid=[on\|off] Displays the process IDs in the trace report. The default value is off. reportedprocessors=[on \| off ] Displays the number of processors remaining. This option is only meaningful for a multi-processor trace, `trace -C`. For example, if you are reading a report from a system with 4 processors, and the reported processor's value goes from 4 to 3, then you know that there are no more hooks to be reported for that processor. PURR=[ on \| off ] Tells trcrpt to show the PURR along with any timestamps. The PURR is displayed following any timestamps. If the PURR is not valid for the processor traced, the elapsed time is shown instead of the PURR. If the PURR is valid, or the cpuid is unknown, but wasn't traced for a hook, the PURR field contains asterisks (*).
	removedups=[on \| off] Enables duplicate event detection. A count in the DUPS column displays the number of events that each event in the report represents. If this option is set to off, duplicate event detection will be disabled. The default value is on. This option is only valid when merging log files via the -m flag. Duplicate entries can only be detected when the processor ID is known from the trace entry itself, not when it must be inferred. The processor ID can be obtained from the entry in the following cases: A lightweight memory trace A multi-processor system trace, where the trace -C command option was used A 64-bit system trace initiated with the -p option A 64-bit component trace. wparname= [on \| off] Displays the workload partition names in the trace report. The default value is off.
	starttime=Seconds Displays trace report data for events recorded after the seconds specified. The specified seconds are from the beginning of the trace file. Seconds can be given in either an integral or rational representation. If this option is used with the endtime option, a specific range of seconds can be displayed. svc=[on\|off] Displays the value of the system call in the trace report. The default value is off. tid=[on\|off] Displays the thread ID in the trace report. The default value is off. timestamp=[0\|1\|2\|3\|4] Controls the reporting of the time stamp associated with an event in the trace report. The possible values are: 0 Time elapsed since the trace was started and delta time from the previous event. The elapsed time is in seconds and the delta time is in milliseconds. Both values are reported to the nearest nanosecond. This is the default. 1 Short elapsed time. Reports only the elapsed time (in seconds) from the start of the trace. Elapsed time is reported to the nearest microsecond. 2 Microsecond delta time. This is like 0, except the delta time is in microseconds, reported to the nearest microsecond. 3 No time stamp. 4 Raw timestamp from the trace event.
-p List	Reports the process IDs for each event specified by the List variable. The List variable may be a list of process IDs or a list of process names. List items that start with a numeric character are assumed to be process IDs. The list items can be separated by commas or enclosed in double quotation marks and separated by commas or blanks.
-r	Outputs unformatted (raw) trace entries and writes the contents of the trace log to standard output one entry at a time. Use the -h flag with the -r flag to exclude the heading. To get a raw report for processors in a multi-processors trace, use both the -r and -C flags.
-s Date	Starts the report time with entries on, or before, the specified date. The Date variable has the form mmddhhmmssyy (month, day, hour, minute, second, and year). Date and time are recorded in the trace data only when trace data collection is started and stopped. If you stop and restart trace data collection multiple times during a trace session, date and time are recorded each time you start or stop a trace data collection. Use this flag in combination with the -e flag to limit the trace to data collected during a certain time interval. Restriction: The -e and -s flags are only valid for trace log files collected without the trace -C flag.
-t File	Uses the file specified in the File variable as the template file. The default is the /etc/trcfmt file.
-T List	Limits the report to the kernel thread IDs specified by the List parameter. The list items are kernel thread IDs separated by commas or enclosed in double quotation marks and separated by commas or spaces. Starting the list with a kernel thread ID limits the report to all kernel thread IDs in the list. Starting the list with a ! (exclamation point) followed by a kernel thread ID limits the report to all kernel thread IDs not in the list.
-v	Prints file names as the files are opened. Changes to verbose setting.
-x	Displays the exec path name and value of the system call.

Security

Attention RBAC users and Trusted AIX users: This command can perform privileged operations. Only privileged users can run privileged operations. For more information about authorizations and privileges, see Privileged Command Database in Security. For a list of privileges and the authorizations associated with this command, see the lssecattr command or the getcmdattr subcommand.

Examples

To format the trace log file and print the result, enter:
```
trcrpt | qprt
```
To send a trace report to the /tmp/newfile file, enter:
```
trcrpt -o /tmp/newfile
```
To display process IDs and exec path names in the trace report, enter:
```
trcrpt -O pid=on,exec=on
```
To create trace ID histogram data, enter:
```
trcrpt -O hist=on
```
To produce a list of all event groups, enter:
```
trcrpt -G
```
The format of this report is shown under the trcevgrp command.
To generate back-to-back LMT reports from the common and rare buffers, enter:
```
trcrpt -M all
```
If, in the above example, the LMT files reside at /tmp/mydir, and we want the LMT traces to be merged, enter:
```
trcrpt -m -M all:/tmp/mydir
```
To merge the system trace with the scdisk.hdisk0 component trace, enter:
```
trcrpt -m -l scdisk.hdisk0 /var/adm/ras/trcfile
```
To merge LMT with the system trace while not eliminating duplicate events, enter:
```
trcrpt -O removedups=off -m -M all /var/adm/ras/trcfile
```
To merge all component traces in /tmp/mydir with the LMT traces in the default LMT directory while showing the source file for each trace event, enter:
```
trcrpt -O filename=on -m -M all /tmp/mydir
```
Tip: This is equivalent to the following command:
```
trcrpt -O filename=on -m -M all -l all:/tmp/mydir
```
Tip: If the traces are from a 64-bit kernel, duplicate entries will be removed. However, on the 32-bit kernel, duplicate entries will not be removed since we do not know the processor IDs of the entries in the components traces.

Files

Item	Description
/usr/bin/trcrpt	Contains the trcrpt command.
/var/adm/ras/trcfile	Contains the default log file.
/var/adm/ras/mtrcdir	Location of the default LMT dump directory
/var/adm/ras/trc_ct	Location of the default CT dump directory.
/etc/trcfmt	Contains the trace format file.