tprof Command

Purpose

Reports processor usage.

Syntax

tprof { [ -c ] [ -C { all | cpulist } ] [ -d ] -D ] [ -e ] [ -@ {ALL | wparlist } ] [ [ { -E [ mode [ -b ] [ -B ] } ] ] [ -f frequency ] ] [ -F ] [-I] [ -j ] [ -k ] [ -l ] [-L objectlist] [ -m objectslist ] [ -M sourcepathlist ] [-N] [ -p processlist ] [ -P { all | pidslist } ] [ -s ] [ -S searchpathlist ] [ -t ] [ -T buffersize ] [ -u ] [ -v ] [ -V verbosefilename ] [-g] [-G "start=mmddhhmmssyy",end=mmddhhmmssyy] [-O options]{ [-z] [-Z] | -R } { { -r rootstring } | { [ -A { all | cpulist }[ -n ] ] [ -r rootstring [ -X [ timedata [ , buckets=N ] ] ] ] { -x program | -y program } } } } { -a [ -A [ all ] ] [ -f frequency ] [ -F ] [ -v ] [ -z ] [ -V verbosefilename ] [ -T buffersize ] { { [ -r rootstring ] -y program } | { -r rootstring } } }
Note:
  • All the list type inputs are separated by a comma except for pathlist, which is separated by a colon.
  • Multi-cpu profiling mode is automatically disabled while running in real-time mode.
  • Microprofiling is automatically disabled if per-processor profiling is turned on.
  • Log Buffer size that was specified will be omitted if the tprof command runs in realtime mode.
  • If the -x flag is specified without the -A flag, tprof runs in realtime mode.
  • If the -x flag is specified with the -A flag, tprof runs in automated offline mode.
  • 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.
  • The -@ flag is automatically disabled if the tprof command runs in a workload partition in real-time or automated-offline modes.
  • The -y flag can be used only with the -E flag or the -a flag.
  • The -O showaddrbytes=on option cannot be used with the -z option.
  • The -O wrapfname=on option should be used with the -l option.
  • The -G option can be used only in post-processing mode.
  • The -O pdetails=on option can be used only with the -p option.
  • When manually collecting traces with the -A option for the tprof post-processing mode, it is mandatory to specify the -pP and I options of the trace command.

Description

The tprof command reports processor 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 processor-bound and who wants to know which sections of the program are most heavily using the processor.

The tprof command can charge processor 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 processor time to subroutines is called profiling and charging processor 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 traceback 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 the -g flag and the source files should be accessible to the tprof command or the program should be compiled with the -qlist flag and either both the object listing files and the source files or just the object listing files should be accessible to the tprof command. To take full advantage of tprof micro-profiling capabilities, it is best to provide both the .lst and the source file.

The tprof command can run in the following modes:
  • Realtime or online
  • Manual offline
  • Automated offline
  • Post-processing
If you specify the -x flag without the -A flag, the tprof command runs in realtime mode. In realtime mode, the tprof command 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 tprof reports.
Note: This mode does not allow per-processor profiling.
If you specify the -x flag with the -A flag, the tprof command runs in automated offline mode. In this mode, the tprof command starts the AIX trace utility and logs the trace data into a file. Once the trace data collection is done, it collects symbolic name information, and the tprof command opens the trace log file and processes the data to generate reports. In this mode, the tprof command generates the following files in addition to the tprof report files:
  • rootstring.syms
  • rootstring.trc [-cpuid]

All of the input and report files used by the tprof command are named rootstring.suffix, where rootstring is either specified with the -r flag, or is the program name specified with the -x flag.

In realtime mode and automated offline mode, the ulimit value of the data area for the program that is being profiled is set to unlimited.

In automated offline mode, you can specify the -N flag to collect source line information into the generated RootString.syms file. And you can specify the -I flag to collect binary instructions into the generated RootString.syms file.

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] files are trace log files. The -cpuid is added to the names when per-processor tracing is on. In that case, each file contains trace data from one processor only.

If you specify the -c flag with the -A flag, the rootstring.syms and rootstring.trc[-cpuid] files are not generated. Instead, the following two files are created:
  • rootstring.csyms
  • 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 you specify neither the -A flag nor the -x flag, the tprof command runs either in manual offline or in post-processing mode. To run the tprof command in post-processing mode, the following files must be available:
  • rootstring.csyms
  • rootstring.ctrc[ -cpuid ]

These files are generated when the tprof command runs (in any mode except post-processing mode) with the -c flag.

To run the tprof command in manual offline mode, the following files must be available:
  • rootstring.syms
  • rootstring.trc [-cpuid]

To generate these files, you need to manually run the gensyms command and AIX trace facility, or run the tprof command in automated offline mode without the -c flag.

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

If the input symbols file contains demangled names, you cannot use the -Z flag.

The tprof command generates a tprof report file named rootstring.prof, which holds the process, thread, object file and subroutine level profiling report. The file can contain the following sections and subsections:
  • Summary report section:
    • Processor usage summary by process name
    • Processor usage summary by threads (tid)
  • Global (pertains to the execution of all processes on system) profile section:
    • Processor usage of user mode routines
    • Processor usage of kernel routines, including milicode routines called in kernel mode
    • Processor usage summary for kernel extensions
    • Processor usage of each kernel extension's subroutines
    • Processor usage summary for privately loaded, global, and named shared libraries, and milicode routines called in user mode
    • Processor usage of each shared library's subroutines
    • Processor usage of each Java class
    • Processor usage of each Java methods of each Java class
  • Process and thread level profile sections (one section for each process or thread) :
    • Processor usage of user mode routines for this process/thread
    • Processor usage of kernel routines for this process/thread, including milicode routines called in kernel mode
    • Processor usage summary for kernel extensions for this process/thread
    • Processor usage of each kernel extension's subroutines for this process/thread
    • Processor usage summary for privately loaded, global, and named shared libraries for this process/thread, and milicode routines called in user mode
    • Processor usage of each shared library's subroutines for this process/thread
    • Processor usage of each Java class for this process/thread
    • Processor 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. You can turn on or turn off various subsections of the global profile section using the following profiling flags:
  • -u turns on subsections a
  • -k turns on subsection b
  • -e turns on subsections c and d
  • -s turns on subsections e and f
  • -j turns on subsections g and h

If you specify the -p, -P and -t flags, the process and thread level profile sections are created for processes and threads. 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, if you run the tprof command with the -C flag, the command also generates per-processor profiling reports, which contains one profiling report per processor. The generated tprof reports have the same structure and are named using the convention: rootstring.prof[-cpuid].

If you specify the -m flag, the tprof command 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, a number to uniquely identify them is appended to the report file names. For example, rootstring.Filename.c.mprof-1. The micro-profiling report has the following information:
  • The full path name of the annotated source file.
  • A hot line profile section which has all the line numbers from that source file hit by profiling samples, sorted by processor 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.
  • A source line profile section for each of the functions in that source file, which have processor usage. This section contains the source line number, processor usage and source code. If a .lst file for that source file is accessible to tprof, then it interlaces the instruction lines from the .lst file with the source lines from the source file and charges processor usage appropriately. This provides breakdown by instruction for each source file.

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

    If neither the .lst file nor the source file is present, but the source file is compiled with the -g flag, the tprof command retrieves the source line numbers and generates a similar report, with the source code column missing.
    Note: If per-processor profiling is requested, micro-profiling is automatically disabled. The tprof command cannot report correct source line information if a .c file is included in another .c file. The tprof command cannot micro-profile Java classes or methods.

If you specify the -m flag, the -N flag is automatically specified to gather the source line info into a symbols file in automated offline mode.

If you specify the -Z flag with the -m flag, one report file is generated per subroutine. The following naming convention is used: RootString.source.routine.mprof, where routine is the name of one of the subroutines listed in the source file. In addition, a file named RootString.source.HOT_LINES.mprof containing the hot line profiling information described above is also created.

If you specify the -L flag, the tprof command generates annotated listing files. The files use the following naming convention: RootString.source.alst, where source is the base name of a source file. If more than one source file has the same base name, a number to uniquely identify them is appended to the report file name. For example, RootString.Filename.c.alst-1. If you specify the -Z flag with the -L flag, one report file is generated per subroutine. The following naming convention is then used: RootString.source.routine.alst, where routine is the name of one of the subroutines listed in the source file.

If you specify the -N flag or -I flag when profiling a Java program using JPA (-x java -Xrunjpa or -x java -agentlib:jpa), the JIT source line number and instructions can be collected if the corresponding parameter is added to the -Xrunjpa flag or the -agentlib:jpa flag:
  • source=1 turns on JIT source line collecting (requires IBM® JRE 1.5.0 or later version).
  • instructions=1 turns on JIT instructions collecting.
The following restrictions apply for non-root users running the tprof command:
  • The tprof will not be able to verify that the running kernel is the same as the /unix file. This means that even if a warning message is displayed, in most cases the running kernel and /unix are the same, so the data should be accurate.
  • When the gensyms command is run by a non-root user, the same warning as in restriction #1 (above) is given and the gensyms file is marked. If tprof is run in the offline mode, the file created with the gensyms command will flag tprof as to kernel that is not verified.
  • The tprof will not be able to open and read symbols on files which do not have the read permission set. Some private, shared libraries do not have read permission, and some kernel extensions are not readable.

Time-Based versus Event-Based Profiling

By default, tprof is time-based and is driven by the decrementer interrupt. Another mode of profiling is event-based profiling, in which the interrupt is driven by either software-based events or by Performance Monitor events. With event-based profiling, both the sampling frequency and the profiling event can be varied on the command line.

The -E flag enables event-based profiling. The -E flag is one of the four software-based events (EMULATION, ALIGNMENT, ISLBMISS, DSLBMISS) or a Performance Monitor event (PM_*). By default, the profiling event is processor cycles. All Performance Monitor events are prefixed with PM_, such as PM_CYC for processor cycles or PM_INST_CMPL for instructions completed. The pmlist lists all Performance Monitor events that are supported on a processor. The chosen Performance Monitor event must be taken in a group where we can also find the PM_INST_CMPL Performance Monitor event. On POWER4 and later processors, profiling on marked events results in better accuracy. Marked events have the PM_MRK_ prefix.

If you specify the -y flag, only the specified program and its descendents are profiled. Use the -y flag only with the -E or -a flag.

The -f flag varies the sampling frequency for event-based profiling. For software-based events and processor cycles, supported frequencies range from 1 to 500 milliseconds, with a default of 10 milliseconds. For all other Performance Monitor events, the range is from 10000 to MAXINT occurrences of the event, with a default of 10000 events. If you specify the -f flag with the -y flag, the sampling frequency can range from 1 through the MAXINT occurrences for other Performance Monitor events, with a default of 10000 events.

Additional information is added to the .prof file to reflect the processor name, profiling event, and sampling frequency.

Java Applications Profiling

To profile Java applications, you must specify the -j flag, and start the applications with the -Xrunjpa API (for running on Java 5 and earlier JVMs) or the -agentlib:jpa (for running on Java 6 JVM) of the java command line option. When you specify this option, the JVM will automatically calls the jpa library whenever new classes and methods are loaded into memory. The library will in turn collect address to name mapping information for methods and classes in files named /tmp/JavaPID.syms, where PID is the process ID of a process running a Java Virtual Machine. The tprof command will automatically look in that directory for such files.

When running in automated offline mode, or selecting the cooking flags, the tprof command will copy the information contained in JavaPID.syms files into the RootString.syms or RootString.csyms file. The corresponding files in /tmp can then be deleted. The directory content should be kept up to date by tprof command users. Whenever the JVM corresponding to a particular JavaPID.syms is stopped, the file should be deleted.

Profile Accuracy

The degree to which processor 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.

Information

The -@ flag controls the addition of WPAR information to a tprof report. Sub-options specify what information is included to some of the report sections; these sub-options is in one of the following forms:
  • The -@ flag alone (that is, with no suboption) adds a summary of the processor usage WPAR name. Also, the WPAR name is shown for each process listed in the sections summarizing processor usage by process and by thread.
  • The ALL suboption causes the tprof report to contain a process, thread, object file and subroutine-level profiling report for the overall system and for each running WPAR.
  • A comma-separated list of WPAR names results in a process, thread, object file and subroutine-level profile section for each named WPAR in the tprof report.
Note: When a WPAR is used as a checkpoint and is restarted, some shared library areas might be local to the WPAR. In this case, the name of the WPAR is printed after the name of the area myarea@mywpar. In all other cases, the area is system-wide; thus the WPAR name is omitted.

XML Report Generating

The -X flag generates an XML report file named RootString.etm. This file can be shown in Visual Performance Analyzer. The XML report file contains four sections:
  • Profile general information
  • Symbol data
  • Profile hierarchy
  • Temporal data

The -X is used in automated offline mode to generate XML report directly.

The -X is also used in manual offline mode to generate XML report from the RootString.syms and RootString.trc files.

If the -X timedata is specified, the generated XML report will include the time data information. By default, the time data generating function is turned off.

To specify the bucket number for the time data, use the buckets=N argument. The default bucket number is 1800.

Large Page Analysis

The tprof -a command collects the profile trace from a representative application run, and produces performance projections. The projections map different portions of the data space of an application to different page sizes. The large page analysis uses the information in the trace to project translation buffer performance when the command maps any of the following application memory regions to a different page size:
  • Static application data (data that is initialized or not initialized)
  • Application heap (data that is dynamically allocated)
  • Stack
  • Application text
Performance projections are provided for each of the page sizes that the operating system supports. The first performance projection is a baseline projection that maps all of the memory regions to a default page size of 4 KB. Subsequent projections map one region at a time to a different page size. The following statistics are reported for each projection:
  • Page size
  • Number of pages needed to back all of the regions
  • Translation miss score
  • Cold translation miss score
The summary section lists the processes that are profiled and the statistics that are reported. It includes the following information:
  • Number or percentage of memory reference
  • Modeled memory reference
  • Malloc calls
  • Free calls

Data Profiling

The tprof -b command turns on basic data profiling and collects data access information. The summary section reports access information across the kernel data, library data, user global data, and the stack heap sections for each process.

If you specify the -b flag with the -s, -u, -k, and -e flags, the tprof command data profiling reports most used data structures (exported data symbols) in shared library, binary, kernel and kernel extensions. The -b flag also reports the functions that use those data structures.

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 binaries, while they do require special compilation flags, and induce a slowdown in the execution time that can be significant. prof does not work on stripped binaries.

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 processor consumption estimates for each subprogram by sampling the program counter of the user program.

tprof collects processor 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

Item Description
-@ { ALL | wparlist } Includes the WPAR information in the generated reports.

The ALL option includes summaries for all of the WPAR. When this option is set, the report contains a 'SYSTEM' report and a report per WPAR traced.

The wparlist option specifies a comma-separated list of WPAR. When the wparlist option is set, the tprof command produces a report for each WPAR specified.
-a Turns on the large page analysis.
-A { all | cpulist } Turns on automatic offline mode. No argument turns off per-processor tracing. all enables tracing of all processors. cpulist is a comma separated list of processor-ids to be traced.
-b Turns on basic data profiling.
-B Turns on basic data profiling with the information about the instruction address mapped function.
-c Turns on generation of cooked files.
-C all | cpulist Turns on the per-processor profiling. Specify all to generate profile reports for all processors. Processor numbers should be separated with a comma if you give a cpulist (for example, 0,1,2).
Note: per-processor profiling is possible only if per-processor 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. This option is not supported if the number of CPUs traced is greater than 128.
-d Turns on deferred tracing mode, that is defers data collection until trcon is called.
-D Turns on detailed profiling which displays processor usage by instruction offset under each subroutine.
-e Turns on kernel extension profiling.
-E [ mode ] Enables event-based profiling. The possible modes are:
PM_event
Specifies the hardware event to profile. If no mode is specified for the -E flag, the default event is processor cycles (PM_CYC).
EMULATION
Enables the emulation profiling mode.
ALIGNMENT
Enables the alignment profiling mode.
ISLBMISS
Enables the Instruction Segment Lookaside Buffer miss profiling mode.
DSLBMISS
Enables the Data Segment Lookaside Buffer miss profiling mode.
-f frequency Specifies the sampling frequency. The sampling frequency can be from 1 to 500 milliseconds for processor cycles and EMULATION, ALIGNMENT, ISLBMISS, and DSLBMISS events, and from 10000 to MAXINT event occurrences for other Performance Monitor events. If you specify the -f flag with the -y flag, the value of the sampling frequency ranges from 1 through the value of the MAXINT occurrences for other Performance Monitor events, with the default value of 10000 events.
-F Overwrites cooked files if they exists. If used without the -x flag, this forces the manual offline mode.
-g Does not translate symbol names into human-readable names.
-G Sets trace processing start date and end date. The parameters are specified in the following format: 
"start=mmddhhmmssyy,end=mmddhhmmssyy"
where mmddhhmmssyy is the month, day, hour, minute, second, and year respectively. This option can have the following values:
start
When set, trace processing starts from the specified start date string.
end
When set, trace processing stops at the specified end date string.
-I Turns on binary instructions collecting.
Note: The -I flag activates to gather binary instructions when generating symbol files or cooked symbol files in automated offline mode. However, in manual offline mode, the -I flag does not affect the report files.
-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.
-L objectlist Enables listing annotation for objects specified by the comma separated list, objectlist. Executables and shared libraries can have their listing files annotated. Specify the archive name for libraries.
Note:
  1. To enable listing annotation of programs, user mode profiling (-u) must be turned on.
  2. To enable listing annotation of shared libraries, shared library profiling (-s) must be turned on.
  3. To annotate a listing generated with IPA compilations, specify a.lst as the objectlist.
-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.
Note:
  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 and listing annotation.

By default the source path list is the object search path list.
-n Turns off postprocessing. If the -n flag is specified, the -u, -s, -k, -e, and -j flags are ignored. The data is collected, the .trc file and the gensyms files are generated, but the .prof file is not generated. This helps avoid overloading the system during a benchmark, for example. The -A flag must be used if the -n option is used.
-N Turns on source line number info collecting.

The -N flag activates to gather source line information when generating symbol files or cooked symbol files in automated offline mode. However, in manual offline mode, the -N flag does not affect the report files.
-O This option can have the following values:
showaddrbytes=[on|off]
Turns on the Address and Bytes columns in subroutine reports. The default value is off.
wrapfname=[on|off]
Turns on the line wrap of the long function name. To wrap the function names on a line, set value as -l. The default value is off.
pdetails=[on|off]
Turns on the data consolidation process for the report. The report consolidates data for the specified processlist in the kernel and sharedlib segment of the Process Summary section in the report.
-p processlist Enables process level profiling of the process names specified in the processlist. processlist is a comma separated list of process names

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.

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.

If you do not specify the -r flag, the rootstring parameter uses the default program name that the -x flag specifies.
-R Specifies that the tprof command should use samples weighted by PURR increment values to calculate percentages. This is the preferred mode when running in either simultaneous multithreading or Micro-Partitioning® environments.

The -R flag cannot be used with either the -z flag or the -Z 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.

The default object search PathList is the environment path list ($PATH).

-t Enables thread level profiling.

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.

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

The -x flag must be the last flag in the list of flags specified in tprof.
-X Specifies the tprof command to call XML Generator when the tprof profiling is finished, and to generate the XML report directly from the tprof trace and symlib data.

The -X option needs Java. Install the Java first, and make sure Java is in PATH.
-y Turns on the event-based profiling for only the specified command and its descendents.
-z Turns on ticks report. Enables compatibility mode with the previous version of tprof. By default processor 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.

If you specify the -z flag with the -a flag, the process summary section in the report displays numbers rather than percentages.
-Z Switches reports to use ticks instead of percentages (same as the -z flag), and splits annotated listing (when used with the -L flag) and annotated source files (when used with the -m flag) into multiple files, one per subroutine.

This option turns on the -g flag.

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

  1. The following example shows the basic global program and thread-level summary: 
    $tprof -x sleep 10

    An output that is similar to the following is displayed:

    Mon May 21 00:39:26 2012 System: AIX 6.1 Node: dreaming Machine: 000671894C00 
Starting Command sleep 10 
stopping trace collection. 
Generating sleep.prof

    The sleep.prof file that is generated only contains the summary report section.

  2. The following example shows the global profiling with all options: 
    $tprof -skeuj -x sleep 10

    An output that is similar to the following is displayed:

    Mon May 21 00:39:26 2012 
System: AIX 6.1 Node: drea
ming Machine: 000671894C00 
Starting Command sleep 10 
stopping trace collection.
Generating sleep.prof

    The sleep.prof file that is generated contains the summary report and global profile sections.

  3. The following example shows the single process level profiling: 
    $tprof -u -p workload -x workload

    An output that is similar to the following is displayed:

    Mon May 21 00:39:26 2012 
System: AIX 6.1 Node: drea
ming Machine: 000671894C00 
Starting Command workload stopping trace collection. 
Generating workload.prof

    The workload.prof file that is generated contains the summary report, 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. The following example shows the multiple process level profiling: 
    $tprof -se -p send,receive -x startall

    An output that is similar to the following is displayed:

    Mon May 21 00:39:26 2012 
System: AIX 6.1 Node: drea
ming Machine: 000671894C00 
Starting Command startall 
stopping trace collection. 
Generating startall.prof

    The startall.prof file that is generated contains the summary report, the global shared library mode profile, 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 library profiling information and one with kernel extensions profiling information.

  5. The following example shows the micro-profiling and listing annotation: 
    $tprof -m ./tcalc -L ./tcalc -u -x ./tcalc

    An output that is similar to the following is displayed:

    Mon May 21 00:39:26 2012 
System: AIX 6.1 Node: drea
ming Machine: 000671894C00 
Starting Command ./tcalc 
stopping trace collection. 
Generating tcalc.prof 
Generating tcalc.tcalc.c.mprof
Generating tcalc.tcalc.c.alst

    The tcalc.prof file that is generated contains the summary report and the global user mode profile sections. The resulting tcalc.tcalc.c.mprof and tcalc.tcalc.c.alst files contain the micro-profiling report and the annotated listing.

  6. For event-based profiling on processor cycles, sampling once every 100 milliseconds, enter the following command: 
    $tprof -E -f 100 -Askex sleep 10

    The output is similar to the following display:

    Starting Command sleep 10
stopping trace collection.
Tue Apr 26 14:44:02 2005
System: AIX 5.3 Node: bigdomino Machine: 00C0046A4C00
Generating sleep.trc
Generating sleep.prof
Generating sleep.syms
  7. For event-based profiling on completed instructions, sampling once every 20,000 completed instructions, enter the following command: 
    $tprof -E PM_INST_CMPL -f 20000 -Askex sleep 10

    The output is similar to the following display:

    Starting Command sleep 10
stopping trace collection.
Tue Apr 26 14:42:44 2005
System: AIX 5.3 Node: bigdomino Machine: 00C0046A4C00
Generating sleep.trc
Generating sleep.prof
Generating sleep.syms
  8. For event-based profiling on emulation interrupts, sampling once every 10000 events, enter the following command: 
    $tprof -E EMULATION -Askex sleep 10

    The output is similar to the following display:

    Starting Command sleep 10
stopping trace collection.
Tue Apr 26 14:41:44 2005
System: AIX 5.3 Node: bigdomino Machine: 00C0046A4C00
Generating sleep.trc
Generating sleep.prof
Generating sleep.syms
  9. The following example shows the automated offline mode: 
    $tprof -c -A all -x sleep 10

    The output is similar to the following display:

    Starting Command sleep 10 
stopping trace collection. 
Mon May 21 00:39:26 2012 
System: AIX 6.1 Node: drea
ming Machine: 000671894C00 
Generating sleep.ctrc 
Generating sleep.csyms 
Generating sleep.prof

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

  10. The following example shows the automated offline mode that is enabling source line collecting: 
    $tprof -A -N -x sleep 10

    The output is similar to the following display:

    Starting Command sleep 10
stopping trace collection.
Wed Feb 8 15:12:41 2006
System: AIX 5.3 Node: aixperformance Machine: 000F9F3D4C00
Generating sleep.trc
Generating sleep.prof
Generating sleep.syms
    The sleep.prof file that is generated only contains the summary report section, while sleep.syms contains the source line information.
  11. The following example shows the automated offline mode that is enabling source line and instruction collecting: 
    $tprof -A -N -I -r RootString -x sleep 10

    The output is similar to the following display:

    Starting Command sleep 10
stopping  trace collection.
Wed Feb  8 15:16:37 2006
System: AIX 5.3 Node: aixperformance Machine: 000F9F3D4C00
Generating RootString.trc
Generating RootString.prof
Generating RootString.syms
    The rootstring.prof file is generated. The rootstring.syms file contains the source line information and binary instructions.
  12. To enable Java source line and instructions collecting for the application HelloAIX that is running on Java 5 JVM in realtime mode, enter the following command: 
    $tprof -N -I -x java -Xrunjpa:source=1,instructions=1 Hello AIX

    The output is similar to the following display:

    Thu Feb  9 13:30:38 2006
System: AIX 5.3 Node: perftdev Machine: 00CEBB4A4C00
Starting Command java -Xrunvpn_jpa:source=1,instructions=1 Hello AIX
Hello AIX!
stopping trace collection.
Generating java.prof
    The java.prof file is generated. It contains the JIT source line information and the JIT instructions.
  13. The following example shows the processor usage for the vloop_lib_32 program without any shared library, thread-level profiling, per-processor tracing, or post processing: 
    $tprof -A -n -s -t -r test -x vloop_lib_32 5

    The output is similar to the following display:

    Starting Command vloop_lib_32 5
stopping trace collection.
Generating test.trc
Generating test.syms
  14. The following is an example of the automated offline mode for XML report: 
    $tprof -A -X -r RootString -x sleep 10
Starting Command sleep 10
stopping trace collection.
Tue Apr 17 22:00:24 2007
System: AIX 5.3 Node: test105 Machine: 00CEBB4A4C00
Generating sleep.trc
Generating sleep.syms
Calling tprof2xml to generate XML report.
tprof2xml TraceReader Version 1.2.0
Tue Apr 17 22:00:24 2007
System: AIX 6.1 Node: test105 Machine: 00CEBB4A4C00
 ------------------0------------------
Record 0
Post-processing counters
Retrieving Disassembly
writing the XML
Writing symbol list
.
Writing process hierarchy
Finished writing sleep.etm
  15. The following is an example of the automated offline mode enabling source line and instruction collecting: 
    $tprof -A -N -I -X -x sleep 10
Starting Command sleep 10
stopping trace collection.
Tue Apr 17 22:00:24 2007
System: AIX 5.3 Node: test105 Machine: 00CEBB4A4C00
Generating sleep.trc
Generating sleep.syms
Calling tprof2xml to generate XML report.
tprof2xml TraceReader Version 1.2.0
Tue Apr 17 22:00:24 2007
System: AIX 6.1 Node: test105 Machine: 00CEBB4A4C00
------------------0------------------
Record 0
Post-processing counters
Retrieving Disassembly
writing the XML
Writing symbol list
.
Writing process hierarchy
Finished writing sleep.etm
The symbol data elements in the xml report will have both bytes and
LineNumberList child elements.
  16. The following is an example of the automated offline mode for XML report enabling timedata: 
    $tprof -A -X timedata,buckets=100 -x sleep 10
Starting Command sleep 10
stopping trace collection.
Tue Apr 17 22:18:06 2007
System: AIX 5.3 Node: test105 Machine: 00CEBB4A4C00
Generating RootString.trc
Generating RootString.syms
Calling tprof2xml to generate XML report.
tprof2xml TraceReader Version 1.2.0
Tue Apr 17 22:18:06 2007
System: AIX 5.3 Node: test105 Machine: 00CEBB4A4C00
Tue Apr 17 22:18:06 2007
System: AIX 5.3 Node: test105 Machine: 00CEBB4A4C00
------------------0------------------
Record 0
Post-processing counters
Retrieving Disassembly
writing the XML
Writing symbol list
.
Writing process hierarchy
Finished writing RootString.etm
The RootString.etm will have bucket elements in each object of the profile
hierachy.
  17. The following is an example of the manual offline mode for XML report: 
    $tprof -A -x sleep 10
Starting Command sleep 10
stopping trace collection.
Tue Apr 17 22:28:01 2007
System: AIX 5.3 Node: test105 Machine: 00CEBB4A4C00
Generating sleep.trc
Generating sleep.prof
Generating sleep.syms
    To run the tprof to use the sleep.trc and sleep.syms to generate XML report, enter the following to specify the -r sleep to generate XMLl report: 
    $tprof -X -r sleep
Calling tprof2xml to generate XML report.
tprof2xml TraceReader Version 1.2.0
Tue Apr 17 22:28:01 2007
System: AIX 6.1 Node: test105 Machine: 00CEBB4A4C00
------------------0------------------
Record 0
Post-processing counters
Retrieving Disassembly
writing the XML
Writing symbol list
.
Writing process hierarchy
Finished writing sleep.etm
  18. For large page analysis of the workload and its descendants, enter the following command: 
    $tprof -a -y workload
    The output is similar to the following display: 
    Starting Command workload
stopping trace collection.
Tue Apr 26 14:42:44 2005
System: AIX 5.3 Node: bigdomino Machine: 00C0046A4C00
Generating workload.trc
Generating workload.prof
Generating workload.syms
  19. To profile only the specified program workload and its descendents, enter the following command: 
    $tprof -E PM_MRK_LSU_FIN -f 20000 –Aske –y workload
    The output is similar to the following display: 
    Starting Command workload
stopping trace collection.
Tue Apr 26 16:42:44 2005
System: AIX 5.3 Node: bigdomino Machine: 00C0046A4C00
Generating workload.trc
Generating workload.prof
Generating workload.syms
  20. To enable Java source line and instructions collecting for the application HelloAIX that is running on Java 6 JVM in realtime mode, enter the following command: 
    $ tprof -N -I -x java -agentlib:jpa=source=1,instructions=1 Hello AIX
    Note: When a 64-bit JDK is used, enter the -agentlib:jpa64 command instead of -agentlib:jpa in the following format:
    $ tprof -N -I -x java -agentlib:jpa64=source=1,instructions=1 Hello AIX
    The output is similar to the following display: 
    Fri May 30 04:16:27 2008
System: AIX 6.1 Node: toolbox2 Machine: 00CBA6FE4C00
Starting Command java -agentlib:jpa=source=1,instructions=1 Hello AIX
Hello AIX!
stopping trace collection.
Generating java.prof

    The java.prof file is generated. It contains the JIT source line information and JIT instructions.

  21. To displays the address bytes information in the report by using the -O showaddrbytes=on flag, enter the following command:
    $ tprof  -O showaddrbytes=on -x sleep 5
    A report similar to the following example is displayed: 
    
Subroutine                        %   Source                Address  Bytes 
==========                     ====== ======                =======  ===== 
h_cede_end_point                98.47 hcalls.s               111bfc     14 

Sample report without -O showaddrbytes=on option 

Subroutine                        %   Source                      
==========                     ====== ======         
h_cede_end_point                98.47 hcalls.s
  22. To display the process for trace data between 02/18/2016 02:30:30 and 02/18/2016 02:35:30 by using the -G option, enter the following command:
    $tprof  -G “start=021802303016,end=021802353016” -r sleep
    To process trace data starting from 02/18/2016 02:30:30 till the end, enter the following command:
    
$tprof -G “start= 021802303016” -r sleep
    To process trace data from start and until 02/18/2016 02:35:30, enter the following command: 
    $tprof -G “end=021802303517” -r sleep
  23. In the following example, the function name is 
    Test::abcdefghijklmnoprstuvwxyz ABCDEFGHIJKLMNOPQRSTUVWXYZ123456789
    . To display how to line wrap long function names by using the -O wrapfname=on option, enter the following command: 
    $tprof -ukesl -O wrapfname=on -x sleep 5

The following is a sample report: 
.Test::abcdefghijklmnoprstuvwxyz
ABCDEFGHIJKLMNOPQRSTUVW
XYZ123456789							215  19.40 test. C
    The following is a sample report without using the -O wrapfname=on option:
    Test::abcdefghijklmnoprstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ123456789_0abcdefghijk 
    lmnoprstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890(int,int)  215  19.40 test. C

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.