NB5 Docs► User Guide▼ Command Line Options 🖺

The NoSQLBench CLI

Help (You're looking at it.)


Short options, like '-v', represent simple options, like verbosity. Using multiples increases the 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 you to get more details on how to use nb5.

All other options are either commands, or named arguments to commands.

The following example is a commandline with a command start, and two named arguments to that command.

nb5 start driver=diag alias=example

Discovery options

These options help you learn more about running nb5, and about the plugins that are present in your particular version.

Get a list of additional help topics that have more detailed documentation:

nb5 help topics

Provide specific help for the named activity type:

nb5 help <activity type>

List the available drivers:


List the available scenarios:


List only the available workloads which contain the above scenarios:


Copy a workload or other file to your local directory as a starting point:

--copy <name>

Provide the metrics that are available for scripting:

--list-metrics <activity type> [ <activity name> ]

Execution Options

This is how you actually tell nb5 what scenario to run. Each of these commands appends script logic to the scenario that will be executed. These are considered as commands, can occur in any order and 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:

script <script file> [arg=value]...

Add the named activity to the scenario, interpolating named parameters

activity [arg=value]...

General options

These options modify how the scenario is run.

Specify a directory for scenario log files:

--logs-dir <dirname>

Specify a limit on logfiles (old files will be purged):

--logs-max <count>

Specify the priority level of file logs:

--logs-level <level>

where <level> can be one of OFF, ERROR, WARN, INFO, DEBUG, TRACE, or ALL

Specify an override for one or more classes:

--log-level-override com.foobarbaz:DEBUG,com.barfoobaz:TRACE

Specify the logging pattern for console and logfile:

--logging-pattern '%date %level [%thread] %logger{10} [%file:%line] %msg%n'
--logging-pattern 'TERSE'

Specify the logging pattern for console only:

--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):


Specify a directory and enable CSV reporting of metrics:

--report-csv-to <dirname>

Specify the graphite destination and enable reporting

--report-graphite-to <addr>[:<port>]

Specify the interval for graphite or CSV reporting in seconds:

--report-interval 10

Specify the metrics name prefix for graphite reporting:

--metrics-prefix <metrics-prefix>

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-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 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


--progress logonly:5m

👉 The progress indicator on console is provided by default unless logging levels are turned up 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 a logfile will be created for this name.

--session-name <name>

Console Options

Increase console logging levels: (Default console logging level is warning)

-v         (info)
-vv        (debug)
-vvv       (trace)

--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/...

Show version, long form, with artifact coordinates.


The logged metrics reporting to console at INFO level is often problematic. This can be explicitly enabled or disabled:

# the current default, soon to be deprecated
# use this if you need to stop being spammed by a high-frequency reporting interval

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.


# 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 boilerplate 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.

Labeling Options

For an in-depth introduction to descriptive metadata support in NoSQLBench, see the Labeling Results section.

You can add labels and their values to a NoSQLBench session:

# all at once
--add-labels "label1:value1,label2:value2"

# incrementally
--add-labels "label1:value1" --add-labels "label2:value2"

All such labels must have names and values which are compatible with metrics systems, which means the initial character must be alphabetic, and all subsequent characters must be alphanumeric or underscores.

You can establish labeling specification (standard forms) for metrics and annotations with:

# set both --annotate-labelspec and --metrics-labelspec
--labelspec "+instance,+session,+specialcircumstancelabel"
# set different labelspecs for metrics and annotation:
--metrics-labelspec "+instance,+session" --annotate-labelspec "+instance,+session,+region"

These can serve as a safety against sending invalid label data to a downstream system and polluting the namespace of all results.

Back to top