Command-Line Hardware Performance Counting and Profiling

This documentation applies to PerfSuite version 0.6.1.


psrun is a PerfSuite command-line utility that can be used to gather hardware performance information on an unmodified executable. It's a convenient and flexible way to do quick performance monitoring/measurement.

psrun operates in one of two modes: "counting" mode or "profiling" mode. In counting mode, psrun reports overall performance information on your program, while in profiling mode, psrun relates hardware performance event occurrences to your program's source code in much the same way as time-based profilers like gprof.

Optionally, psrun can also monitor other resource usage of an application independent of hardware performance counters (e.g, maximum memory usage, faults, swaps, user/system time, exit information, etc).

Here are examples of the type of information that psrun provides in each mode of operation:

These examples were generated by post-processing the XML output of psrun with the tool psprocess.

Like several of the other components of PerfSuite, psrun makes use of the XML standard for data representation to enhance the flexibility and cross-platform compatibility of the data collected. Here is an example XML document created by psrun.

psrun uses libperfsuite and libpshwpc as the underlying libraries to support hardware performance counting. By default, libpshwpc uses the PAPI library (from the Innovative Computing Laboratory at the University of Tennessee-Knoxville) as the performance counter support layer, but the software has been designed to accept alternate support layers as needed.

psrun is available on x86, x86-64, and ia64 platforms and requires no modifications to your source code or relinking of your application (you can use it on unmodified binary executables). psrun supports both single-threaded and multi-threaded programs using the POSIX threads standard (pthreads).

psrun is only effective with progams that have been linked dynamically. If you want to do performance counting with a statically-linked program, please refer to the section Troubleshooting and Important Notes/Reminders for more information.

Manual Page



psrun - PerfSuite performance data collection tool  


psrun [option] command [args]  


psrun is a command-line utility that allows you to take performance measurements of unmodified executables. psrun takes as input a configuration XML document that describes the desired measurement. If no XML document is specified through the command-line option -c, psrun will use a default configuration. You can determine the default configuration file that will be used on your system by entering the command psrun -h. psrun can be used to perform aggregate data collection ("counting mode") or to do statistical profiling ("profiling mode"). By default, psrun operates in counting mode. See the FILES section below for more information. psrun uses library preloading to initialize performance measurement and therefore can only be used with executables that have been linked dynamically. If you would like to measure the performance of a statically-linked application, you can insert calls to the routines in the PerfSuite library libpshwpc to achieve similar results.  


The output of psrun is an XML document with the root element <hwpcreport> that contains the resulting performance data as well as information about other characteristics of the computer on which the performance data was collected. By default, the output XML document will be written to a file with the name command.[threadID].PID.xml, where command will be replaced with the name of the program being measured, PID will be replaced with the process ID of command, and threadID will be replaced with a unique integer thread identifier ranging from 0 to the number of additional threads created by command (threadID will only be present in the file name when support for POSIX threads is enabled with the option -p). You can specify a different output document prefix than psrun by using the option -o. If the option -r is used, psrun will gather additional resource usage information and write it to a separate XML document using the same name template as the performance data but with the extension .res.xml. The root element of the resource usage XML document will be of type <resourcereport>. Typical use of psrun involves measuring the performance of a program and then post-processing the output with the utility psprocess. However, customized post-processing of the output XML document is another option using XML-aware software of your choice. You can request output in a plain text (rather than XML) format by using the option -F text. This can be helpful if you do not wish to use psprocess to post-process your performance data.  


-a, --annotate TEXT
Include annotation TEXT in output
-c, --config FILE
Specify configuration file
-d, --domain DOMAIN
Specify counting domain (default user)
-f, --fork
Monitor child processes (default no)
-F, --format FORMAT
Select output format (default XML)
-h, --help
Provide brief help on usage
-o, --output PREFIX
Specify alternate output XML document prefix. The keywords "stdout" and "stderr" are recognized (default "psrun")
-p, --pthreads
Enable POSIX thread support
-r, --resource
Collect resource usage information
-t, --threshold INTEGER
Specify the overflow threshold to be used for profiling
-V, --version
Report psrun version


Specify annotation text for output
Specify configuration file
Select alternate domain (user|kernel|all)
Specify the name of an exclusion database (a flat file containing full path names of programs that should be excluded from monitoring)
Specify alternate prefix
Select output format (text|xml)
Do not use process ID in output name
Specify overflow threshold (for profiling)
Specify minimum CPU seconds for output
Monitor child processes
Specify alternate POSIX threads library
psrun alters the value of this environment variable before executing command


The following files are listed relative to the top-level PerfSuite installation path.
Directory containing predefined input configuration documents
Document Type Definition (DTD) for the output XML document
DTD for the input XML document (counting mode)
DTD for the input XML document (profiling mode)


Please refer to the file share/perfsuite/doc/BUGS for information about current known bugs in psrun.  


This manual page is a brief synopsis of the use of psrun and may not contain the most current information. Please refer to the documentation for psrun available at the PerfSuite web site or in the source code distribution for complete information about psrun.  

SEE ALSO, psconfig(1), psenv(1), psprocess(1)  


Rick Kufrin  


University of Illinois/NCSA Open Source License




Troubleshooting and Important Notes/Reminders

Here are some suggestions for troubleshooting use of psrun when things go wrong, as well as a few notes and reminders regarding the proper use of psrun:

Last modified: Monday, 03-Jan-2005 16:28:09 CST

National Center for Supercomputing Applications
University of Illinois at Urbana-Champaign