| 1 |
Running Flent |
| 2 |
============= |
| 3 |
|
| 4 |
When run, flent must be supplied either (a) a test name and one or more host |
| 5 |
names to connect to, or (b) one or more input files containing data from |
| 6 |
previous runs to post-process. |
| 7 |
|
| 8 |
Test names, hostnames and input file names can all be specified as unqualified |
| 9 |
arguments, and flent will do its best to guess which is which. For each |
| 10 |
argument, if it is an existing file, it is assumed to be an input file, if it is |
| 11 |
the name of an existing test configuration it’s assumed to be a test name, and |
| 12 |
if neither of those are true, it is assumed to be a host name. The :option:`-i` |
| 13 |
and :option:`-H` switches can be used to explicitly specify the interpretation |
| 14 |
of an argument. |
| 15 |
|
| 16 |
Invocation |
| 17 |
---------- |
| 18 |
|
| 19 |
**flent** [*options*\ ] *<host\|test\|input file* ...\ *>* |
| 20 |
|
| 21 |
|
| 22 |
|
| 23 |
General options |
| 24 |
--------------- |
| 25 |
|
| 26 |
.. option:: -o OUTPUT, --output=OUTPUT |
| 27 |
|
| 28 |
File to write processed output to (default standard out). |
| 29 |
|
| 30 |
.. option:: -D DATA_DIR, --data-dir=DATA_DIR |
| 31 |
|
| 32 |
Directory to store data files in. Defaults to the current directory. |
| 33 |
|
| 34 |
.. option:: -i INPUT, --input=INPUT |
| 35 |
|
| 36 |
File to read input from (instead of running tests). Input files can also be |
| 37 |
specified as unqualified arguments without using the :option:`-i` switch. |
| 38 |
|
| 39 |
.. option:: -f FORMAT, --format=FORMAT |
| 40 |
|
| 41 |
Select output format (plot, csv, org\_table, stats). Default is no processed |
| 42 |
output (just writes the JSON data file). |
| 43 |
|
| 44 |
.. option:: -p PLOT, --plot=PLOT |
| 45 |
|
| 46 |
Select which plot to output for the given test (implies :option:`-f` plot). Use the |
| 47 |
:option:`--list-plots` option to see available plots. |
| 48 |
|
| 49 |
.. option:: -t TITLE, --title-extra=TITLE |
| 50 |
|
| 51 |
Text to add to plot title and data file name. |
| 52 |
|
| 53 |
.. option:: -n NOTE, --note=NOTE |
| 54 |
|
| 55 |
Add arbitrary text as a note to be stored in the JSON data file (under the |
| 56 |
*NOTE* key in the metadata object). |
| 57 |
|
| 58 |
.. option:: -r RCFILE, --rcfile=RCFILE |
| 59 |
|
| 60 |
Load configuration data from *RCFILE* (default *~/.flentrc*). See section |
| 61 |
below for information on the rc file format. |
| 62 |
|
| 63 |
.. option:: -x, --extended-metadata |
| 64 |
|
| 65 |
Collect extended metadata and store it with the data file. May include |
| 66 |
details of your machine you don’t want to distribute; see the section on the |
| 67 |
data format below. |
| 68 |
|
| 69 |
.. option:: --remote-metadata=HOSTNAME |
| 70 |
|
| 71 |
Collect extended metadata from a remote host. *HOSTNAME* is passed verbatim |
| 72 |
to ssh, so can include hosts specified in ~/.ssh/config. Note that gathering |
| 73 |
the data can take some time, since it involves executing several remote |
| 74 |
commands. This option can be specified multiple times and implies |
| 75 |
:option:`--extended-metadata`. |
| 76 |
|
| 77 |
.. option:: --gui |
| 78 |
|
| 79 |
Run the flent GUI. All other options are used as defaults in the GUI, but can |
| 80 |
be changed once it is running. The GUI can also be started by running the |
| 81 |
:command:`flent-gui` binary. For more information on the GUI, see the |
| 82 |
:doc:`gui` section. |
| 83 |
|
| 84 |
.. option:: --new-gui-instance |
| 85 |
|
| 86 |
Start a new GUI instance. Otherwise, flent will try to connect to an already |
| 87 |
running GUI instance and have that load any new data files specified as |
| 88 |
arguments. Implies :option:`--gui` when passed on the command line, but not when |
| 89 |
set in the rc file. Note that when multiple GUI instances are running, there |
| 90 |
is no guarantee as to which instance will get a subsequent open request (if |
| 91 |
run again without :option:`--new-gui-instance`). |
| 92 |
|
| 93 |
.. option:: --gui-no-defer |
| 94 |
|
| 95 |
Normally, the GUI defers redrawing plots until they are needed to avoid |
| 96 |
redrawing all open plots every time an option changes. This switch turns off |
| 97 |
that optimisation in favour of always redrawing everything straight away. |
| 98 |
This is useful when loading a bunch of plots from the command line and then |
| 99 |
wanting to flip through them without drawing delay. |
| 100 |
|
| 101 |
.. option:: -b BATCH_NAME, --batch-name=BATCH_NAME |
| 102 |
|
| 103 |
Run test batch BATCH\_NAME (must be specified in a batch file loaded by the |
| 104 |
:option:`--batch-file` option). Can be supplied multiple times. |
| 105 |
|
| 106 |
.. option:: -B BATCH_FILE, --batch-file=BATCH_FILE |
| 107 |
|
| 108 |
Load batch file BATCH_FILE. Can be specified multiple times, in which case |
| 109 |
the files will be combined (with identically-named sections being overridden |
| 110 |
by later files). See appropriate section below for an explanation of the |
| 111 |
batch file format. |
| 112 |
|
| 113 |
.. option:: --batch-override=key=value |
| 114 |
|
| 115 |
Override parameter ’key’ in the batch config and set it to ’value’. The key |
| 116 |
name will be case folded to lower case. Can be specified multiple times. |
| 117 |
|
| 118 |
.. option:: --batch-dry-run |
| 119 |
|
| 120 |
Dry batch run. Prints what would be done, but doesn’t actually run any tests. |
| 121 |
|
| 122 |
.. option:: --batch-verbose |
| 123 |
|
| 124 |
Be verbose during batch run: Print all commands executed. |
| 125 |
|
| 126 |
.. option:: --batch-no-shuffle |
| 127 |
|
| 128 |
Do not randomise the order of test runs within each batch. |
| 129 |
|
| 130 |
.. option:: --batch-repetitions=REPETITIONS |
| 131 |
|
| 132 |
Shorthand for :option:`--batch-override` ``'repetitions=REPETITIONS’``. |
| 133 |
|
| 134 |
.. option:: --batch-title=TITLE |
| 135 |
|
| 136 |
Shorthand for :option:`--batch-override` ``'batch_title=TITLE’``. |
| 137 |
|
| 138 |
.. option:: --batch-resume=DIR |
| 139 |
|
| 140 |
Try to resume a previously interrupted batch run. The argument is the |
| 141 |
top-level output directory from the previous run. |
| 142 |
|
| 143 |
This will attempt to find a data file in the resume directory and load the |
| 144 |
BATCH_TIME from the previous run from that and continue. The assumption is |
| 145 |
that the output directory and filenames are generated from the batch time, so |
| 146 |
that they will match with the previous run when the same time is used. Then, |
| 147 |
tests for which data files already exist will be skipped on this run. If the |
| 148 |
rest of the batch invocation is different from the one being resumed, results |
| 149 |
may not be what you want. |
| 150 |
|
| 151 |
There's a check to ensure that the generated output path is a subdirectory of |
| 152 |
the resume directory, and the whole run will be aborted if it isn't. |
| 153 |
|
| 154 |
Test configuration options |
| 155 |
-------------------------- |
| 156 |
|
| 157 |
These options affect the behaviour of the test being run and have no effect when |
| 158 |
parsing input files. |
| 159 |
|
| 160 |
.. option :: -H HOST, --host=HOST |
| 161 |
|
| 162 |
Host to connect to for tests. For tests that support it, multiple hosts can |
| 163 |
be specified by supplying this option multiple times. Hosts can also be |
| 164 |
specified as unqualified arguments; this parameter guarantees that the |
| 165 |
argument be interpreted as a host name (rather than being subject to |
| 166 |
auto-detection between input files, hostnames and test names). |
| 167 |
|
| 168 |
.. option:: --local-bind=IP |
| 169 |
|
| 170 |
Local hostname or IP address to bind to (for test tools that support this). |
| 171 |
Can be specified multiple times for tests that connect to more than one host; |
| 172 |
if it is, it must be specified as many times as there are hosts. |
| 173 |
|
| 174 |
.. option:: --remote-host=idx=HOSTNAME |
| 175 |
|
| 176 |
A remote hostname to connect to when starting a test. The idx is the runner |
| 177 |
index, which is assigned sequentially to each *runner* (and so it is *not* |
| 178 |
the same as the sequence of hostnames). Look for the 'IDX' key in SERIES_META |
| 179 |
for a test get the idx used here, but note that the idx assignment depends on |
| 180 |
the exact arguments to the test. |
| 181 |
|
| 182 |
This works by simply prepending 'ssh HOSTNAME' to the runner command, so it |
| 183 |
relies on the same binaries being in the same places on both machines, and |
| 184 |
won't work for all runners. |
| 185 |
|
| 186 |
This option can be specified multiple times to have multiple runners run on |
| 187 |
remote hosts. |
| 188 |
|
| 189 |
.. option:: -l LENGTH, --length=LENGTH |
| 190 |
|
| 191 |
Base test length (some tests may add some time to this). |
| 192 |
|
| 193 |
.. option:: -s STEP_SIZE, --step-size=STEP_SIZE |
| 194 |
|
| 195 |
Measurement data point step size. |
| 196 |
|
| 197 |
.. option:: -d DELAY, --delay=DELAY |
| 198 |
|
| 199 |
Number of seconds to delay parts of test (such as bandwidth loaders). |
| 200 |
|
| 201 |
.. option:: -4, --ipv4 |
| 202 |
|
| 203 |
Use IPv4 for tests (some tests may ignore this). |
| 204 |
|
| 205 |
.. option:: -6, --ipv6 |
| 206 |
|
| 207 |
Use IPv6 for tests (some tests may ignore this). |
| 208 |
|
| 209 |
.. option:: --socket-timeout=SOCKET_TIMEOUT |
| 210 |
|
| 211 |
Socket timeout (in seconds) used for UDP delay measurement, to prevent stalls |
| 212 |
on packet loss. Only enabled if the installed netperf version is detected to |
| 213 |
support this (requires SVN version of netperf). |
| 214 |
|
| 215 |
For the default value, see the output of flent :option:`-h`. The value of |
| 216 |
this parameter is an implicit upper bound on how long a round-trip time that |
| 217 |
can be measured. As such you may need to adjust it if you are experiencing |
| 218 |
latency above the default value. Set to 0 to disable. |
| 219 |
|
| 220 |
.. option:: --send-size=SEND_SIZE |
| 221 |
|
| 222 |
Send size (in bytes) used for TCP tests. Netperf uses the socket buffer size |
| 223 |
by default, which if too large can cause spikes in the throughput results. |
| 224 |
Lowering this value will increase CPU usage but also improves the fidelity |
| 225 |
of the throughput results without having to decrease the socket buffer size. |
| 226 |
|
| 227 |
Can be specified multiple times, with each value corresponding to a stream |
| 228 |
of a test. If only specified once, the same value will be applied to all |
| 229 |
flows. |
| 230 |
|
| 231 |
.. option:: --test-parameter=key=value |
| 232 |
|
| 233 |
Arbitrary test parameter in key=value format. Key will be case folded to |
| 234 |
lower case. The values are stored with the results metadata, and so can be |
| 235 |
used for storing arbitrary information relevant for a particular test run. |
| 236 |
|
| 237 |
In addition to serving as simple metadata, the test parameters can also |
| 238 |
affect the behaviour of some test configurations. See the :doc:`tests` |
| 239 |
section for information on these. |
| 240 |
|
| 241 |
This option can be specified multiple times to set multiple test parameters. |
| 242 |
|
| 243 |
.. option:: --swap-up-down |
| 244 |
|
| 245 |
Switch upstream and downstream directions for data transfer. This means that |
| 246 |
’upload’ will become ’download’ and vice versa. Works by exchanging netperf |
| 247 |
``TCP_MAERTS`` and ``TCP_STREAM`` parameters, so only works for tests that employ |
| 248 |
these as their data transfer, and only for the TCP streams. |
| 249 |
|
| 250 |
.. option:: --socket-stats |
| 251 |
|
| 252 |
Parse socket stats during test. This will capture and parse socket |
| 253 |
statistics for all TCP upload flows during a test, adding TCP cwnd and RTT |
| 254 |
values to the test data. Requires the 'ss' utility to be present on the |
| 255 |
system, and can fail if there are too many simultaneous upload flows; which |
| 256 |
is why this option is not enabled by default. |
| 257 |
|
| 258 |
.. option:: --marking-name |
| 259 |
|
| 260 |
Define a new symbolic name that can be used when specifying flow markings |
| 261 |
using the 'markings' test parameter. This can be used to make it easier to |
| 262 |
specify custom diffserv markings on flows by using symbolic names for each |
| 263 |
marking value instead of the hex codes. Values specified here will be used |
| 264 |
in addition to the common values (listed below), and cannot override the |
| 265 |
built-in names. Names will be case-folded when matching. |
| 266 |
|
| 267 |
The list of symbolic markings natively supported, along with their hex |
| 268 |
expansions, are:: |
| 269 |
|
| 270 |
AF11: 0x28 CS0: 0x00 |
| 271 |
AF12: 0x30 CS1: 0x20 |
| 272 |
AF13: 0x38 CS2: 0x40 |
| 273 |
AF21: 0x48 CS3: 0x60 |
| 274 |
AF22: 0x50 CS4: 0x80 |
| 275 |
AF23: 0x58 CS5: 0xa0 |
| 276 |
AF31: 0x68 CS6: 0xc0 |
| 277 |
AF32: 0x70 CS7: 0xe0 |
| 278 |
AF33: 0x78 EF: 0xb8 |
| 279 |
AF41: 0x88 |
| 280 |
AF42: 0x90 |
| 281 |
AF43: 0x98 |
| 282 |
|
| 283 |
Note that the hexadecimal values denote the value of the full ToS byte |
| 284 |
(including the two ECN bits), so they need to be right-shifted by two bits |
| 285 |
to get the corresponding diffserv code points. |
| 286 |
|
| 287 |
|
| 288 |
Plot configuration options |
| 289 |
-------------------------- |
| 290 |
|
| 291 |
These options are used to configure the appearance of plot output and only make |
| 292 |
sense combined with :option:`-f` *plot*. |
| 293 |
|
| 294 |
.. option:: --label-x=LABEL |
| 295 |
.. option:: --label-y=LABEL |
| 296 |
|
| 297 |
Override the figure axis labels. Can be specified twice, corresponding to |
| 298 |
figures with multiple axes. |
| 299 |
|
| 300 |
.. option:: -I, --invert-latency-y |
| 301 |
|
| 302 |
Invert latency data series axis (typically the Y-axis), making plots show |
| 303 |
’better' values upwards. |
| 304 |
|
| 305 |
.. option:: -z, --zero-y |
| 306 |
|
| 307 |
Always start Y axis of plot at zero, instead of autoscaling the axis. |
| 308 |
Autoscaling is still enabled for the upper bound. This also disables log |
| 309 |
scale if enabled. |
| 310 |
|
| 311 |
.. option:: --log-scale={log2,log10} |
| 312 |
|
| 313 |
Use the specified logarithmic scale on plots. |
| 314 |
|
| 315 |
.. option:: --norm-factor=FACTOR |
| 316 |
|
| 317 |
Data normalisation factor. Divide all data points by this value. Can be |
| 318 |
specified multiple times, in which case each value corresponds to a data |
| 319 |
series. |
| 320 |
|
| 321 |
.. option:: --bounds-x=BOUNDS |
| 322 |
.. option:: --bounds-y=BOUNDS |
| 323 |
|
| 324 |
Specify bounds of the plot axes. If specifying one number, that will become |
| 325 |
the upper bound. Specify two numbers separated by a comma to specify both |
| 326 |
upper and lower bounds. To specify just the lower bound, add a comma |
| 327 |
afterwards. Can be specified twice, corresponding to figures with multiple |
| 328 |
axes. |
| 329 |
|
| 330 |
.. option:: -S, --scale-mode |
| 331 |
|
| 332 |
Treat file names (except for the first one) passed as unqualified arguments |
| 333 |
as if passed as :option:`--scale-data` (default as if passed as |
| 334 |
:option:`--input`). |
| 335 |
|
| 336 |
.. option:: --concatenate |
| 337 |
|
| 338 |
Concatenate multiple result sets into one data series. This means that each |
| 339 |
data file will have its time axis shifted by the preceding series duration |
| 340 |
and appended to the first data set specified. Only works for data sets from |
| 341 |
the same test, obviously. |
| 342 |
|
| 343 |
.. option:: --absolute-time |
| 344 |
|
| 345 |
Plot data points with absolute UNIX time on the x-axis. This requires the |
| 346 |
absolute starting time for the test run to be stored in the data file, and so |
| 347 |
it won’t work with data files that predates this feature. |
| 348 |
|
| 349 |
.. option:: --subplot-combine |
| 350 |
|
| 351 |
When plotting multiple data series, plot each one on a separate subplot |
| 352 |
instead of combining them into one plot. This mode is not supported for all |
| 353 |
plot types, and only works when :option:`--scale-mode` is disabled. |
| 354 |
|
| 355 |
.. option:: --skip-missing-series |
| 356 |
|
| 357 |
Skip missing series entirely from bar plots, instead of leaving an empty |
| 358 |
space for it. |
| 359 |
|
| 360 |
.. option:: --no-print-n |
| 361 |
|
| 362 |
Do not print the number of data points on combined plots. When using plot |
| 363 |
types that combines results from several test runs, the number of data series |
| 364 |
in each combined data point is normally added after the series name, (n=X) |
| 365 |
for X data series. This option turns that off. |
| 366 |
|
| 367 |
.. option:: --no-annotation |
| 368 |
|
| 369 |
Exclude annotation with hostnames, time and test length from plots. |
| 370 |
|
| 371 |
.. option:: --figure-note=NOTE, --fig-note=NOTE |
| 372 |
|
| 373 |
Add a note (arbitrary text) to the bottom-left of the figure. |
| 374 |
|
| 375 |
.. option:: --no-title |
| 376 |
|
| 377 |
Exclude title from plots. |
| 378 |
|
| 379 |
.. option:: --override-title=TITLE |
| 380 |
|
| 381 |
Override plot title with this string. Completely discards the configured |
| 382 |
title (from the test configuration), as well as the title stored in the data |
| 383 |
set, and replaces it with the value supplied here. This is useful to override |
| 384 |
the plot title *at the time of plotting*, for instance to add a title to an |
| 385 |
aggregate plot from several data series. When this parameter is specified, |
| 386 |
:option:`--no-title` has no effect. |
| 387 |
|
| 388 |
.. option:: --no-labels |
| 389 |
|
| 390 |
Hides tick labels from box and bar plots. |
| 391 |
|
| 392 |
.. option:: --no-markers |
| 393 |
|
| 394 |
Don’t use line markers to differentiate data series on plots. |
| 395 |
|
| 396 |
.. option:: --no-legend |
| 397 |
|
| 398 |
Exclude legend from plots. |
| 399 |
|
| 400 |
.. option:: --horizontal-legend |
| 401 |
|
| 402 |
Place a horizontal legend below the plot instead of a vertical one next to |
| 403 |
it. Doesn't always work well if there are too many items in the legend. |
| 404 |
|
| 405 |
.. option:: --legend-title=LEGEND_TITLE |
| 406 |
|
| 407 |
Override legend title on plot. |
| 408 |
|
| 409 |
.. option:: --legend-placement=LEGEND_PLACEMENT |
| 410 |
|
| 411 |
Control legend placement. Enabling this option will place the legend inside |
| 412 |
the plot at the specified location. Can be one of 'best', 'upper right', |
| 413 |
'upper left', 'lower left', 'lower right', 'right', 'center left', 'center |
| 414 |
right', 'lower center', 'upper center' or 'center'. |
| 415 |
|
| 416 |
.. option:: --legend-columns=LEGEND_COLUMNS |
| 417 |
Set the number of columns in the legend. |
| 418 |
|
| 419 |
.. option:: --reverse-legend |
| 420 |
|
| 421 |
Reverse the order of items in the legend. This can be useful to make the |
| 422 |
legend order match the data series in some cases. |
| 423 |
|
| 424 |
.. option:: --filter-legend |
| 425 |
|
| 426 |
Filter legend labels by removing the longest common substring from all |
| 427 |
entries. This is not particularly smart, so use with care. |
| 428 |
|
| 429 |
.. option:: --replace-legend=src=dest |
| 430 |
|
| 431 |
Replace 'src' with 'dst' in legends. Can be specified multiple times. |
| 432 |
|
| 433 |
.. option:: --filter-regexp=REGEXP |
| 434 |
|
| 435 |
Filter the plot legend by the supplied regular expression (removing any text |
| 436 |
from the legend that matches the expression). Can be specified multiple |
| 437 |
times, in which case the filters will be applied in the order specified. Note |
| 438 |
that for combining several plot results, the regular expression is also |
| 439 |
applied before the grouping logic, meaning that a too wide filter can mess up |
| 440 |
the grouping. |
| 441 |
|
| 442 |
.. option:: --override-label=LABEL |
| 443 |
|
| 444 |
Override dataset label. Can be specified multiple times when multiple |
| 445 |
datasets are being plotted, in which case the order of labels corresponds to |
| 446 |
the order of datasets. |
| 447 |
|
| 448 |
Like :option:`--override-title`, this is applied *at the time of plotting*. |
| 449 |
|
| 450 |
.. option:: --filter-series=SERIES |
| 451 |
|
| 452 |
Filter out specified series from plot. Can be specified multiple times. |
| 453 |
|
| 454 |
.. option:: --split-group=LABEL |
| 455 |
|
| 456 |
Split data sets into groups when creating box plots. Specify this option |
| 457 |
multiple times to define the new groups; the value of each option is the |
| 458 |
group name. |
| 459 |
|
| 460 |
Say you're plotting nine datasets which are really testing two variables with |
| 461 |
three values each. In this case, it can be useful to have the box plot of the |
| 462 |
results be split into three parts (corresponding to the values of one |
| 463 |
variable) with each three boxes in each of them (corresponding to the values |
| 464 |
of the second variable). This option makes this possible; simply specify it |
| 465 |
three times with the labels to be used for the three groups. |
| 466 |
|
| 467 |
A constraint on this option is that the number of datasets being plotted must |
| 468 |
be divisible by the number of groups. |
| 469 |
|
| 470 |
.. option:: --colours=COLOURS |
| 471 |
|
| 472 |
Comma-separated list of colours to be used for the plot colour cycle. Can be |
| 473 |
specified in any format understood by matplotlib (including HTML hex values |
| 474 |
prefixed with a #). |
| 475 |
|
| 476 |
Yes, this option uses British spelling. No, American spelling is not |
| 477 |
supported. |
| 478 |
|
| 479 |
.. option:: --override-colour-mode=MODE |
| 480 |
|
| 481 |
Override colour_mode attribute. This changes the way colours are |
| 482 |
assigned to bar plots. The default is 'groups' which assigns a separate |
| 483 |
colour to each group of data series. The alternative is 'series' which |
| 484 |
assigns a separate colour to each series, repeating them for each data |
| 485 |
group. |
| 486 |
|
| 487 |
.. option:: --override-group-by=GROUP |
| 488 |
|
| 489 |
Override the ``group_by`` setting for combination plots. This is useful to, |
| 490 |
for instance, switch to splitting up combined data sets by batch run instead |
| 491 |
of by file name. |
| 492 |
|
| 493 |
.. option:: --combine-save-dir=DIRNAME |
| 494 |
|
| 495 |
When doing a combination plot save the intermediate data to ``DIRNAME``. This |
| 496 |
can then be used for subsequent plotting to avoid having to load all the |
| 497 |
source data files again on each plot. |
| 498 |
|
| 499 |
.. option:: --figure-width=FIG_WIDTH |
| 500 |
|
| 501 |
Figure width in inches. Used when saving plots to file and for default size |
| 502 |
of the interactive plot window. |
| 503 |
|
| 504 |
.. option:: --figure-height=FIG_HEIGHT |
| 505 |
|
| 506 |
Figure height in inches. Used when saving plots to file and for default size |
| 507 |
of the interactive plot window. |
| 508 |
|
| 509 |
.. option:: --figure-dpi=FIG_DPI |
| 510 |
|
| 511 |
Figure DPI. Used when saving plots to raster format files. |
| 512 |
|
| 513 |
.. option:: --fallback-layout |
| 514 |
|
| 515 |
Use the fallback layout engine (tight_layout built in to matplotlib). Use |
| 516 |
this if text is cut off on saved figures. The downside to the fallback engine |
| 517 |
is that the size of the figure (as specified by :option:`--figure-width` and |
| 518 |
:option:`--figure-height`) is no longer kept constant.) |
| 519 |
|
| 520 |
.. option:: --no-matplotlibrc |
| 521 |
|
| 522 |
Don’t load included matplotlibrc values. Use this if autodetection of custom |
| 523 |
matplotlibrc fails and flent is inadvertently overriding rc values. |
| 524 |
|
| 525 |
.. option:: --no-hover-highlight |
| 526 |
|
| 527 |
Don't highlight data series on hover in interactive plot views. Use this if |
| 528 |
redrawing is too slow, or the highlighting is undesired for other reasons. |
| 529 |
|
| 530 |
.. option:: --scale-data=SCALE_DATA |
| 531 |
|
| 532 |
Additional data files to consider when scaling the plot axes (for plotting |
| 533 |
several plots with identical axes). Note, this displays only the first data |
| 534 |
set, but with axis scaling taking into account the additional data sets. Can |
| 535 |
be supplied multiple times; see also :option:`--scale-mode`. |
| 536 |
|
| 537 |
|
| 538 |
Test tool-related options |
| 539 |
------------------------- |
| 540 |
.. option:: --control-host=HOST |
| 541 |
|
| 542 |
Hostname for the test control connection (for test tools that support this). |
| 543 |
Default: First hostname of test target. |
| 544 |
|
| 545 |
When running tests that uses D-ITG as a test tool (such as the voip-\* |
| 546 |
tests), this switch controls where flent will look for the D-ITG control |
| 547 |
server (see section below on running tests with D-ITG). For Netperf-based |
| 548 |
tests, this option is passed to Netperf to control where to point the control |
| 549 |
connection. This is useful to, for instance, to run the control server |
| 550 |
communication over a separate control network so as to not interfere with |
| 551 |
test traffic. |
| 552 |
|
| 553 |
There is also a per-flow setting for this for tests that connect to multiple |
| 554 |
hosts; see the `control_hosts` test parameter in :doc:`tests`. If both are |
| 555 |
set, the per-flow setting takes precedence for those tests that use it. |
| 556 |
|
| 557 |
.. option:: --control-local-bind=IP |
| 558 |
|
| 559 |
Local hostname or IP to bind control connection to (for test tools that |
| 560 |
support it; currently netperf). If not supplied, the value for |
| 561 |
:option:`--local-bind` will be used. Note that if this value is passed but |
| 562 |
:option:`--local-bind` is *not*, netperf will use the value specified here to |
| 563 |
bind the data connections to as well. |
| 564 |
|
| 565 |
.. option:: --netperf-control-port=PORT |
| 566 |
|
| 567 |
Port for Netperf control server. Default: 12865. |
| 568 |
|
| 569 |
.. option:: --ditg-control-port=PORT |
| 570 |
|
| 571 |
Port for D-ITG control server. Default: 8000. |
| 572 |
|
| 573 |
.. option:: --ditg-control-secret=SECRET |
| 574 |
|
| 575 |
Secret for D-ITG control server authentication. Default: ’’. |
| 576 |
|
| 577 |
.. option:: --http-getter-urllist=FILENAME |
| 578 |
|
| 579 |
When running HTTP tests, the http-getter tool is used to fetch URLs (see |
| 580 |
https://github.com/tohojo/http-getter). This option specifies the filename |
| 581 |
containing the list of HTTP URLs to get. Can also be a URL, which will then |
| 582 |
be downloaded as part of each test iteration. If not specified, this is set |
| 583 |
to http://<hostname>/filelist.txt where <hostname> is the first test |
| 584 |
hostname. |
| 585 |
|
| 586 |
.. option:: --http-getter-dns-servers=DNS_SERVERS |
| 587 |
|
| 588 |
DNS servers to use for http-getter lookups. Format is |
| 589 |
host[:port][,host[:port]]... This option will only work if libcurl supports |
| 590 |
it (needs to be built with the ares resolver). Default is none (use the |
| 591 |
system resolver). |
| 592 |
|
| 593 |
.. option:: --http-getter-timeout=MILLISECONDS |
| 594 |
|
| 595 |
Timeout for HTTP connections. Default is to use the test length. |
| 596 |
|
| 597 |
.. option:: --http-getter-workers=NUMBER |
| 598 |
|
| 599 |
Number of workers to use for getting HTTP urls. Default is 4. |
| 600 |
|
| 601 |
.. option:: --irtt-sampling-interval=MILLISECONDS |
| 602 |
|
| 603 |
Override the sampling interval passed to irtt, in milliseconds. Can be used |
| 604 |
to run irtt with a higher sampling frequency than the rest of the test. If |
| 605 |
set, this will override the sampling interval for all instances of irtt used |
| 606 |
in the test. |
| 607 |
|
| 608 |
Misc and debugging options: |
| 609 |
--------------------------- |
| 610 |
|
| 611 |
.. option:: -L LOG_FILE, --log-file=LOG_FILE |
| 612 |
|
| 613 |
Write debug log (test program output) to log file. |
| 614 |
|
| 615 |
.. option:: --list-tests |
| 616 |
|
| 617 |
List available tests and exit. |
| 618 |
|
| 619 |
.. option:: --list-plots |
| 620 |
|
| 621 |
List available plots for selected test and exit. |
| 622 |
|
| 623 |
.. option:: -V, --version |
| 624 |
|
| 625 |
Show Flent version information and exit. |
| 626 |
|
| 627 |
.. option:: -v, --verbose |
| 628 |
|
| 629 |
Enable verbose logging to console. |
| 630 |
|
| 631 |
.. option:: -q, --quiet |
| 632 |
|
| 633 |
Disable normal logging to console (and only log warnings and errors). |
| 634 |
|
| 635 |
.. option:: --debug-error |
| 636 |
|
| 637 |
Print full exception backtraces to console. |
| 638 |
|
| 639 |
.. option:: -h, --help |
| 640 |
|
| 641 |
Show usage help message and exit. |
| 642 |
|
| 643 |
|
| 644 |
Signals |
| 645 |
------- |
| 646 |
|
| 647 |
Flent will abort what it is currently doing on receiving a **SIGINT** -- this |
| 648 |
includes killing all runners, cleaning up temporary files and shutting down as |
| 649 |
gracefully as possible. Runners are killed with **SIGTERM** in this mode, and |
| 650 |
their output is discarded. If a batch run is in progress, the current test will |
| 651 |
be interrupted in this way, and the rest of the batch run is aborted. Previously |
| 652 |
completed tests and their results are not aborted. Post-commands marked as |
| 653 |
’essential’ will be run after the test is interrupted. Additionally, flent |
| 654 |
converts **SIGTERM** into **SIGINT** internally and reacts accordingly. |
| 655 |
|
| 656 |
Upon receiving a **SIGUSR1**, flent will try to gracefully abort the test it is |
| 657 |
currently running, and parse the output of the runners to the extent that any |
| 658 |
such output exists. That is, each runner will be killed by a **SIGINT**, which |
| 659 |
will cause a graceful shutdown for at least ping and netperf (although netperf |
| 660 |
running in *TCP_MAERTS* mode will bug out when interrupted like this, so |
| 661 |
end-of-tests statistics will be missing). Flent will only react once to a |
| 662 |
**SIGUSR1**, sending exactly one **SIGINT** to the active runners, then wait for |
| 663 |
them to exit. This may take several seconds in the case of netperf. If the |
| 664 |
runners for some reason fail to exit, flent will be stuck and will need to be |
| 665 |
killed with **SIGINT**. If running in batch mode, **SIGUSR1** will only affect |
| 666 |
the currently running test; subsequent tests will still be run. |