Configuration¶
Command Line Options¶
Locust is configured mainly through command line arguments.
$ locust --help
Usage: locust [OPTIONS] [UserClass ...]
Common options:
-h, --help show this help message and exit
-f LOCUSTFILE, --locustfile LOCUSTFILE
Python module to import, e.g. '../other_test.py'.
Either a .py file, multiple comma-separated .py files
or a package directory. Defaults to 'locustfile'.
--config CONFIG Config file path
-H HOST, --host HOST Host to load test in the following format:
http://10.21.32.33
-u NUM_USERS, --users NUM_USERS
Peak number of concurrent Locust users. Primarily used
together with --headless or --autostart. Can be
changed during a test by keyboard inputs w, W (spawn
1, 10 users) and s, S (stop 1, 10 users)
-r SPAWN_RATE, --spawn-rate SPAWN_RATE
Rate to spawn users at (users per second). Primarily
used together with --headless or --autostart
-t RUN_TIME, --run-time RUN_TIME
Stop after the specified amount of time, e.g. (300s,
20m, 3h, 1h30m, etc.). Only used together with
--headless or --autostart. Defaults to run forever.
-l, --list Show list of possible User classes and exit
Web UI options:
--web-host WEB_HOST Host to bind the web interface to. Defaults to '*'
(all interfaces)
--web-port WEB_PORT, -P WEB_PORT
Port on which to run web host
--headless Disable the web interface, and start the test
immediately. Use -u and -t to control user count and
run time
--autostart Starts the test immediately (like --headless, but
without disabling the web UI)
--autoquit AUTOQUIT Quits Locust entirely, X seconds after the run is
finished. Only used together with --autostart. The
default is to keep Locust running until you shut it
down using CTRL+C
--web-auth WEB_AUTH Turn on Basic Auth for the web interface. Should be
supplied in the following format: username:password
--tls-cert TLS_CERT Optional path to TLS certificate to use to serve over
HTTPS
--tls-key TLS_KEY Optional path to TLS private key to use to serve over
HTTPS
--class-picker Enable select boxes in the web interface to choose
from all available User classes and Shape classes
Master options:
Options for running a Locust Master node when running Locust distributed. A Master node need Worker nodes that connect to it before it can run load tests.
--master Set locust to run in distributed mode with this
process as master
--master-bind-host MASTER_BIND_HOST
Interfaces (hostname, ip) that locust master should
bind to. Only used when running with --master.
Defaults to * (all available interfaces).
--master-bind-port MASTER_BIND_PORT
Port that locust master should bind to. Only used when
running with --master. Defaults to 5557.
--expect-workers EXPECT_WORKERS
How many workers master should expect to connect
before starting the test (only when
--headless/autostart is used).
--expect-workers-max-wait EXPECT_WORKERS_MAX_WAIT
How long should the master wait for workers to connect
before giving up. Defaults to wait forever
Worker options:
Options for running a Locust Worker node when running Locust distributed.
Only the LOCUSTFILE (-f option) needs to be specified when starting a Worker, since other options such as -u, -r, -t are specified on the Master node.
--worker Set locust to run in distributed mode with this
process as worker
--master-host MASTER_NODE_HOST
Host or IP address of locust master for distributed
load testing. Only used when running with --worker.
Defaults to 127.0.0.1.
--master-port MASTER_NODE_PORT
The port to connect to that is used by the locust
master for distributed load testing. Only used when
running with --worker. Defaults to 5557.
Tag options:
Locust tasks can be tagged using the @tag decorator. These options let specify which tasks to include or exclude during a test.
-T [TAG [TAG ...]], --tags [TAG [TAG ...]]
List of tags to include in the test, so only tasks
with any matching tags will be executed
-E [TAG [TAG ...]], --exclude-tags [TAG [TAG ...]]
List of tags to exclude from the test, so only tasks
with no matching tags will be executed
Request statistics options:
--csv CSV_PREFIX Store current request stats to files in CSV format.
Setting this option will generate three files:
[CSV_PREFIX]_stats.csv, [CSV_PREFIX]_stats_history.csv
and [CSV_PREFIX]_failures.csv
--csv-full-history Store each stats entry in CSV format to
_stats_history.csv file. You must also specify the '--
csv' argument to enable this.
--print-stats Enable periodic printing of request stats in UI runs
--only-summary Disable periodic printing of request stats during
--headless run
--reset-stats Reset statistics once spawning has been completed.
Should be set on both master and workers when running
in distributed mode
--html HTML_FILE Store HTML report to file path specified
--json Prints the final stats in JSON format to stdout.
Useful for parsing the results in other
programs/scripts. Use together with --headless and
--skip-log for an output only with the json data.
Logging options:
--skip-log-setup Disable Locust's logging setup. Instead, the
configuration is provided by the Locust test or Python
defaults.
--loglevel LOGLEVEL, -L LOGLEVEL
Choose between DEBUG/INFO/WARNING/ERROR/CRITICAL.
Default is INFO.
--logfile LOGFILE Path to log file. If not set, log will go to stderr
Other options:
--show-task-ratio Print table of the User classes' task execution ratio.
Use this with non-zero --user option if some classes
define non-zero fixed_count attribute.
--show-task-ratio-json
Print json data of the User classes' task execution
ratio. Use this with non-zero --user option if some
classes define non-zero fixed_count attribute.
--version, -V Show program's version number and exit
--exit-code-on-error EXIT_CODE_ON_ERROR
Sets the process exit code to use when a test result
contain any failure or error
-s STOP_TIMEOUT, --stop-timeout STOP_TIMEOUT
Number of seconds to wait for a simulated user to
complete any executing task before exiting. Default is
to terminate immediately. This parameter only needs to
be specified for the master process when running
Locust distributed.
--equal-weights Use equally distributed task weights, overriding the
weights specified in the locustfile.
--enable-rebalancing Allow to automatically rebalance users if new workers
are added or removed during a test run.
User classes:
UserClass Optionally specify which User classes that should be
used (available User classes can be listed with -l or
--list)
Environment Variables¶
Options can also be set through through environment variables. They are typically the same as the command line argument but capitalized and prefixed with LOCUST_:
On Linux/macOS:
$ LOCUST_LOCUSTFILE=custom_locustfile.py locust
On Windows:
> set LOCUST_LOCUSTFILE=custom_locustfile.py
> locust
Configuration File¶
Options can also be set in a configuration file in the config file format.
Locust will look for ~/.locust.conf and ./locust.conf by default, and you can specify an
additional file using the --config flag.
Example:
# master.conf in current directory
locustfile = locust_files/my_locust_file.py
headless = true
master = true
expect-workers = 5
host = http://target-system
users = 100
spawn-rate = 10
run-time = 10m
$ locust --config=master.conf
Note
Configuration values are read (overridden) in the following order:
~/locust.conf -> ./locust.conf -> (file specified using --conf) -> env vars -> cmd args
All available configuration options¶
Here’s a table of all the available configuration options, and their corresponding Environment and config file keys:
Command line |
Environment |
Config file |
Description |
|
|
|
Python module to import, e.g. ‘../other_test.py’. Either a .py file, multiple comma-separated .py files or a package directory. Defaults to ‘locustfile’. |
|
|
|
Host to load test in the following format: http://10.21.32.33 |
|
|
|
Peak number of concurrent Locust users. Primarily used together with –headless or –autostart. Can be changed during a test by keyboard inputs w, W (spawn 1, 10 users) and s, S (stop 1, 10 users) |
|
|
|
Rate to spawn users at (users per second). Primarily used together with –headless or –autostart |
|
|
|
Stop after the specified amount of time, e.g. (300s, 20m, 3h, 1h30m, etc.). Only used together with –headless or –autostart. Defaults to run forever. |
|
|
|
Host to bind the web interface to. Defaults to ‘*’ (all interfaces) |
|
|
|
Port on which to run web host |
|
|
|
Disable the web interface, and start the test immediately. Use -u and -t to control user count and run time |
|
|
|
Starts the test immediately (like –headless, but without disabling the web UI) |
|
|
|
Quits Locust entirely, X seconds after the run is finished. Only used together with –autostart. The default is to keep Locust running until you shut it down using CTRL+C |
|
|
|
Turn on Basic Auth for the web interface. Should be supplied in the following format: username:password |
|
|
|
Optional path to TLS certificate to use to serve over HTTPS |
|
|
|
Optional path to TLS private key to use to serve over HTTPS |
|
|
|
Enable select boxes in the web interface to choose from all available User classes and Shape classes |
|
|
|
Set locust to run in distributed mode with this process as master |
|
|
|
Interfaces (hostname, ip) that locust master should bind to. Only used when running with –master. Defaults to * (all available interfaces). |
|
|
|
Port that locust master should bind to. Only used when running with –master. Defaults to 5557. |
|
|
|
How many workers master should expect to connect before starting the test (only when –headless/autostart is used). |
|
|
|
How long should the master wait for workers to connect before giving up. Defaults to wait forever |
|
|
|
Set locust to run in distributed mode with this process as worker |
|
|
|
Host or IP address of locust master for distributed load testing. Only used when running with –worker. Defaults to 127.0.0.1. |
|
|
|
The port to connect to that is used by the locust master for distributed load testing. Only used when running with –worker. Defaults to 5557. |
|
|
|
List of tags to include in the test, so only tasks with any matching tags will be executed |
|
|
|
List of tags to exclude from the test, so only tasks with no matching tags will be executed |
|
|
|
Store current request stats to files in CSV format. Setting this option will generate three files: [CSV_PREFIX]_stats.csv, [CSV_PREFIX]_stats_history.csv and [CSV_PREFIX]_failures.csv |
|
|
|
Store each stats entry in CSV format to _stats_history.csv file. You must also specify the ‘–csv’ argument to enable this. |
|
|
|
Enable periodic printing of request stats in UI runs |
|
|
|
Disable periodic printing of request stats during –headless run |
|
|
|
Reset statistics once spawning has been completed. Should be set on both master and workers when running in distributed mode |
|
|
|
Store HTML report to file path specified |
|
|
|
Disable Locust’s logging setup. Instead, the configuration is provided by the Locust test or Python defaults. |
|
|
|
Choose between DEBUG/INFO/WARNING/ERROR/CRITICAL. Default is INFO. |
|
|
|
Path to log file. If not set, log will go to stderr |
|
|
|
Sets the process exit code to use when a test result contain any failure or error |
|
|
|
Number of seconds to wait for a simulated user to complete any executing task before exiting. Default is to terminate immediately. This parameter only needs to be specified for the master process when running Locust distributed. |
Running without the web UI¶
Using multiple Locustfiles at once¶
The -f/--locustfile option accepts a single directory of locustfiles as an option. Locust will recursively
search the directory for *.py files, ignoring files named locust.py or those that start with “_”.
Example:
With the following file structure:
├── locustfiles/
│ ├── locustfile1.py
│ ├── locustfile2.py
│ └── more_files/
│ ├── locustfile3.py
│ ├── locust.py
│ ├── _ignoreme.py
$ locust -f locustfiles
Locust will use locustfile1.py, locustfile2.py & more_files/locustfile3.py
Additionally, -f/--locustfile accepts multiple, comma-separated locustfiles.
Example:
$ locust -f locustfiles/locustfile1.py,locustfiles/locustfile2.py,locustfiles/more_files/locustfile3.py
Locust will use locustfile1.py, locustfile2.py & more_files/locustfile3.py
Running Locust with User class UI picker¶
You can select which Shape class and which User classes to run in the WebUI when running locust with the --class-picker flag.
No selection uses all of the available User classes.
Example:
With the following file structure:
├── src/
│ ├── some_file.py
├── locustfiles/
│ ├── locustfile1.py
│ ├── locustfile2.py
│ └── more_files/
│ ├── locustfile3.py
│ ├── locust.py
│ ├── _ignoreme.py
│ └── shape_classes/
│ ├── DoubleWaveShape.py
│ ├── StagesShape.py
$ locust -f locustfiles --class-picker
The Web UI will display:
Custom arguments¶
See Custom arguments
Customization of statistics settings¶
Default configuration for Locust statistics is set in constants of stats.py file. It can be tuned to specific requirements by overriding these values. To do this, import locust.stats module and override required settings:
import locust.stats
locust.stats.CONSOLE_STATS_INTERVAL_SEC = 15
It can be done directly in Locust file or extracted to separate file for common usage by all Locust files.
The list of statistics parameters that can be modified is:
Parameter name |
Purpose |
STATS_NAME_WIDTH |
Width of column for request name in console output |
STATS_TYPE_WIDTH |
Width of column for request type in console output |
CSV_STATS_INTERVAL_SEC |
Interval for how frequently the CSV file is written if this option is configured |
CONSOLE_STATS_INTERVAL_SEC |
Interval for how frequently results are written to console |
CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW |
Window size/resolution - in seconds - when calculating the current response time percentile |
PERCENTILES_TO_REPORT |
The list of response time percentiles to be calculated & reported |
PERCENTILES_TO_CHART |
The list of response time percentiles for response time chart |