hpcprof-mpi:
Analysis and Attribution of Call Path Performance Measurements
The HPCToolkit Performance Tools
2021/09/11
Version 2022.10.01-develop
hpcprof-mpi
scalably
analyzes call path profile performance measurements (in parallel) and attributes them to static source code structure.
See hpctoolkit(1)
for an overview of HPCToolkit.
Table of Contents
hpcprof-mpi
[options]
measurement-group...
hpcprof-mpi
analyzes call path profile performance measurements,
attributes them to static source code structure,
and generates an experiment database for use with hpcviewer(1)
.
hpcprof-mpi
is especially designed for analyzing and attributing measurements
from large-scale executions.
hpcprof-mpi
expects a list of measurement groups,
each of which is either a call path profile directory or an individual profile file.
For best results, one other option should be given:
-I
to specify search directories for source code files.
If {hpcstruct(1)}
was run on the measurements directory, no -S
to provide structure files is needed.
is needed.
If no search directory arguments are given,
hpcprof-mpi
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.
- 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 {}.
- -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}
- --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)
This option may be given multiple times,
e.g. to provide structure for shared libraries in addition to the application executable.
It is normally not needed if {hpcstruct(1)}
was run on the measurements directory.
- -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 of a path to a binary measured by HPCToolkit
or a source file used to produce a binary measured by HPCToolkit.
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 no
longer present at their original path.
For instance, a library may have been compiled by a system administrator and
distributed with line map information containing file paths that point to a
build directory that no longer exists.
If you can locate a copy of the source code for the library, you can unpack
it anywhere and provide a -R option that maps the prefix of the build
directory to the prefix of the directory where you unpacked a copy of the library sources.
- --only-exe filename
-
Only include measurements for executables with the given filename. This option may be
given multiple times to indicate multiple executables to include.
Use this option when the application is measured through a wrapper script
(e.g. hpcrun script.sh)
and you don't want to include the shell used to run the script in the
resulting performance database.
- -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..
- -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.
hpctoolkit(1)
.
hpcprof-mpi(1)
.
Version: 2022.10.01-develop
- Copyright
- © 2002-2022, Rice University.
- License
- See LICENSE.
Rice University's HPCToolkit Research Group
Email: hpctoolkit-forum =at= rice.edu
WWW: http://hpctoolkit.org.