hpcprof:
Analysis and Attribution of Call Path Performance Measurements

The HPCToolkit Performance Tools

2021/09/11

Version 2024.01.1-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] measurements...

... hpcprof-mpi [options] measurements...

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) .

hpcprof-mpi additionally parallelizes the analysis across multiple compute nodes, using MPI for communication. This is usually not needed except for especially large-scale executions (more than about 100,000 threads). Using 8-10 compute nodes is recommended as larger numbers tend to not improve the analysis speed.

hpcprof/hpcprof-mpi expects a list of measurements, each of which is either a call path profile directory or an individual profile file. hpcprof/hpcprof-mpi will find only source files whose paths are recorded in an application binary, shared library, or GPU binary as an absolute path still present in the file system or a relative path with respect to the current working directory. If hpcstruct(1) was run on the measurements directory, no -S arguments are needed.

Arguments

measurements...

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

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

Options: Informational

-v, --verbose

Print additional messages to stderr.

-V, --version

Print version information.

-h, --help

Print help.

-j threads

Perform analysis with threads threads. {}

Options: Source Code and Static Structure

--name name, --title name

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

-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. If hpcstruct(1) was run on the measurements directory, no such arguments are needed.

-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.

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

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

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.

Examples

See Also

hpctoolkit(1) .

Version

Version: 2024.01.1-release

License and Copyright

Copyright

© 2002-2023, Rice University.

License

See LICENSE.

Authors

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