Manual configuration

When not using built-in performance measurement configurations (Built-in profiling configurations), through the ConfigManager API or the CALI_CONFIG environment variable, Caliper can be configured manually by setting configuration variables through the environment or configuration files.

Configuration variables have the form

CALI_<MODULE>_<KEY>=<VALUE>

Values can be strings, lists, numbers, or boolean values, depending on the variable. List elements are typically separated by commas. Boolean values can be given as ‘1’, ‘true’, or ‘0’, ‘false’ for true and false, respectively.

Generally, configuring Caliper requires selecting a set of services, which implement Caliper’s measurement functionality. Refer to Architecture and workflow to learn how services can be combined to form a complete measurement, data collection, and output pipeline. Select services with CALI_SERVICES_ENABLE configuration variable, for example by setting it as an environment variable:

$ export CALI_SERVICES_ENABLE=event,trace,recorder,timestamp

Many services have additional configuration variables. See Caliper services for a complete list of available services and their configuration.

Configuration files

Configuration variables can be put in configuration files. By default, Caliper reads the file caliper.config in the current working directory, if present. Alternatively, you can provide a list of configuration files with the CALI_CONFIG_FILE variable. Note that CALI_CONFIG_FILE can only be set through an environment variable.

The configuration files use a simple <VARIABLE>=<VALUE> syntax. Lines starting with # are interpreted as comments. Example:

# My configuration
CALI_SERVICES_ENABLE=event,recorder,timer,mpi
CALI_MPI_WHITELIST=MPI_Allreduce,MPI_Barrier
CALI_TIMER_TIMESTAMP=true

When multiple definitions of the same variable are given, the last definition is taken. When multiple configuration files are provided, they are processed in the order they are given. Values set through environment variables override values given in configuration files.

Configuration profiles

Configuration profiles allow you to put multiple Caliper configurations into a file and select one of them with a single switch. You can declare a profile in a configuration file with # [profile name]. The following lines up to the next profile declaration then belong to this profile. Entries that do not belong to any specific profile are inserted into the default profile. Caliper will use the profile given by the CALI_CONFIG_PROFILE variable, or the default profile if none is set.

Example:

CALI_CONFIG_PROFILE=callstack-trace

# [callstack-trace]
# A trace with call-path info
CALI_SERVICES_ENABLE=callpath,event,recorder,timer
CALI_CALLPATH_USE_NAME=true

# [hwc-trace]
# A trace with PAPI hardware counters
CALI_SERVICES_ENABLE=event,papi,recorder,timer
CALI_PAPI_COUNTERS=PAPI_FP_OPS

This file defines two configuration profiles, callstack-trace and hwc-trace, and selects the callstack-trace profile. You can override the profile selection by setting a different value in the CALI_CONFIG_PROFILE environment variable. Note that environment variables always override values set in a configuration file, regardless of the selected profile.

Configuration variables reference

This section describes the configuration variables of the Caliper runtime system.

Many Caliper services define additional configuration variables. See Caliper services for a list of Caliper services and their configuration.

Environment variables

These variables can only be set as environment variables.

CALI_CONFIG

A configuration string to enable one (or more) of Caliper’s built-in performance profiling configurations. See Built-in profiling configurations.

CALI_USE_OMPT

Set to “1” or “true” to activate the OpenMP tools interface in the OpenMP runtime. This is required for the ompt service. It is only necessary to set this if the OpenMP runtime is first initialized before the ompt service is initialized, otherwise the ompt service will activate the OpenMP tools interface automatically. When set to “0” or “false” Caliper will not use the OpenMP tools interface. See ompt

Configuration variables

These variables can be set using environment variables, config files, or the configuration API.

CALI_CONFIG_FILE

Comma-separated list of configuration files. The provided configuration files are read in order. Note: this variable can only be set as an environment variable or through the configuration API.

Default: caliper.config

CALI_SERVICES_ENABLE

Comma-separated list of Caliper service modules to enable.

Default: Not set. Caliper will not record performance data.

CALI_LOG_VERBOSITY

Verbosity level. Default: 1

0: No output except for severe errors.

1: Basic informational runtime output and warning messages.

2: Debug output. Shows e.g. memory usage of context trees,

trace buffers, and aggregation database.

3: More debug output. Shows configuration settings.

CALI_LOG_LOGFILE

Log file name, or ‘stdout’/’stderr’ for streaming to standard out or standard error, respectively. Default: stderr

CALI_CHANNEL_CONFIG_CHECK

Perform basic configuration sanity checks. Caliper prints warnings for incomplete configurations, e.g., if a snapshot trigger service is enabled but no output service.

Default: enabled (true)

CALI_MEMORY_POOL_SIZE

Defines the size of the per-thread memory pool for region data in bytes. This pool stores region names and the Caliper context tree.

Default: 1048576 (1 MiB)