Configuration¶
Command Line Options¶
The most straight forward way to Configure how Locust is run is through command line arguments.
$ locust --help
Environment Variables¶
Most of the options that can be set through command line arguments can also be set through environment variables. Example:
$ LOCUST_LOCUSTFILE=custom_locustfile.py locust
Configuration File¶
Any of the options that can be set through command line arguments can also be set by 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 file to import, e.g. ‘../other.py’. Default: locustfile |
|
|
|
Host to load test in the following format: http://10.21.32.33 |
|
|
|
Number of concurrent Locust users. Primarily used together with –headless. Can be changed during a test by inputs w, W(spawn 1, 10 users) and s, S(stop 1, 10 users) |
|
|
|
The rate per second in which users are spawned. Primarily used together with –headless |
|
|
|
==SUPPRESS== |
|
|
|
Stop after the specified amount of time, e.g. (300s, 20m, 3h, 1h30m, etc.). Only used together with –headless. 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 instead start the load test immediately. Requires -u and -t to be specified. |
|
|
|
==SUPPRESS== |
|
|
|
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 |
|
|
|
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 used). |
|
|
|
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. |
|
|
|
Print stats in the console |
|
|
|
Only print the summary stats |
|
|
|
Reset statistics once spawning has been completed. Should be set on both master and workers when running in distributed mode |
|
|
|
Store HTML report file |
|
|
|
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 stdout/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. |
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 |