You copied the Doc URL to your clipboard.

32 Performance Analysis with Caliper Instrumentation

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.

32.1 Get Caliper

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:

32.2 Annotating your program

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.

32.2.1 Annotating in C/C++

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.


Using the low-level API for C/C++ applications is not recommended.

32.2.2 Annotating in Fortran

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

use Caliper 
call cali_begin_string_byname('function', 'myFunction')

32.3 Analyzing your program

Use Caliper with MAP to get a quick idea of how much time is spent in the various phases of your program, to help you decide where to focus your optimization efforts.

  1. Instrument your program with Caliper annotations (or use one of the Caliper-provided examples).
  2. 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.

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

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

32.4 Guidelines

  • 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.
Next steps

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