Clarify what tool-specific options are (#3444) (#3462)

Fixes #3443

Modify the help message of base-tool (and everybody who is symlinked
to it) to clarify the tool-specific options that may be specified when
registering a tool (on the RHS of `--` in the invocation of
`pbench-register-tool`).

PBENCH-1173

agent/tool-scripts/base-tool

@@ -190,24 +190,29 @@ vmstat)
 esac
 
 function usage {
-	printf -- "The following options are available:\n\n"
-	printf -- "\t--install                 verify this perf tool will work\n\n"
-	printf -- "\t--start|stop|postprocess  start/stop/postprocess the data collection\n"
-	printf -- "\t-d str|--dir=str          directory to store data collection (required)\n"
+	printf -- "\t-h|--help                 display this help message and exit\n\n"
+
+	printf -- "\nTool-specific options - these may be specified when you register a tool:\n\n"
+
 	case "${tool}" in
-	blktrace|bpftrace|kvmtrace|lockstat|oc|perf|strace|systemtap|tcpdump)
-		:  # These tools don't use interval
+	lockstat)
+		:  # Tools that don't take *any* tool-specific options
+		printf -- "\tNo tool-specific options for this tool\n"
+		;;
+	blktrace|bpftrace|kvmtrace|oc|perf|strace|systemtap|tcpdump)
+		:  # Tools that don't use '--interval' but take other tool-specific options
 		;;
 	*)
 		printf -- "\t--interval=int            number of seconds between each data collection (optional, default is %s seconds)\n" "${def_interval}"
 		;;
 	esac
+
 	case "${tool}" in
 	blktrace)
-		printf -- "\t--devices=str,[str]       the list of block devices to trace (required w/ --start)\n"
+		printf -- "\t--devices=str,[str]       the list of block devices to trace (required)\n"
 		;;
 	bpftrace)
-		printf -- "\t--script=str              path to the bpftrace script (required w/ --start)\n"
+		printf -- "\t--script=str              path to the bpftrace script (required)\n"
 		;;
 	haproxy-ocp)
 		printf -- "\t--counters-clear-all      clear all HAProxy counters at tool start (optional, default: '%s')\n" "${def_counters_clear_all}"
@@ -278,7 +283,6 @@ function usage {
 		printf -- "\t                           but not both at the same time\n"
 		;;
 	esac
-	printf -- "\n\t-h|--help                 display this help message\n"
 }
 
 # Process options and arguments
@@ -582,7 +586,7 @@ install)
 		local _installed_rpm
 		local _rc
 		_installed_rpm="$(require-rpm "${_tpn}" "${_tpv}")"
-		_rc=${?} 
+		_rc=${?}
 		if [[ ${_rc} != 0 ]]; then
 			printf -- "%s: %s is not installed\n" "${tool}" "${_tpn}${_tpv:+-${_tpv}}" >&2
 		else

agent/tool-scripts/tests/blktrace/gold/stderr

@@ -1,13 +1,10 @@
 blktrace: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--devices=str,[str]       the list of block devices to trace (required w/ --start)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--devices=str,[str]       the list of block devices to trace (required)
 blktrace: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/blktrace/tools-group/blktrace', missing
 blktrace: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/blktrace/tools-group/blktrace', missing

agent/tool-scripts/tests/bpftrace/gold/stderr

@@ -1,13 +1,10 @@
 bpftrace: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--script=str              path to the bpftrace script (required w/ --start)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--script=str              path to the bpftrace script (required)
 bpftrace: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/bpftrace/tools-group/bpftrace', missing
 bpftrace: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/bpftrace/tools-group/bpftrace', missing

agent/tool-scripts/tests/cpuacct/gold/stderr

@@ -1,13 +1,10 @@
 cpuacct: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 cpuacct: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/cpuacct/tools-group/cpuacct', missing
 cpuacct: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/cpuacct/tools-group/cpuacct', missing

agent/tool-scripts/tests/disk/gold/stderr

@@ -1,13 +1,10 @@
 disk: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 disk: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/disk/tools-group/disk', missing
 disk: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/disk/tools-group/disk', missing

agent/tool-scripts/tests/dm-cache/gold/stderr

@@ -1,13 +1,10 @@
 dm-cache: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 dm-cache: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/dm-cache/tools-group/dm-cache', missing
 dm-cache: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/dm-cache/tools-group/dm-cache', missing

agent/tool-scripts/tests/docker-info/gold/stderr

@@ -1,13 +1,10 @@
 docker-info: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 docker-info: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/docker-info/tools-group/docker-info', missing
 docker-info: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/docker-info/tools-group/docker-info', missing

agent/tool-scripts/tests/docker/gold/stderr

@@ -1,13 +1,10 @@
 docker: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 docker: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/docker/tools-group/docker', missing
 docker: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/docker/tools-group/docker', missing

agent/tool-scripts/tests/haproxy-ocp/gold/stderr

@@ -1,14 +1,11 @@
 haproxy-ocp: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
+Tool-specific options - these may be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--counters-clear-all      clear all HAProxy counters at tool start (optional, default: 'false')
-
-	-h|--help                 display this help message
 haproxy-ocp: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/haproxy-ocp/tools-group/haproxy-ocp', missing
 haproxy-ocp: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/haproxy-ocp/tools-group/haproxy-ocp', missing

agent/tool-scripts/tests/iostat/gold/stderr

@@ -1,14 +1,11 @@
 iostat: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
+Tool-specific options - these may be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--options=str             options passed directly to the tool (optional)
-
-	-h|--help                 display this help message
 iostat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/iostat/tools-group/iostat', missing
 iostat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/iostat/tools-group/iostat', missing

agent/tool-scripts/tests/jmap/gold/stderr

@@ -1,15 +1,12 @@
 jmap: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
+Tool-specific options - these may be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--pid=int                 a process ID to jmap
 	--pattern=str             jmap any PID which name matches this string (via pgrep)
-
-	-h|--help                 display this help message
 jmap: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/jmap/tools-group/jmap', missing
 jmap: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/jmap/tools-group/jmap', missing

agent/tool-scripts/tests/jstack/gold/stderr

@@ -1,15 +1,12 @@
 jstack: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
+Tool-specific options - these may be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--pid=int                 a process ID to jstack
 	--pattern=str             jstack any PID which name matches this string (via pgrep)
-
-	-h|--help                 display this help message
 jstack: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/jstack/tools-group/jstack', missing
 jstack: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/jstack/tools-group/jstack', missing

agent/tool-scripts/tests/kvm-spinlock/gold/stderr

@@ -1,13 +1,10 @@
 kvm-spinlock: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 kvm-spinlock: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvm-spinlock/tools-group/kvm-spinlock', missing
 kvm-spinlock: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvm-spinlock/tools-group/kvm-spinlock', missing

agent/tool-scripts/tests/kvmstat/gold/stderr

@@ -1,13 +1,10 @@
 kvmstat: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
-	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 kvmstat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvmstat/tools-group/kvmstat', missing
 kvmstat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvmstat/tools-group/kvmstat', missing

agent/tool-scripts/tests/kvmtrace/gold/stderr

@@ -1,16 +1,13 @@
 kvmtrace: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
+Tool-specific options - these may be specified when you register a tool:
+
 	--vm=str                  the hostname of the vm running (to get kallsyms)
 	--timeout=int             how long the trace will run (default is 1 second)
 	                          If 0 is used, the trace will not stop until stop-tools is called
 	--start-delay=int         sleep this many seconds before starting the trace (default is 0 seconds)
-
-	-h|--help                 display this help message
 kvmtrace: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvmtrace/tools-group/kvmtrace', missing
 kvmtrace: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/kvmtrace/tools-group/kvmtrace', missing

agent/tool-scripts/tests/lockstat/gold/stderr

@@ -1,12 +1,10 @@
 lockstat: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
+Tool-specific options - these may be specified when you register a tool:
 
-	-h|--help                 display this help message
+	No tool-specific options for this tool
 lockstat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/lockstat/tools-group/lockstat', missing
 lockstat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/lockstat/tools-group/lockstat', missing

agent/tool-scripts/tests/mpstat/gold/stderr

@@ -1,14 +1,11 @@
 mpstat: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
+Tool-specific options - these may be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--options=str             options passed directly to the tool (optional)
-
-	-h|--help                 display this help message
 mpstat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/mpstat/tools-group/mpstat', missing
 mpstat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/mpstat/tools-group/mpstat', missing

agent/tool-scripts/tests/numastat/gold/stderr

@@ -1,14 +1,11 @@
 numastat: Error, one of the following options is required, --install|--start|--stop|--postprocess
 
-The following options are available:
+	-h|--help                 display this help message and exit
 
-	--install                 verify this perf tool will work
 
-	--start|stop|postprocess  start/stop/postprocess the data collection
-	-d str|--dir=str          directory to store data collection (required)
+Tool-specific options - these may be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 	--pattern=str             a pattern for matching which processes for reporting per-node memory allocation
-
-	-h|--help                 display this help message
 numastat: WARNING - postprocess - tool output directory, '/var/tmp/pbench-test-tool-scripts/numastat/tools-group/numastat', missing
 numastat: WARNING - stop - tool output directory, '/var/tmp/pbench-test-tool-scripts/numastat/tools-group/numastat', missing