Clarify what tool-specific options are (#3444)

Fixes #3443

Modify the help message of pbench-register-tool to warn against using
operational options (i.e. options used internally by pbench) for a
tool when it is registered.

Modify the help message of base-tool (and everybody who is symlinked
to it) to clarify which are operational options and which are
tool-specific options: operational options should not be specified
when registering a tool: they are used by pbench internally; only
tool-specific options are specifed when registering the tool (on the
RHS of `--` in the invocation of `pbench-register-tool`).

PBENCH-1173

Author: ndokos

agent/tool-scripts/base-tool

@@ -191,17 +191,26 @@ esac
 
 function usage {
 	printf -- "The following options are available:\n\n"
+	printf -- "Operational options - do *not* specify any of these when you register a tool:\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 -- "\nTool-specific options - these should 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"
@@ -278,7 +287,9 @@ function usage {
 		printf -- "\t                           but not both at the same time\n"
 		;;
 	esac
-	printf -- "\n\t-h|--help                 display this help message\n"
+
+	printf -- "\nHelp option - do *not* specify this when you register a tool:\n\n"
+	printf -- "\t-h|--help                 display this help message\n\n"
 }
 
 # Process options and arguments
@@ -582,7 +593,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

@@ -2,12 +2,20 @@ blktrace: Error, one of the following options is required, --install|--start|--s
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should be specified when you register a tool:
+
 	--devices=str,[str]       the list of block devices to trace (required w/ --start)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 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

@@ -2,12 +2,20 @@ bpftrace: Error, one of the following options is required, --install|--start|--s
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should be specified when you register a tool:
+
 	--script=str              path to the bpftrace script (required w/ --start)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 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

@@ -2,12 +2,20 @@ cpuacct: Error, one of the following options is required, --install|--start|--st
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 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

@@ -2,12 +2,20 @@ disk: Error, one of the following options is required, --install|--start|--stop|
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 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

@@ -2,12 +2,20 @@ dm-cache: Error, one of the following options is required, --install|--start|--s
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 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

@@ -2,12 +2,20 @@ docker-info: Error, one of the following options is required, --install|--start|
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 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

@@ -2,12 +2,20 @@ docker: Error, one of the following options is required, --install|--start|--sto
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should be specified when you register a tool:
+
 	--interval=int            number of seconds between each data collection (optional, default is 10 seconds)
 
+Help option - do *not* specify this when you register a tool:
+
 	-h|--help                 display this help message
+
 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

@@ -2,13 +2,21 @@ haproxy-ocp: Error, one of the following options is required, --install|--start|
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should 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')
 
+Help option - do *not* specify this when you register a tool:
+
 	-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

@@ -2,13 +2,21 @@ iostat: Error, one of the following options is required, --install|--start|--sto
 
 The following options are available:
 
+Operational options - do *not* specify any of these when you register a tool:
+
 	--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 should 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)
 
+Help option - do *not* specify this when you register a tool:
+
 	-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