APAPI is a wrapper library for the Performance Application Programming Interface (PAPI) library.
APAPI extends PAPI by following features:
- a timer mechanism to periodically read PAPI counters
- gathering of statistics (minimal, maximal, average and accumlated value)
PAPI is a library to read performance counters available on your system. Performance counters allow to measure certain system characteristics, e.g. miss-rate of the CPU cache. PAPI's generic terminology for a measurable value is "event". PAPI allows to be extended by "components" that offer additional events, e.g. values for specific devices.
libmeasure and APAPI
APAPI was primarily build to replace libmeasure's measurement mechanism. libapapi wraps PAPI and provides functionality that is required by libmeasure. libms_common_apapi provides the well-known interface to libmeasure while using PAPI for measurement. Applications that use libms_common can use libms_common_apapi to use PAPI.
Values delivered by PAPI are raw values. There are two types of raw values:
- accumulating values are growing monotonously and overflow
- non-accumulating values are simply updated
APAPI stores the last two raw values. If the raw value is non-accumulating then the last value is simply used as value0. If the raw value is accumulating then the last two values are used to check for an overflow and fix it. In this case the difference between the last two raw values is used as value0. This way the value0 is computed after every timer interval.
APAPI stores the last two values for value0. The last two values for value0 and it's timestamps can be used to compute value1.
For value0 and value1 statistics can be computed:
- minimal value - the smallest value encountered
- maximal value - the largest value encountered
- average value - the average value over the complete time period, every value is weighted by it's timing period
- accumulated value - the sum of all values
- default_eventops.txt: defines event metadata used to convert and print results
- default_eventlist.txt: defines lists of events that should be used when measuring certain PAPI components
- default component list: defines a default list of components to be used by applications
Default component list: rapl, nvml, maxeler, micknc, ipmi
APAPI provides methods to applications to evaluate environment variables.
- APAPI_EVENTLIST: path to file that defines alternative event lists similar to default_eventlist.txt
- APAPI_EVENTOPS: path to file that defines alternative event metadata similar to default_eventops.txt
- APAPI_CMPLIST: list of component names, e.g. APAPI_CMPLIST="nvml:maxeler:ipmi"
- APAPI_VERBOSE: libapapi will print additional messages, e.g. APAPI_VERBOSE=1
- APAPI_SOFTFAIL: libapapi will ignore certain unsuccessful actions, e.g. APAPI_VERBOSE=1
atime uses libapapi to measure arbitrary events.
atime [-t intervals] program [program arguments]
- -t -- allows to specifiy measurement intervals in nanoseconds, e.g. -t "nvml:250000000:ipmi:3000000000" for 250ms for nvml and 3s for ipmi
- program [program arguments] -- atime will start the program with its arguments and measure while it is running
atime will use the environment variables as following: If APAPI_CMPLIST is not specified then the default component list will be used. Only components in APAPI_CMPLIST are used. If in the APAPI_EVENTLIST file no events for a component are specified then the list from default_eventlist.txt is used. If the list is neither in the APAPI_EVENTLIST file nor in default_eventlist.txt specified, all events from the component are used. For an event the definition from the APAPI_EVENTOPS file is prioritized over the definition in default_eventops.csv.
LD_PRELOAD=/path/to/libms_common_apapi.so hettime [...]
Use LD_PRELOAD to force hettime to use libapapi. libms_common_apapi will use APAPI_CMPLIST only as subset of the default components supported by libmeasure (rapl, nvml, maxeler, micknc, ipmi).
Default file specification
Every line is interpreted as one event name. Lines starting with '#' are ignored. Empty lines are ignored.
Every line is interpreted as one event definition. Lines starting with '#' are ignored. Empty lines are ignored. One definition consists of several fields delimited by a ','. Fields should not contain unnecessary whitespace. One definition consists of the following fields:
- event name
- operation to use to compute value1 from value0 (last two values for value0 are called sample1 (last) and sample0 (previous))
- value1 = sample1 - sample0
- value1 = sample1 * (time1 - time0)
- value1 = (sample0 + sample1) / 2.0 * (time1 - time0)
- value1 = sample1 / (time1 - time0)
- statistics to compute for value0, single term or '|' delimited list of terms:
- APAPI_STAT_NO - no statistics
- statistics to compute for value1
- maximal raw counter value or 0 if counter is not accumulating
- name for type of value0
- unit for value0
- factor to use for value0
- name for type of value1
- unit for value1
- factor to use for value1