Caliper is a program instrumentation and performance measurement framework. It is a performance analysis toolbox in a library, that enables you to insert performance analysis capabilities directly into applications, and activate them at runtime. Caliper is intended for use with HPC applications, but works for any C/C++/Fortran program on Unix/Linux.
When MAP profiles a program instrumented with Caliper source code annotations the stack of Caliper attributes with keys of interest (corresponding to those used by Caliper's high-level API: function, loop, statement, annotation) is taken alongside regular samples. In MAP you can see where time was spent in any set of these key-attribute pairs.
Download Caliper (version 2.0.1 or later) from GitHub.
Build and install Caliper, then use it to instrument programs of your choice as described in the Caliper documentation:
Typically, we integrate Caliper into a program by marking source-code sections of interest with descriptive annotations. MAP can connect to Caliper and access the information provided by these annotations.
MAP supports Caliper's high-level C/C++ API for annotating functions, loops (although loop iterations will not be recorded) and code regions. Refer to the Annotation API in the Caliper documentation, for details and examples.
For Fortran programs the low-level API must be used to emulate the high-level API. Caliper regions must be nested - close all inner regions before closing an outer region. Only the following label types are supported: function, loop, statement, annotation (the same attribute names used by the high level API).
- Instrument your program with Caliper annotations (or use one of the Caliper-provided examples).
- Dynamically link your program against Caliper, and
profile it with MAP.
Caliper will be automatically detected and used, you do not need to set any special flags or options.
When profiling, Caliper may prompt you to enable Caliper services, this is not required. You may enable Caliper services if you wish but this will increase overhead without providing any additional data to MAP (although it may produce Caliper output files you could manually examine).
In MAP you will see a 'Selected Regions' graph (initially empty) underneath the 'Applications Activity' graph in the metrics view.
- Switch to the 'Regions' tab at the bottom of the screen to view the regions in your code that you annotated with Caliper. Optionally, select the 'Legend column' in the Regions tab to change the color used to represent a region.
- Enable one or more regions. Select one or more regions
in the Regions tab, right-click and choose Enable. Use
CTRL+Click or SHIFT+Click to select multiple regions.
Periods of time where the program was inside that region are displayed in the 'Selected Regions' graph.
- Enable 'Regions-focused view' from the 'View' menu (you can also use CTRL+R or the button next to the 'Selected Regions' graph). Application activity timeglyphs in the PSVs, Functions tab and Code Editor will switch to showing the time in the currently selected set of regions.
- The expected usage is that you will only have a few regions enabled at any one time.
- Note that the application activity graph will display the 'deepest' enabled region in any stacks to display.
- Only the default Caliper channel is sampled by MAP.
- Neither MAP nor Caliper will propagate Caliper attributes set on the main thread to OpenMP worker threads when entering a OpenMP parallel region.
Right-click on a region in the Regions tab to access further options. From here you can:
- Enable or disable all regions at once.
- Automatically reassign colors to regions based on the percentage of time in each in the current selected time range.
- Copy a text representation of the tab, or export it to a file.
- Refer to the following paper for more
background on Caliper:
David Boehme, Todd Gamblin, David Beckingsale, Peer-Timo Bremer, Alfredo Gimenez, Matthew LeGendre, Olga Pearce, and Martin Schulz. Caliper: Performance Introspection for HPC Software Stacks. In Supercomputing 2016 (SC16), Salt Lake City, Utah, November 13-18, 2016. LLNL-CONF-699263.
- Refer to the Annotation API in the Caliper documentation for full details and examples of annotations.
- Read a summary about Caliper
- Caliper full documentation
- Pre-instrumented examples (LULESH2 and Quicksilver)