llnl/boba/boba-caliper-build-run

BoBa Caliper Build And Run

Use this skill when you need to build a BoBa target with Caliper, run it, save the report, and read the reported hotspots.

Quick Choice

• Use BOBA_ENABLE_CALIPER=1 when you want the normal BoBa internal profiling scopes.
• Use BOBA_ENABLE_CALIPER_EXTERNAL=1 when you want Caliper scopes outside BoBa internals, such as in exercises and tests.
• Use BOBA_ENABLE_CALIPER_OBJECTS=1 when you specifically need object-level profiling regions.
• Source caliper_lib_path_info_cpu before running on CPU so the runtime loader can find libcaliper. This file is generated by ./boba_builder.py.

make Flow

Build a target with Caliper enabled:

source caliper_lib_path_info_cpu
make clean
make test_boba_tensor_train BOBA_ENABLE_CALIPER=1

In the make flow, the output executable name usually picks up a suffix such as _cpu_cali.out. For this target the executable is test_boba_tensor_train_cpu_cali.out.

Run it with Caliper's runtime report and save the text output. Capture both stdout and stderr so the report table is not lost:

( CALI_CONFIG=runtime-report ./test_boba_tensor_train_cpu_cali.out ) 2>&1 | tee cali_runtime_report.txt

For profiling regions outside of BoBa source code while avoiding profiling BoBa source, use the "external" regions and add them to your code:

source caliper_lib_path_info_cpu
make clean
make test_boba_tensor_train BOBA_ENABLE_CALIPER_EXTERNAL=1
( CALI_CONFIG=runtime-report ./test_boba_tensor_train_cpu_cali.out ) 2>&1 | tee cali_apps_report.txt

CMake Flow

For CMake, the Caliper toggles are read from the environment and Caliper must also be discoverable through CALIPER_DIR.

source caliper_lib_path_info_cpu
BOBA_ENABLE_CALIPER=1 cmake -S . -B build -DCALIPER_DIR=/path/to/caliper/install
cmake --build build --target test_boba_tensor_train -j
( CALI_CONFIG=runtime-report ./build/examples/tests/test_boba_tensor_train ) 2>&1 | tee cali_runtime_report.txt

If you only want only the Caliper regions outside of BoBa source (e.g. in exercises or tests) ...

source caliper_lib_path_info_cpu
BOBA_ENABLE_CALIPER_EXTERNAL=1 cmake -S . -B build -DCALIPER_DIR=/path/to/caliper/install
cmake --build build --target test_boba_tensor_train -j
( CALI_CONFIG=runtime-report ./build/examples/tests/test_boba_tensor_train ) 2>&1 | tee cali_apps_report.txt

Reading The Report

• In this BoBa setup, runtime-report may emit the text table on stderr. Use ( ... ) 2>&1 | tee file.txt when you want a reliable saved copy.
• The exact columns can vary by Caliper version, but focus on the region name/path, time, time percentage, and call count columns.
• The hottest rows are the ones with the largest total time or largest time percentage.
• For hotspot ranking, prefer the largest Time (E) rows under main rather than main itself, since main is usually not the most actionable row.
• BOBA_CALI_MARK usually shows function-level regions.
• BOBA_CALI_BEGIN("..."), BOBA_CALI_SWITCH("...","..."), and BOBA_CALI_END("...") produce rows named after the explicit phase labels such as setup or iterating.
• BOBA_ENABLE_CALIPER_EXTERNAL=1 is useful when you want CALIPER scopes in code outside BoBa source, such as exercises and tests.

Practical Reading Workflow

1. Start with BOBA_ENABLE_CALIPER_EXTERNAL=1 to find which top-level phase dominates in external code.
2. Rebuild with BOBA_ENABLE_CALIPER=1 if you need finer detail inside that phase.
3. Open the saved report with less cali_runtime_report.txt.
4. Search for the heaviest region names and then rg those labels in include/BOBA/ or examples/ to find the owning code.

Precision Profiling

If on a temporary basis you want to profile a precise set of functions in a call stack but ignore everything else, BOBA_ENABLE_CALIPER_EXTERNAL can be used with BOBA_ENABLE_CALIPER_EXTERNAL=1 targeting just the desired functions. This might be useful for temporary targeted profiling.

Common Problems

• If the executable fails to start because libcaliper is missing, source caliper_lib_path_info_cpu in the current shell before running.
• If the report shows little or no BoBa profiling data, rebuild with one of BOBA_ENABLE_CALIPER=1, BOBA_ENABLE_CALIPER_EXTERNAL=1, or BOBA_ENABLE_CALIPER_OBJECTS=1.
• If you only see coarse rows, you likely built with BOBA_ENABLE_CALIPER_EXTERNAL=1 instead of full BOBA_ENABLE_CALIPER=1.