hpcprof:
Analysis and Attribution of Call Path Performance Measurements

The HPCToolkit Performance Tools

2018/07/09

Version 2020.03.01-release

hpcprof analyzes call path profile performance measurements and attributes them to static source code structure. See hpctoolkit(1) for an overview of HPCToolkit.

Table of Contents

• Synopsis
• Description
• Arguments
  • Options: Informational
  • Options: Source Code and Static Structure
  • Options: Metrics
  • Options: Output
• Examples
• See Also
• Version
• License and Copyright
• Authors

Synopsis

hpcprof [options] measurement-group...

Description

hpcprof analyzes call path profile performance measurements, attributes them to static source code structure, and generates an experiment database for use with hpcviewer(1) or hpctraceviewer(1) . For analyzing and attributing the performance of large-scale executions, use hpcprof-mpi(1) , a parallel version of hpcprof.

hpcprof expects a list of measurement groups, each of which is either a call path profile directory or an individual profile file. For best results, two other options should be given: -I to specify search directories for source code files and -S to provide a source code structure file generated by hpcstruct(1) . If no search directory arguments are given, hpcprof will find only those source files that are specified via either an absolute path still preseent in the file system or a relative path w.r.t. the current working directory.

Arguments

measurement-group...

A sequence of file system paths, each speciufying a call path profile directory or an individual profile file.

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

Options: Informational

-v [n], --verbose [n]

Print progress messages to stderr at verbosity level n. {1}

-V, --version

Print version information.

-h, --help

Print help.

--debug [n]

Print debugging messages at level n. {1}

Options: Source Code and Static Structure

--name name, --title name

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

-I dir, --include dir

Use dir as a search directory to find source files. For a recursive search, append a '+' after the last slash, e.g., /mypath/+. This option may be given multiple times.

If a file appears in more than one search directory, the ambiguity is resolved in favor of the search directory which occurred first on the command line.

-S file, --structure file

Use the structure file file produced by hpcstruct(1) to identify source code elements for attribution of performance. This option may be given multiple times, e.g. to provide structure for shared libraries in addition to the application executable.

-R 'old-path=new-path', --replace-path 'old-path=new-path'

Replace every instance of old-path by new-path in all paths for which old-path is a prefix (e.g., in a profile's load map and source code). Use '\' to escape instances of '=' within a path. This option may be given 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: Metrics

-M metric, --metric metric

Compute the specified metrics, where metric is one of the following:

sum
Sum over threads/processes
stats
Sum, Mean, StdDev (standard deviation), CoefVar (coefficient of variation), Min, Max over threads/processes
thread
per-thread/process metrics

Note that hpcprof-mpi(1) cannot compute thread.

The default metric is sum. This option may be given multiple times.

--force-metric

Show all thread-level metrics regardless of their number.

--normalize all | none

If this option is all, normalize call paths in profiles to hide implementation details; if none, do not normalize. If not given, the default is all..

Options: Output

-o db-path, --db db-path, --output db-path

Write the computed experiment database to db-path. The default path is ./hpctoolkit-<application>-database.

--metric-db yes | no

If yes, generate a thread-level metric value database for hpcviewer scatter plots. The default is yes.

--remove-redundancy

Eliminate procedure name redundancy in output file experiment.xml.

--struct-id

Add 'str=nnn' field to profile data with the hpcstruct node id. The default is no.

Examples

See Also

hpctoolkit(1) .
hpcprof-mpi(1) .
hpcsummary(1) .

Version

Version: 2020.03.01-release

License and Copyright

Copyright

© 2002-2020, Rice University.

License

See README.License.

Authors

Rice University's HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.