Correlation of Flat Profile Metrics with Static Program Structure

The HPCToolkit Performance Tools


Version 2017.11

hpcprof-flat correlates `flat' (IP histograms) profile metrics with static source code structure. See hpctoolkit(1) for an overview of HPCToolkit.

Table of Contents


hpcprof-flat [output-options] [correlation-options] profile-file...

hpcprof-flat [output-options] --config config-file


hpcprof-flat correlates flat profiling metrics with static source code structure and (by default) generates an Experiment database for use with hpcviewer(1) . hpcprof-flat is invoked in one of two ways. In the former, correlation options are specified on the command line along with a list of flat profile files. In the latter, these options along with derived metrics are specified in the configuration file config-file. Note that the first mode is generally sufficient since derived metrics may be computed in hpcviewer(1) . However, to facilitate the batch processing of the second mode, during the first mode, a sample configuration file (config.xml) is generated within the Experiment database. See the section Configuration File below for more details about its syntax.

For optimal results, structure information from hpcstruct(1) should be provided. Without structure information, hpcprof-flat will default to correlation using line map information.


A list of flat profile files.
The hpcprof-flat configuration file.

Default values for an option's optional arguments are shown in {}.

Options: General

-v [n], --verbose [n]
Verbose: generate progress messages to stderr at verbosity level n. {1} (Use n=3 to debug path replacement if metric and program structure is not properly matched.)

-V, --version
Print version information.

-h, --help
Print help.

--debug [n]
Debug: use debug level n. {1}

Options: Source Structure Correlation

--name name, --title name
Set the database's name (title) to name.

-I path, --include path
Use path when searching for source files. For a recursive search, append a '*' after the last slash, e.g., '/mypath/*' (quote or escape to protect from the shell). May pass multiple times.

-S file, --structure file
Use hpcstruct(1) structure file file for correlation. May pass multiple times (e.g., for shared libraries).

-R 'old-path=new-path', --replace-path 'old-path=new-path'
Substitute instances of old-path with new-path; apply to all paths (e.g., a profile's load map and source code) for which old-path is a prefix. Use '
'to escape instances of '=' within a path. May pass multiple times.

Use this option when a profile or binary contains references to files that have been relocated, such as might occur with a file system change.

Options: Output

-o db-path, --db db-path, --output db-path
Specify Experiment database name db-path. {./experiment-db}
--src [yes | no], --source [yes | no]
Whether to copy source code files into Experiment database. {yes} By default, hpcprof-flat copies source files with performance metrics and that can be reached by PATH/REPLACE statements, resulting in a self-contained dataset that does not rely on an external source code repository. Note that if copying is suppressed, the database is no longer self-contained.

Output Formats

Select different output formats and optionally specify the output filename file (located within the Experiment database). The output is sparse in the sense that it ignores program areas without profiling information. (Set file to '-' to write to stdout.)

-x [file], --experiment [file]
Default. ExperimentXML format. {experiment.xml}. NOTE: To disable, set file to no.

Configuration File

A hpcprof-flat configuration file is an XML document of type HPCPROF. The following briefly describes its syntax.


Derived or Computed Metrics

See Also

hpctoolkit(1) .


Version: 2017.11 of 2011/02/22.

License and Copyright

© 2002-2018, Rice University.
See README.License.


Nathan Tallent
John Mellor-Crummey
Rob Fowler
Rice HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.