title: Measure intervals between events
name: measureinterval.stp
version: 1.0
author: William Cohen
keywords: monitoring
subsystem: none
status: experimental
exit: user-controlled
output: batch on-exit
scope: system-wide
description: The measureinteval.stp script allows quick creation of instrumentation to measure quantity between different probe points, aggregate the measurements, and display the results. The first argument to the script is the quantity to measure such as time in microseconds via "gettimeofday_us()".   There could be multiple intervals being measured concurrently and the second argument is the means to match the start probe points listed in the fourth argument with the end probes listed in the fifth argument.  The third argument is how to display the aggregated data.  The data could be displayed as a sum (@sum), an average (@avg), or a histogram (@hist_log).  The fourth and fifth arguments are lists of probes marking the start and end of an interval.  An optional sixth argument allows grouping of the intervals. One could use "tid()" for the matching argument to measure the intervals on a per-thread basis, but then use "execname()" for the optional argument to group the measurements by executable name.  If there is no sixth argument, all the intervals are aggregated into a single entry.
test_check: stap -p4 measureinterval.stp "gettimeofday_us()" "tid()" @sum vm.pagefault vm.pagefault.return "execname()"
test_installcheck: stap measureinterval.stp "gettimeofday_us()" "tid()" @sum vm.pagefault vm.pagefault.return "execname()" -c 'sleep 3'
