minor doc updates

engine-cli/src/main/resources/commandline.md

@@ -4,29 +4,25 @@ Help ( You're looking at it. )
 
     --help
 
-Short options, like '-v' represent simple options, like verbosity.
+Short options, like '-v' represent simple options, like verbosity. Using multiples increases the
-Using multiples increases the level of the option, like '-vvv'.
+level of the option, like '-vvv'.
 
-Long options, like '--help' are top-level options that may only be
+Long options, like '--help' are top-level options that may only be used once. These modify general
-used once. These modify general behavior, or allow you to get more
+behavior, or allow you to get more details on how to use PROG.
-details on how to use PROG.
 
-All other options are either commands, or named arguments to commands.
+All other options are either commands, or named arguments to commands. Any single word without
-Any single word without dashes is a command that will be converted
+dashes is a command that will be converted into script form. Any option that includes an equals sign
-into script form. Any option that includes an equals sign is a
+is a named argument to the previous command. The following example is a commandline with a command *
-named argument to the previous command. The following example
+start*, and two named arguments to that command.
-is a commandline with a command *start*, and two named arguments
-to that command.
 
     PROG start driver=diag alias=example
 
 ### Discovery options ###
 
-These options help you learn more about running PROG, and
+These options help you learn more about running PROG, and about the plugins that are present in your
-about the plugins that are present in your particular version.
+particular version.
 
-Get a list of additional help topics that have more detailed
+Get a list of additional help topics that have more detailed documentation:
-documentation:
 
     PROG help topics
 
@@ -56,11 +52,10 @@ Provide the metrics that are available for scripting
 
 ### Execution Options ###
 
-This is how you actually tell PROG what scenario to run. Each of these
+This is how you actually tell PROG what scenario to run. Each of these commands appends script logic
-commands appends script logic to the scenario that will be executed.
+to the scenario that will be executed. These are considered as commands, can occur in any order and
-These are considered as commands, can occur in any order and quantity.
+quantity. The only rule is that arguments in the arg=value form will apply to the preceding script
-The only rule is that arguments in the arg=value form will apply to
+or activity.
-the preceding script or activity.
 
 Add the named script file to the scenario, interpolating named parameters:
 
@@ -92,12 +87,35 @@ Specify an override for one or more classes:
 
     --log-level-override com.foobarbaz:DEBUG,com.barfoobaz:TRACE
 
-Specify the logging pattern:
+Specify the logging pattern for console and logfile:
 
-    --with-logging-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
+    --logging-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
+    --logging-pattern 'TERSE'
 
-    ( default: '%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n' )
+Specify the logging pattern for console only:
-    ( See https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout for format options )
+
+    --console-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
+    --console-pattern 'TERSE-ANSI'
+
+Specify the logging pattern for logfile only:
+
+    --logfile-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
+    --logfile-pattern 'VERBOSE'
+
+    # See https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout
+    # These shortcuts are allowed
+    TERSE        %8r %-5level [%t] %-12logger{0} %msg%n%throwable
+    VERBOSE      %d{DEFAULT}{GMT} [%t] %logger %-5level: %msg%n%throwable
+    TERSE-ANSI   %8r %highlight{%-5level} %style{%C{1.} [%t] %-12logger{0}} %msg%n%throwable
+    VERBOSE-ANSI %d{DEFAULT}{GMT} [%t] %highlight{%logger %-5level}: %msg%n%throwable
+    # ANSI variants are auto promoted for console if --ansi=enable
+    # ANSI variants are auto demoted for logfile in any case
+
+Explicitly enable or disable ANSI logging support:
+(ANSI support is enabled if the TERM environment variable is defined)
+
+    --ansi=enabled
+    --ansi=disabled
 
 Specify a directory and enable CSV reporting of metrics:
 
@@ -133,6 +151,13 @@ Adjust the HDR histogram precision:
 
     --hdr-digits 3
 
+The default is 3 digits, which creates 1000 equal-width histogram buckets for every named metric in
+every reporting interval. For longer running test or for test which require a finer grain of
+precision in metrics, you can set this up to 4 or 5. Note that this only sets the global default.
+Each activity can also override this value with the hdr_digits parameter. Be aware that each
+increase in this number multiples the amount of detail tracked on the client by 10x, so use
+caution.
+
 Adjust the progress reporting interval:
 
     --progress console:1m
@@ -141,20 +166,18 @@ or
 
     --progress logonly:5m
 
-NOTE: The progress indicator on console is provided by default unless
+NOTE: The progress indicator on console is provided by default unless logging levels are turned up
-logging levels are turned up or there is a script invocation on the
+or there is a script invocation on the command line.
-command line.
 
-If you want to add in classic time decaying histogram metrics for your
+If you want to add in classic time decaying histogram metrics for your histograms and timers, you
-histograms and timers, you may do so with this option:
+may do so with this option:
 
     --classic-histograms prefix
     --classic-histograms 'prefix:.*'               # same as above
     --classic-histograms 'prefix:.*specialmetrics' # subset of names
 
-Name the current session, for logfile naming, etc
+Name the current session, for logfile naming, etc By default, this will be "scenario-TIMESTAMP", and
-By default, this will be "scenario-TIMESTAMP", and a logfile will be created
+a logfile will be created for this name.
-for this name.
 
     --session-name <name>
 
@@ -162,13 +185,12 @@ Enlist nosqlbench to stand up your metrics infrastructure using a local docker r
 
     --docker-metrics
 
-When this option is set, nosqlbench will start graphite, prometheus, and grafana automatically
+When this option is set, nosqlbench will start graphite, prometheus, and grafana automatically on
-on your local docker, configure them to work together, and point nosqlbench to send metrics
+your local docker, configure them to work together, and point nosqlbench to send metrics the system
-the system automatically. It also imports a base dashboard for nosqlbench and configures grafana
+automatically. It also imports a base dashboard for nosqlbench and configures grafana snapshot
-snapshot export to share with a central DataStax grafana instance (grafana can be found on localhost:3000
+export to share with a central DataStax grafana instance (grafana can be found on localhost:3000
 with the default credentials admin/admin).
 
-
 ### Console Options ###
 
 Increase console logging levels: (Default console logging level is *warning*)
@@ -179,9 +201,8 @@ Increase console logging levels: (Default console logging level is *warning*)
 
     --progress console:1m (disables itself if -v options are used)
 
-These levels affect *only* the console output level. Other logging level
+These levels affect *only* the console output level. Other logging level parameters affect logging
-parameters affect logging to the scenario log, stored by default in
+to the scenario log, stored by default in logs/...
-logs/...
 
 Show version, long form, with artifact coordinates.
 
@@ -189,10 +210,9 @@ Show version, long form, with artifact coordinates.
 
 ### Summary Reporting
 
-The classic metrics logging format is used to report results into the
+The classic metrics logging format is used to report results into the logfile for every scenario.
-logfile for every scenario. This format is not generally human-friendly,
+This format is not generally human-friendly, so a better summary report is provided by default to
-so a better summary report is provided by default to the console and/or a
+the console and/or a specified summary file by default.
-specified summary file by default.
 
 Examples:
 
@@ -205,16 +225,14 @@ Examples:
     # do both (the default)
     --report-summary-to stdout:60,_LOGS_/_SESSION_.summary
 
-Values of `stdout` or `stderr` are send summaries directly to the console,
+Values of `stdout` or `stderr` are send summaries directly to the console, and any other pattern is
-and any other pattern is taken as a file name.
+taken as a file name.
 
-You can use `_SESSION_` and `_LOGS_` to automatically name the file
+You can use `_SESSION_` and `_LOGS_` to automatically name the file according to the current session
-according to the current session name and log directory.
+name and log directory.
 
-The reason for the optional timing parameter is to allow for results of
+The reason for the optional timing parameter is to allow for results of short scenario runs to be
-short scenario runs to be squelched. Metrics for short runs are not
+squelched. Metrics for short runs are not generally accurate nor meaningful. Spamming the console
-generally accurate nor meaningful. Spamming the console with boiler-plate
+with boiler-plate in such cases is undesirable. If the minimum session length is not specified, it
-in such cases is undesirable. If the minimum session length is not
+is assumed to be 0, meaning that a report will always show on that channel.
-specified, it is assumed to be 0, meaning that a report will always show
-on that channel.
 

engine-docs/src/main/resources/docs-for-nb/reference/command_line.md

@@ -10,26 +10,29 @@ This is the same documentation you get in markdown format with the
 
 ---------------------------------------
 
+### Command-Line Options ###
+
 Help ( You're looking at it. )
 
     --help
 
-Short options, like '-v' represent simple options, like verbosity. Using multiples increases the level of the option,
+Short options, like '-v' represent simple options, like verbosity. Using multiples increases the
-like '-vvv'.
+level of the option, like '-vvv'.
 
-Long options, like '--help' are top-level options that may only be used once. These modify general behavior, or allow
+Long options, like '--help' are top-level options that may only be used once. These modify general
-you to get more details on how to use nosqlbench.
+behavior, or allow you to get more details on how to use nosqlbench.
 
-All other options are either commands, or named arguments to commands. Any single word without dashes is a command that
+All other options are either commands, or named arguments to commands. Any single word without
-will be converted into script form. Any option that includes an equals sign is a named argument to the previous command.
+dashes is a command that will be converted into script form. Any option that includes an equals sign
-The following example is a commandline with a command *start*, and two named arguments to that command.
+is a named argument to the previous command. The following example is a commandline with a command *
+start*, and two named arguments to that command.
 
     ./nb start driver=diag alias=example
 
 ### Discovery options ###
 
-These options help you learn more about running nosqlbench, and about the plugins that are present in your particular
+These options help you learn more about running nosqlbench, and about the plugins that are
-version.
+present in your particular version.
 
 Get a list of additional help topics that have more detailed documentation:
 
@@ -61,9 +64,10 @@ Provide the metrics that are available for scripting
 
 ### Execution Options ###
 
-This is how you actually tell nosqlbench what scenario to run. Each of these commands appends script logic to the
+This is how you actually tell nosqlbench what scenario to run. Each of these commands appends
-scenario that will be executed. These are considered as commands, can occur in any order and quantity. The only rule is
+script logic to the scenario that will be executed. These are considered as commands, can occur in any order and
-that arguments in the arg=value form will apply to the preceding script or activity.
+quantity. The only rule is that arguments in the arg=value form will apply to the preceding script
+or activity.
 
 Add the named script file to the scenario, interpolating named parameters:
 
@@ -71,7 +75,7 @@ Add the named script file to the scenario, interpolating named parameters:
 
 Add the named activity to the scenario, interpolating named parameters
 
-    run [arg=value]...
+    activity [arg=value]...
 
 ### General options ###
 
@@ -95,12 +99,35 @@ Specify an override for one or more classes:
 
     --log-level-override com.foobarbaz:DEBUG,com.barfoobaz:TRACE
 
-Specify the logging pattern:
+Specify the logging pattern for console and logfile:
 
-    --with-logging-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
+    --logging-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
+    --logging-pattern 'TERSE'
 
-    ( default: '%d{HH:mm:ss.SSS} [%thread] %-5level %logger{36} - %msg%n' )
+Specify the logging pattern for console only:
-    ( See https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout for format options )
+
+    --console-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
+    --console-pattern 'TERSE-ANSI'
+
+Specify the logging pattern for logfile only:
+
+    --logfile-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
+    --logfile-pattern 'VERBOSE'
+
+    # See https://logging.apache.org/log4j/2.x/manual/layouts.html#Pattern_Layout
+    # These shortcuts are allowed
+    TERSE        %8r %-5level [%t] %-12logger{0} %msg%n%throwable
+    VERBOSE      %d{DEFAULT}{GMT} [%t] %logger %-5level: %msg%n%throwable
+    TERSE-ANSI   %8r %highlight{%-5level} %style{%C{1.} [%t] %-12logger{0}} %msg%n%throwable
+    VERBOSE-ANSI %d{DEFAULT}{GMT} [%t] %highlight{%logger %-5level}: %msg%n%throwable
+    # ANSI variants are auto promoted for console if --ansi=enable
+    # ANSI variants are auto demoted for logfile in any case
+
+Explicitly enable or disable ANSI logging support:
+(ANSI support is enabled if the TERM environment variable is defined)
+
+    --ansi=enabled
+    --ansi=disabled
 
 Specify a directory and enable CSV reporting of metrics:
 
@@ -110,68 +137,71 @@ Specify the graphite destination and enable reporting
 
     --report-graphite-to <addr>[:<port>]
 
-Specify the interval for graphite or CSV reporting in seconds (default: 10)
+Specify the interval for graphite or CSV reporting in seconds:
 
-    --report-interval <interval-seconds>
+    --report-interval 10
 
-Specify the metrics name prefix for graphite reporting
+Specify the metrics name prefix for graphite reporting:
 
     --metrics-prefix <metrics-prefix>
 
-Log all HDR histogram data to a file
+Log all HDR histogram data to a file:
 
     --log-histograms histodata.log
     --log-histograms 'histodata.log:.*'
     --log-histograms 'histodata.log:.*:1m'
     --log-histograms 'histodata.log:.*specialmetrics:10s'
 
-Log HDR histogram stats to a CSV file
+Log HDR histogram stats to a CSV file:
 
     --log-histostats stats.csv
     --log-histostats 'stats.csv:.*'       # same as above
     --log-histostats 'stats.csv:.*:1m'    # with 1-minute interval
     --log-histostats 'stats.csv:.*specialmetrics:10s'
 
-Adjust the progress reporting inverval
+Adjust the HDR histogram precision:
 
-    --progress console:10s
+    --hdr-digits 3
+
+The default is 3 digits, which creates 1000 equal-width histogram buckets for every named metric in
+every reporting interval. For longer running test or for test which require a finer grain of
+precision in metrics, you can set this up to 4 or 5. Note that this only sets the global default.
+Each activity can also override this value with the hdr_digits parameter. Be aware that each
+increase in this number multiples the amount of detail tracked on the client by 10x, so use
+caution.
+
+Adjust the progress reporting interval:
+
+    --progress console:1m
 
 or
 
     --progress logonly:5m
 
-If you want to add in classic time decaying histogram metrics for your histograms and timers, you may do so with this
+NOTE: The progress indicator on console is provided by default unless logging levels are turned up
-option:
+or there is a script invocation on the command line.
+
+If you want to add in classic time decaying histogram metrics for your histograms and timers, you
+may do so with this option:
 
     --classic-histograms prefix
     --classic-histograms 'prefix:.*'               # same as above
     --classic-histograms 'prefix:.*specialmetrics' # subset of names
 
-
+Name the current session, for logfile naming, etc By default, this will be "scenario-TIMESTAMP", and
-Name the current session, for logfile naming, etc By default, this will be "scenario-TIMESTAMP", and a logfile will be
+a logfile will be created for this name.
-created for this name.
 
     --session-name <name>
 
-If you want to control the number of significant digits in all of the HDR metrics, including histograms and timers, then
+Enlist nosqlbench to stand up your metrics infrastructure using a local docker runtime:
-you can do so this way:
-
-    --hdr-digits 4
-
-The default is 4 digits, which creates 10000 equisized histogram buckets for every named metric in every reporting
-interval. For longer running test or for test which do not require this level of precision in metrics, you can set this
-down to 3 or 2. Note that this only sets the global default. Each activity can also override this value with the
-hdr_digits parameter.
-
-
-Enlist engineblock to stand up your metrics infrastructure using a local docker runtime:
 
     --docker-metrics
 
-When this option is set, engineblock will start graphite, prometheus, and grafana automatically on your local docker,
+When this option is set, nosqlbench will start graphite, prometheus, and grafana automatically on
-configure them to work together, and point engineblock to send metrics the system automatically. It also imports a base
+your local docker, configure them to work together, and point nosqlbench to send metrics the system
-dashboard for engineblock and configures grafana snapshot export to share with a central DataStax grafana instance
+automatically. It also imports a base dashboard for nosqlbench and configures grafana snapshot
-(grafana can be found on localhost:3000 with the default credentials admin/admin).
+export to share with a central DataStax grafana instance (grafana can be found on localhost:3000
+with the default credentials admin/admin).
 
 ### Console Options ###
 
@@ -183,9 +213,38 @@ Increase console logging levels: (Default console logging level is *warning*)
 
     --progress console:1m (disables itself if -v options are used)
 
-These levels affect *only* the console output level. Other logging level parameters affect logging to the scenario log,
+These levels affect *only* the console output level. Other logging level parameters affect logging
-stored by default in logs/...
+to the scenario log, stored by default in logs/...
 
 Show version, long form, with artifact coordinates.
 
     --version
+
+### Summary Reporting
+
+The classic metrics logging format is used to report results into the logfile for every scenario.
+This format is not generally human-friendly, so a better summary report is provided by default to
+the console and/or a specified summary file by default.
+
+Examples:
+
+    # report to console if session ran more than 60 seconds
+    --report-summary-to stdout:60
+
+    # report to auto-named summary file for every session
+    --report-summary-to _LOGS_/_SESSION_.summary
+
+    # do both (the default)
+    --report-summary-to stdout:60,_LOGS_/_SESSION_.summary
+
+Values of `stdout` or `stderr` are send summaries directly to the console, and any other pattern is
+taken as a file name.
+
+You can use `_SESSION_` and `_LOGS_` to automatically name the file according to the current session
+name and log directory.
+
+The reason for the optional timing parameter is to allow for results of short scenario runs to be
+squelched. Metrics for short runs are not generally accurate nor meaningful. Spamming the console
+with boiler-plate in such cases is undesirable. If the minimum session length is not specified, it
+is assumed to be 0, meaning that a report will always show on that channel.
+