Legion Prof

Legion Prof is a profiler for Legion applications that visualizes the tasks and other operations that occur during a program's execution. Documentation for installing and using the profiler is provided on the Legion profiling page.

Quickstart

Always make sure that you build Legion in release mode (DEBUG=0 or -DCMAKE_BUILD_TYPE=Release) when profiling Legion applications. Release mode provides a substantial (often factor of 5x or larger) speedup over debug builds.

After the application has been built, run with:

./your_legion_app -lg:prof 1 -lg:prof_logfile prof_%.gz

The flag -lg:prof 1 enables profiling, and -lg:prof_logfile specifies the path where the corresponding log files will be written. The character % will be replaced with the rank number in multi-node runs (starting at 0).

Once you have a set of logs, you can install the profiler. If you do not already have Rust installed, run:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

And then install the profiler with:

cargo install --all-features --locked legion_prof@0.YYMM.0

Where YYMM corresponds to the version of Legion you used in the application (i.e., YY.MM.0).

Important: The version of the profiler MUST match the version of Legion used in the application, or the profiler may be unable to parse the logs.

If you are running an unreleased version of Legion (e.g., on the master branch), then you can build with:

cargo install --all-features --locked --path legion/tools/legion_prof_rs

Once legion_prof is installed, run:

legion_prof --view prof_*.gz

For other modes of running Legion Prof, see the full profiler documentation.

Development

We use standard Rust development practices in developing Legion Prof.

The code is formatted via cargo fmt, and should compile warning-free at all times. Be sure when you are compiling to check with --all-features:

cargo check --all-features

When developing, you may wish to build your local copy, which you can do with:

cargo run --release --all-features -- --view ...

If you need to modify the legion_prof_viewer frontend as well, you can modify your Cargo.toml to point to your local copy:

legion_prof_viewer = { path = ".../path/to/prof-viewer", optional = true }