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
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 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,timestamp: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 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.
CALI_CONFIG_PROFILE=callstack-trace # [callstack-trace] # A trace with call-path info CALI_SERVICES_ENABLE=callpath,event,recorder,timestamp CALI_CALLPATH_USE_NAME=true # [hwc-trace] # A trace with PAPI hardware counters CALI_SERVICES_ENABLE=event,papi,recorder,timestamp 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.
A configuration string to enable one (or more) of Caliper’s built-in performance profiling configurations. See Built-in profiling configurations.
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.
Comma-separated list of Caliper service modules to enable.
Default: Not set. Caliper will not record performance data.
- Verbosity level. Default: 10: 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.
Log file name, or ‘stdout’/’stderr’ for streaming to standard out or standard error, respectively. Default: stderr
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 (