[ Bottom of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]

Commands Reference, Volume 5

tprof Command

Purpose

Reports CPU usage.

Syntax

tprof [ -c ] [ -C { all | CPUList } ] [ -d ] -D ] [ -e ] [ -F ] [ -j ] [ -k ] [ -l ] [ -m ObjectsList ] [ -M SourcePathList ] [ -p ProcessList ] [ -P { all | PIDsList } ] [ -s ] [ -S SearchPathList ] [ -t ] [ -T BufferSize ] [ -u ] [ -v ] [ -V VerboseFileName ] [ -z ] { { -r RootString } | { [ -A { all | CPUList }] [ -r RootString ] -x Program } }

Notes:
  1. All the list type inputs are separated by a comma except for pathlist, which is separated by a colon.
  2. Per-CPU profiling mode is automatically disabled while running in realtime mode.
  3. Microprofiling is automatically disabled if per-CPU profiling is turned on.
  4. If the -x flag is specified without the -A flag, tprof runs in realtime mode.
  5. If the -x flag is specified with the -A flag, tprof runs in automated offline mode.
  6. If the -x flag is omitted tprof runs in post-processing mode or manual offline mode, depending on the presence of cooked files and the -F flag.

Description

The tprof command reports CPU usage for individual programs and the system as a whole. This command is a useful tool for anyone with a JAVA, C, C++, or FORTRAN program that might be CPU-bound and who wants to know which sections of the program are most heavily using the CPU.

The tprof command can charge CPU time to object files, processes, threads, subroutines (user mode, kernel mode and shared library) and even to source lines of programs or individual instructions. Charging CPU time to subroutines is called profiling and charging CPU time to source program lines is called micro-profiling.

For subroutine-level profiling, the tprof command can be run without modifying executable programs, that is no recompilation with special compiler flags is necessary. This is still true if the executables have been stripped, unless the back tables have also been removed. However, recompilation is required to get a micro-profile, unless a listing file is already available. To perform micro-profiling on a program, either the program should be compiled with -g and the source files should be accessible to tprof or the program should be compiled with -qlist and either both the object listing files and the source files or just the object listing files should be accessible to tprof. To take full advantage of tprof micro-profiling capabilities, it is best to provide both the .lst and the source file.

tprof can run in the following four modes:

  1. Realtime or online
  2. Manual offline
  3. Automated offline
  4. Post-processing

If the -x flag is specified but the -A flag is not specified, tprof runs in realtime mode. In realtime mode tprof starts the AIX trace utility in the background, and processes the trace data as it gets generated. When the program being profiled ends, tprof collects symbolic name information, and generates the reports.

Note
This mode does not allow per-CPU profiling.

If the -A flag is specified with the -x flag, tprof runs in automated offline mode. In this mode tprof starts the AIX trace utility and logs the trace data into a file. Once the trace data collection is done, it collect symbolic name information, and tprof opens the trace log file and processes the data to generate reports. In this mode tprof generates the following files in addition to tprof report files:

  1. RootString.syms
  2. RootString.trc[-cpuid]
Note
All of the input and report files used by tprof are named RootString.suffix, where RootString is either specified with -r or is the program name specified with -x.

The tprof command can re-process these files any time to generate profiling reports. This is called manual offline mode. The RootString.syms file contains symbolic name information similar to the output of the gensyms command. The RootString.trc[-cpuid] file(s) are trace log file(s). The -cpuid is added to the names when per-CPU tracing is on. In that case, each file contains trace data from one CPU only.

Note
If -c is used along with -A then those two files are not generated. Instead, the following two files are created:
  1. RootString.csyms
  2. RootString.ctrc[ -cpuid ]

Those files are cooked, that is they are a pre-processed version of the normal trace and name files. tprof post-processes cooked file much faster.

If neither -A flag nor -x are specified, tprof runs either in manual offline or in post-processing mode. For tprof to run in post-processing mode the following files must be available:

  1. RootString.csyms
  2. RootString.ctrc[ -cpuid ]

Those are generated when tprof runs (in any mode except post-processing mode) with the -c flag. For tprof to run in manual offline mode the following files must be available:

  1. RootString.syms
  2. RootString.trc [-cpuid]

These files are generated by a user manually using the gensyms command and AIX trace facility or by running tprof in automated offline mode without the -c flag.

Note
tprof always first looks for RootString.csyms and RootString.ctrc[-cpuid]. Only if these files are not available, does it look for RootString.syms and RootString.trc[-cpuid]. To prevent tprof from looking for rootstring.csyms and RootString.ctrc[-cpuid], that is, force the manual offline mode, use the -F flag.

tprof generates a report file named RootString.prof which holds the process, thread, object file and subroutine level profiling report. The file can contains the following sections and subsections:

  1. Summary report section
    1. CPU usage summary by process name
    2. CPU usage summary by threads (tid)
  2. Global (pertains to the execution of all processes on system) profile section
    1. CPU usage of user mode routines
    2. CPU usage of kernel routines
    3. CPU usage summary for kernel extensions
    4. CPU usage of each kernel extension's subroutines.
    5. CPU usage summary for shared libraries
    6. CPU usage of each shared library's subroutines.
    7. CPU usage of each JAVA class.
    8. CPU usage of each JAVA methods of each JAVA class.
  3. Process and thread level profile sections (one section for each process or thread)
    1. CPU usage of user mode routines for this process/thread
    2. CPU usage of kernel routines for this process/thread.
    3. CPU usage summary for kernel extensions for this process/thread.
    4. CPU usage of each kernel extension's subroutines for this process/thread.
    5. CPU usage summary for shared libraries for this process/thread.
    6. CPU usage of each shared library's subroutines for this process/thread.
    7. CPU usage of each JAVA class for this process/thread.
    8. CPU usage of JAVA methods of each JAVA class for this process/thread.

The summary report section is always present in the RootString.prof report file. Based on the profiling flags the various subsections of the global profile section can be turned on and off:

The process and thread level profile sections are created for processes and threads selected with the -p, -P and -t flags. The subsections present within each of the per-process of per-thread sections are identical to the subsections present in the global section, they are selected using the profiling flags (-u,-s,-k,-e,-j).

Optionally (when called with the -C flag) tprof also generates per-CPU profiling reports (one profiling report per CPU). The generated tprof reports have the same structure and are named using the convention: RootString.prof[-cpuid].

If -m is specified, tprof generates micro-profiling reports. The reports use the following naming convention: RootString.source.mprof, where source is the base name of a source file. If more than one source file has the same base name, then a number to uniquely identify them is appended to the report file name, for example, RootString.Filename.c.mprof-1. The micro-profiling report has the following information:

  1. The full pathname of the annotated source file.
  2. A hot line profile section which has all the line numbers from that source file hit by profiling samples, sorted by cpu usage. For each source line, one line reports the percentage of time spent on behalf of all processes, followed by additional lines with the breakdown by individual process.
  3. A source line profile section for each of the functions in that source file, which have CPU usage. This section contains the source line number, cpu usage and source code. If a .lst file for that source file is accessible to tprof then it will interlace the instruction lines from the .lst file with the source lines from the source file and charge CPU usage appropriately. This will provide breakdown by instruction for each source file.

    If a source file is not present, but a .lst file is present, tprof only shows the CPU usage based on the source lines and the instructions from the .lst file.

    If neither files are present, but the source file was compiled with -g, tprof can retrieve the source line numbers and it generates a similar report, but with the source code column missing.

    Note
    If per-CPU profiling is requested then micro-profiling is automatically disabled. tprof cannot report correct source line information if a .c file is included in another .c file. tprof cannot micro-profile JAVA classes or methods.

Profile Accuracy

The degree to which CPU activity can be resolved is determined by the number of samples captured and the degree to which hot spots dominate. While a program with a few hot spots can be profiled with relatively few samples, less-frequently executed sections of the program are not visible in the profiling reports unless more samples are captured. In cases where user programs run less than a minute, there may be insufficient resolution to have a high degree of confidence in the estimates.

A simple solution is to repeatedly execute the user program or script until you achieve the degree of resolution you need. The longer a program is run, the finer the degree of resolution of the profile. If you doubt the accuracy of a profile, run the tprof command several times and compare the resulting profiles.

Comparison of tprof Versus prof and gprof

The most significant differences between these three commands is that tprof collects data with no impact on the execution time of the programs being profiled, and works on optimized and stripped binaries without any need for recompilation, except to generate micro-profiling reports. Neither gprof nor prof have micro-profiling capabilities or work on optimized or stripped binaries, while they do require special compilation flags, and induce a slowdown in the execution time that can be significant.

The prof and gprof tools are standard, supported profiling tools on many UNIX systems, including this operating system. Both prof and gprof provide subprogram profiling and exact counts of the number of times every subprogram is called. The gprof command also provides a very useful call graph showing the number of times each subprogram was called by a specific parent and the number of times each subprogram called a child. The tprof command provides neither subprogram call counts nor call graph information.

Like the tprof command, both the prof and gprof commands obtain their CPU consumption estimates for each subprogram by sampling the program counter of the user program.

tprof collects CPU usage information for the whole system, while prof and gprof collect only profiling information for a single program and only for the time spent in user mode.tprof also provides summary for all processes active during the execution of the profiled user program and fully support libraries and kernel mode profiling.

tprof support the profiling of JAVA applications, which prof and gprof do not.

Flags

-A {all | CPUList } Turns on automatic offline mode. No argument turns off per-CPU tracing. all enables tracing of all CPUs. CPUList is a comma separated list of CPU-ids to be traced.
-c Turns on generation of cooked files.
-C all | CPUList Turns on the per-CPU profiling. Specify all to generate profile reports for all CPUs. CPU numbers should be separated with a comma if you give a CPUlist (for example, 0,1,2).
Note
per-CPU profiling is possible only if per-CPU trace is either on (in automated offline mode), or has been used (in manual offline mode). It is not possible at all in online mode.
-d Turns on deferred tracing mode, that is defers data collection until trcon is called.
-D Turns on detailed profiling which displays CPU usage by instruction offset under each subroutine.
-e Turns on kernel extension profiling.
-F Overwrites cooked files if they exists. If used without the -x flag, this forces the manual offline mode.
-j Turns on JAVA classes and methods profiling.
-k Enables kernel profiling.
-l Enables long names reporting. By default tprof truncates the subroutine, program and source file names if they do not fit into the available space in the profiling report. This flag disables truncation.
-m ObjectsList Enables micro-profiling of objects specified by the comma separated list, Objectlist. Executables, shared libraries, and kernel extensions can be micro-profiled. Specify the archive name for libraries and kernel extensions.
Notes:
  1. To enable micro-profiling of programs, user mode profiling (-u) must be turned on.
  2. To enable micro-profiling of shared libraries, shared library profiling (-s) must be turned on.
  3. To enable micro-profiling of kernel extensions, kernel extension profiling (-e) must be turned on.
-M PathList Specifies the source path list. The PathList is a colon separated list of paths that are searched for source files and .lst files that are required for micro-profiling.
Note
By default the source path list is the object search path list.
-p ProcessList Enables process level profiling of the process names specified in the ProcessList. ProcessList is a comma separated list of process names
Note
Process level profiling is enabled only if at least one of the profiling modes (-u,-s,-k,-e, or -j) is turned on.
-P { all | PIDList } Enables process level profiling of all processes encountered or for processes specified with PIDList. The PIDList is a comma separated list of process-IDs.
Note
Process level profiling is enabled only if at least one of the profiling modes (-u,-s,-k,-e, or -j) is turned on.
-r RootString Specifies the RootString. tprof input and report files all have names in the form of RootString.suffix.
Note
If -r is not specified, RootString defaults to the program name specified with the -x flag.
-s Enables shared library profiling.
-S PathList Specifies the object search PathList. The PathList is a colon separated list of paths that are searched for executables, shared libraries and kernel extensions.
Note
The default object search PathList is the environment path list ($PATH).
-t Enables thread level profiling.
Note
If -p or -P are not specified with the -t flag, -t is equivalent to -P all -t. Otherwise, it enables thread level reporting for the selected processes. Thread level profiling is enabled only if at least one of the profiling modes (-u,-s,-k,-e, -j) is enabled.
.
-T BufferSize Specifies the trace BufferSize.
Note
This flag has meaning only in real time or automated offline modes.
-u Enables user mode profiling.
-v Enables verbose mode.
-V File Stores the verbose output in the specified File.
-x Program Specifies the program to be executed by tprof. Data collection stops when Program completes or trace is manually stopped with either trcoff or trcstop
Note
The -x flag must be the last flag in the list of flags specified in tprof.
-z Enables compatibility mode with the previous version of tprof. By default CPU usage is only reported in percentages. When -z is used, tprof also reports ticks. This flag also adds the Address and Bytes columns in subroutine reports.

Examples

  1. Basic global program and thread-level summary
    $ tprof -x sleep 10 
    Mon May 20 00:39:26 2002 System: AIX 5.2 Node: dreaming Machine: 000671894C00 
    Starting Command sleep 10 
    stopping trace collection. 
    Generating sleep.prof  

    The resulting sleep.prof file only contains the summary report section.

  2. Global profiling with all options
    $ tprof -skeuj -x sleep 10 
    Mon May 20 00:39:26 2002 
    System: AIX 5.2 Node: drea
    ming Machine: 000671894C00 
    Starting Command sleep 10 
    stopping trace collection.
    Generating sleep.prof 

    The resulting sleep.prof file contains the summary report and global profile sections.

  3. Single process level profiling
    $ tprof -u -p workload -x workload 
    Mon May 20 00:39:26 2002 
    System: AIX 5.2 Node: drea
    ming Machine: 000671894C00 
    Starting Command workload stopping trace collection. 
    Generating workload.prof  

    The resulting workload.prof file contains the summary report and the global user mode profile sections, and one process level profile section for the process 'workload' that contains only a user mode profile subsection.

  4. Multiple process level profiling
    $ tprof -se -p send,receive -x startall 
    Mon May 20 00:39:26 2002 
    System: AIX 5.2 Node: dreaming Machine: 000671894C00 
    Starting Command startall 
    stopping trace collection. 
    Generating startall.prof

    The resulting startall.prof file contains the summary report, the global shared libary mode profile, and the global kernel extension profile sections, and two process level profile sections: one for the process 'send', and one for the process 'receive'. The process level sections each contain two subsections: one with shared libary profiling information and one with kernel extentions profiling information.

  5. Microprofiling
    $ tprof -m ./tcalc -u -x ./tcalc 
    Mon May 20 00:47:09 2002 
    System: AIX 5.2 Node: dreaming Machine: 000671894C00 
    Starting Command ./tcalc 
    stopping trace collection. 
    Generating tcalc.prof 
    Generating tcalc.tcalc.c.mprof

    The resulting tcalc.prof file contains the summary report and the global user mode profile sections. The resulting tcalc.tcalc.c.mprof file contains the micro-profiling report.

  6. Automated offline mode
    tprof -c -A all -x sleep 10 
    Starting Command sleep 10 
    stopping trace collection. 
    Mon May 20 00:52:52 2002 
    System: AIX 5.2 Node: dreaming Machine: 000671894C00 
    Generating sleep.ctrc 
    Generating sleep.csyms 
    Generating sleep.prof  

    The resulting sleep.prof file only has a summary report section, while the two cooked files are ready to be re-postprocessed.

Messages

If your system displays the following message:

/dev/systrace: device busy or trcon: TRCON:no such device

This means the trace facility is already in use. Stop your program and try again after typing trcstop, stops the trace.

Related Information

The gensyms command, gprof command, prof command, stripnm command, and trace daemon.

[ Top of Page | Previous Page | Next Page | Contents | Index | Library Home | Legal | Search ]