provide better defaults for summary reporting

engine-cli/src/main/java/io/nosqlbench/engine/cli/NBCLI.java

@@ -342,10 +342,13 @@ public class NBCLI {
             options.wantsStackTraces(),
             options.wantsCompileScript(),
             options.getReportSummaryTo(),
-            String.join("\n", args)
+            String.join("\n", args),
+            options.getLogsDirectory()
         );
+
         ScriptBuffer buffer = new BasicScriptBuffer()
-                .add(options.getCommands().toArray(new Cmd[0]));
+            .add(options.getCommands()
+                .toArray(new Cmd[0]));
         String scriptData = buffer.getParsedScript();
 
         if (options.wantsShowScript()) {
@@ -387,7 +390,7 @@ public class NBCLI {
         ScenariosResults scenariosResults = executor.awaitAllResults();
 
         ActivityMetrics.closeMetrics(options.wantsEnableChart());
-        scenariosResults.reportToLog();
+        //scenariosResults.reportToLog();
         ShutdownManager.shutdown();
 
 //        logger.info(scenariosResults.getExecutionSummary());

engine-cli/src/main/java/io/nosqlbench/engine/cli/NBCLIOptions.java

@@ -77,6 +77,7 @@ public class NBCLIOptions {
     private static final String REPORT_GRAPHITE_TO = "--report-graphite-to";
     private static final String REPORT_CSV_TO = "--report-csv-to";
     private static final String REPORT_SUMMARY_TO = "--report-summary-to";
+    private final static String REPORT_SUMMARY_TO_DEFAULT = "stdout:60,_LOGS_/_SESSION_.summary";
     private static final String PROGRESS = "--progress";
     private static final String WITH_LOGGING_PATTERN = "--with-logging-pattern";
     private static final String LOG_HISTOGRAMS = "--log-histograms";
@@ -84,6 +85,7 @@ public class NBCLIOptions {
     private static final String CLASSIC_HISTOGRAMS = "--classic-histograms";
     private final static String LOG_LEVEL_OVERRIDE = "--log-level-override";
     private final static String ENABLE_CHART = "--enable-chart";
+
     private final static String DOCKER_METRICS = "--docker-metrics";
     private final static String DOCKER_METRICS_AT = "--docker-metrics-at";
     private static final String DOCKER_GRAFANA_TAG = "--docker-grafana-tag";
@@ -150,7 +152,7 @@ public class NBCLIOptions {
     private final List<String> statePathAccesses = new ArrayList<>();
     private final String hdrForChartFileName = DEFAULT_CHART_HDR_LOG_NAME;
     private String dockerPromRetentionDays = "183d";
-    private String reportSummaryTo = "stdout:60";
+    private String reportSummaryTo = REPORT_SUMMARY_TO_DEFAULT;
 
     public String getAnnotatorsConfig() {
         return annotatorsConfig;
@@ -498,7 +500,7 @@ public class NBCLIOptions {
                     break;
                 case REPORT_SUMMARY_TO:
                     arglist.removeFirst();
-                    reportSummaryTo = arglist.removeFirst();
+                    reportSummaryTo = readWordOrThrow(arglist, "report summary file");
                     break;
                 case LIST_DRIVERS:
                 case LIST_ACTIVITY_TYPES:
@@ -726,7 +728,7 @@ public class NBCLIOptions {
 
     public String getScriptFile() {
         if (scriptFile == null) {
-            return logsDirectory + File.separator + "_SESSIONNAME_" + ".js";
+            return logsDirectory + File.separator + "_SESSION_" + ".js";
         }
 
         String expanded = scriptFile;

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

@@ -163,6 +163,7 @@ with the default credentials admin/admin).
 
 
 ### Console Options ###
+
 Increase console logging levels: (Default console logging level is *warning*)
 
     -v         (info)
@@ -172,8 +173,41 @@ 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, stored by default in logs/...
+parameters affect logging 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.
+