IntenseFinance/nosqlbench
3
0
Fork 0
mirror of https://github.com/nosqlbench/nosqlbench.git synced 2024-11-23 09:16:37 -06:00
Code Issues Packages Projects Releases Wiki Activity

minor doc updates

Browse Source
This commit is contained in:
Jonathan Shook 2021-11-09 22:26:03 -06:00
parent d94594a4e8
commit 0798b9a8b7
2 changed files with 178 additions and 101 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

126
engine-cli/src/main/resources/commandline.md
View File

@ -4,29 +4,25 @@ Help ( You're looking at it. )
--help
Short options, like '-v' represent simple options, like verbosity.
Using multiples increases the level of the option, like '-vvv'.
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 PROG.
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 PROG.
All other options are either commands, or named arguments to commands.
Any single word without dashes is a command that will be converted
into script form. Any option that includes an equals sign 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.
All other options are either commands, or named arguments to commands. Any single word without
dashes is a command that will be converted into script form. Any option that includes an equals sign
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.
PROG start driver=diag alias=example
### Discovery options ###
These options help you learn more about running PROG, and
about the plugins that are present in your particular version.
These options help you learn more about running PROG, and about the plugins that are present in your
particular version.
Get a list of additional help topics that have more detailed
documentation:
Get a list of additional help topics that have more detailed 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
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.
This is how you actually tell PROG 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:
@ -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' )
( See https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout for format options )
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)
--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
logging levels are turned up or there is a script invocation on the
command line.
NOTE: 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:
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.
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>
@ -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
on your local docker, configure them to work together, and point nosqlbench to send metrics
the system automatically. It also imports a base dashboard for nosqlbench and configures grafana
snapshot export to share with a central DataStax grafana instance (grafana can be found on localhost:3000
When this option is set, nosqlbench will start graphite, prometheus, and grafana automatically on
your local docker, configure them to work together, and point nosqlbench to send metrics the system
automatically. It also imports a base dashboard for nosqlbench and configures grafana snapshot
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
parameters affect logging to the scenario log, stored by default in
logs/...
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.
@ -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
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.
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:
@ -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,
and any other pattern is taken as a file name.
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.
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.
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.

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

@ -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,
like '-vvv'.
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 nosqlbench.
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 nosqlbench.
All other options are either commands, or named arguments to commands. Any single word without dashes is a command that
will be converted into script form. Any option that includes an equals sign 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.
All other options are either commands, or named arguments to commands. Any single word without
dashes is a command that will be converted into script form. Any option that includes an equals sign
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
version.
These options help you learn more about running nosqlbench, and about the plugins that are
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
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.
This is how you actually tell nosqlbench 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:
@ -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' )
( See https://logback.qos.ch/manual/layouts.html#ClassicPatternLayout for format options )
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)
--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
option:
NOTE: 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.
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>
If you want to control the number of significant digits in all of the HDR metrics, including histograms and timers, then
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:
Enlist nosqlbench 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,
configure them to work together, and point engineblock to send metrics the system automatically. It also imports a base
dashboard for engineblock and configures grafana snapshot export to share with a central DataStax grafana instance
(grafana can be found on localhost:3000 with the default credentials admin/admin).
When this option is set, nosqlbench will start graphite, prometheus, and grafana automatically on
your local docker, configure them to work together, and point nosqlbench to send metrics the system
automatically. It also imports a base dashboard for nosqlbench and configures grafana snapshot
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,
stored by default in logs/...
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.
--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.