Caliper: A Performance Analysis Toolbox in a Library

Caliper is a program instrumentation and performance measurement framework. It is a performance-analysis toolbox in a library, allowing one to bake performance analysis capabilities directly into applications and activate them at runtime. Caliper is primarily aimed at HPC applications, but works for any C/C++/Fortran program on Unix or Linux.

Caliper’s data-collection mechanisms and source-code annotation API support a variety of performance-engineering use cases, e.g., performance profiling, tracing, monitoring, and auto-tuning.

Features include:

• Low-overhead source-code annotation API

• Configuration API to control performance measurements from within an application

• Recording program metadata for analyzing collections of runs

• Flexible key:value data model – capture application-specific features for performance analysis

• Fully threadsafe implementation, support for parallel programming models like MPI

• Trace and profile recording with flexible online and offline data aggregation

• Connection to third-party tools, e.g., NVidia Nsight/NVProf and Intel(R) VTune(tm)

• Measurement and profiling functionality, such as timers, PAPI hardware counters, and Linux perf_events

• Memory-allocation annotations: associate performance measurements with named memory regions

Caliper is available for download on GitHub.

Caliper Basics

This section covers basic Caliper usage, including source-code annotations and using Caliper’s built-in performance measurement configurations:

• Caliper Basics
  • Build and install
  • Region profiling
  • ConfigManager API
  • More on configurations
  • Loop profiling
  • Recording program metadata
  • Third-party tool support (NVidia NSight, Intel VTune)
  • C++ example program

Guides

This section lists how-to articles for various use cases.

• GPU profiling
• MPI Profiling
• OpenMP profiling
• Region filtering
• Event tracing and timelines
• Sample profiling
• Connection to third-party tools
• Fortran support

Reference documentation

The reference documentation below covers Caliper user APIs and specific usage aspects in detail:

• Building Caliper
• Annotation API reference
• ConfigManager API reference
• Built-in profiling configurations
• Manual configuration
• Architecture and workflow
• Caliper services
• The CalQL query language
• Output formatting
• Caliper tools
• Python reader API
• Developer guide

Materials

Tutorial slides: 2021 ECP Annual Meeting Tutorial slide deck.

About

Caliper was created by David Boehme.

A complete list of contributors is available on GitHub.

Major contributors include:

• Alfredo Gimenez (libpfm support, memory allocation tracking)

• David Poliakoff (GOTCHA support)

To reference Caliper in a publication, please cite the following paper:

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

Caliper is released under a BSD 3-clause license. See LICENSE for details.

LLNL Software release ID LLNL-CODE-678900.

Index

• Index