Getting started

Caliper is an abstraction layer for a variety of performance engineering tasks, such as tracing, profiling, monitoring, or on-line adaptation. Caliper provides

  • Annotation APIs for marking source-code regions or exporting arbitrary data in the form of key:value attributes. Annotations can be added (and removed) independent of each other; Caliper will automatically combine information from different annotations.
  • Built-in service modules, which provide measurement data (e.g., timestamps), or perform specific functions such as recording profiles or traces.

Source-code annotations and Caliper service modules can be flexibly combined to support a wide range of performance engineering use cases. Specific actions to be performed (e.g., creating a trace or profile) can be specified in a configuration profile at runtime.

Source-code annotations

Caliper provides annotation APIs for C, C++, and Fortran. The annotation commands fulfill two functions:

  1. They provide contextual information, such as the name of a code region or an iteration number.
  2. They serve as hooks for additional actions (e.g., taking performance measurements).

The specific action performed is determined by a runtime configuration profile. By default, the annotations perform no actions other than updating the Caliper-internal blackboard buffer.

The following example marks “initialization” and “loop” phases in a C++ code, and exports the main loop’s current iteration counter.

#include <caliper/cali.h>

int main(int argc, char* argv[])
{
    // Mark this function
    CALI_CXX_MARK_FUNCTION;

    // Mark the "intialization" phase
    CALI_MARK_BEGIN("initialization");
    // perform initialization tasks
    int count = 4;
    double t = 0.0, delta_t = 1e-6;
    CALI_MARK_END("initialization");

    // Mark the loop
    CALI_CXX_MARK_LOOP_BEGIN(mainloop, "mainloop");

    for (int i = 0; i < count; ++i) {
        // Mark each loop iteration
        CALI_CXX_MARK_LOOP_ITERATION(mainloop, i);

        // A Caliper snapshot taken at this point will contain
        // { "function" : "main"
        //   "loop"     : "mainloop"
        //   "iteration#mainloop" : <i> }

        // perform computation
        t += delta_t;
    }

    CALI_CXX_MARK_LOOP_END(mainloop);
}

Caliper-enabled tools will now be able to access the information provided by the source-code annotations at runtime by taking snapshots. The source-code annotations also provide hooks to enable various runtime actions in built-in Caliper service modules, such as triggering snapshots or writing traces.

In addition to the high-level macro API shown above, Caliper also provides lower-level C, C++, and Fortran APIs that can be used to define application-specific attributes. See Example: High-level annotation macros in C for examples in C and Fortran.

Configuring and Running Caliper programs

By default, Caliper annotation commands perform no actions other than updating a Caliper-internal blackboard buffer . However, we can connect a Caliper-enabled third-party tool to the program, or enable built-in Caliper “service” modules to take measurements and collect data.

As an example, Caliper’s built-in trace configuration profiles trigger and write snapshots whenever any or specific attributes are updated, generating a snapshot trace. A configuration profile can be selected with the CALI_CONFIG_PROFILE environment variable:

$ CALI_CONFIG_PROFILE=thread-trace ./cali-basic
== CALIPER: Registered pthread service
== CALIPER: Registered recorder service
== CALIPER: Registered timestamp service
== CALIPER: Initialized
== CALIPER: Wrote 36 records.
== CALIPER: Finished

With this configuration, Caliper will take a snapshot for each attribute update performed by the annotation commands, calculate the time spent in each of the annotated phases, and write the results in form of a snapshot trace to a .cali file in the current working directory.

Analyzing Data

Use the cali-query tool to filter, aggregate, or print the recorded traces. For example, the following command will show us the time spent in the “initialization” phase, in the entire “loop” phase, and in each iteration of the example program:

$ ls *.cali
160219-095419_5623_LQfNQTNgpqdM.cali
$ cali-query -s time.inclusive.duration --table \
      160219-095419_5623_LQfNQTNgpqdM.cali
function phase          loop      iter..loop time.inc..ation
main     initialization                                  100
main                    mainloop           0              23
main                    mainloop           1               9
main                    mainloop           2               6
main                    mainloop           3               8
main                    mainloop                          78
main                                                     258

Where to go from here?

The Concepts section explains Caliper’s underlying concepts better.

Much of Caliper’s functionality is implemented by built-in “services”, which can be enabled or disabled as needed. Refer to the Caliper Services section to learn about functionality they provide.

The Example: High-level annotation macros in C section in the documentation provides reference documentation for Caliper’s C, C++, and Fortran annotation APIs. Finally, the Caliper Tools section documents the command-line tools used to analyze and export the data streams produced by Caliper’s tracing and profiling services.