Locust使用手册--Locust配置

最新推荐文章于 2025-05-20 14:02:17 发布

最新推荐文章于 2025-05-20 14:02:17 发布 · 置顶 · 913 阅读

3 ·

CC 4.0 BY-SA版权

原文链接：https://docs.locust.io/en/latest/configuration.html

文章标签：

#python #linux #git #压力测试

性能测试同时被 3 个专栏收录

9 篇文章

订阅专栏

python

9 篇文章

订阅专栏

Locust

6 篇文章

订阅专栏

本文介绍Locust性能测试工具的配置方法，包括命令行参数、环境变量及配置文件等配置方式。涵盖如何设置并发用户数、生成速率、运行时间等关键参数，并解释了在无WebUI环境下运行及多Locustfile文件的使用方法。

摘要生成于 C知道，由 DeepSeek-R1 满血版支持，前往体验 >

文章目录

配置

配置

命令行参数

Locust主要通过命令行参数进行配置

$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 (without disabling the web
                        UI). Use -u and -t to control user count and run time
  --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         Print stats in the console
  --only-summary        Only print the summary stats
  --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

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)

环境变量

也可以通过环境变量来设置选项。他们和命令行参数相同，但需要用大写且以LOCUST_为前缀。
在Linux/macOS系统：

$LOCUST_LOCUSTFILE=custom_locustfile.py locust

在Windows系统：

> set LOCUST_LOCUSTFILE=custom_locustfile.py
> locust

配置文件

也可以按照配置文件中的配置文件格式来设置选项。
Locust会在默认情况下查找~/.locust.conf和./locust.conf，你可以使用--config标志来指定一个额外的文件。
例如：

# 当前目录下的master.conf
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

批注
按以下的顺序读取(覆盖)配置值：
~/locust.conf -> ./locust.conf -> (file specified using --conf) -> env vars -> cmd args

所有可用的配置选项

下表记录了所有可用配置选项以及它们对应的环境和配置文件键值信息：

命令行	环境	配置文件	描述
`-f`,`--locustfile`	`LOCUST_LOCUSTFILE`	`locustfile`	导入python模块，例如：‘`../other_test.py`’。一个`.py`文件、多个逗号分隔的`.py`文件或包目录。默认是’`locustfile`’
`-H`,`--host`	LOCUST_HOST	host	加载测试时的主机格式为: `http://10.21.32.33`
`-u`,`--users`	`LOCUST_USERS`	`users`	Locust高峰并发用户数。主要和`-headless`或`-autostart`一起使用。在测试过程中可以通过键盘`w`,`W`(生成1,10个用户)和`s`,`S`(停止1,10个用户)进行修改用户数
`-r`,`--spawn-rate`	`LOCUST_SPAWN_RATE`	`spawn-rate`	以(每秒用户数)生成用户的速率。主要和`-headless`或`-autostart`一起使用
`-t`,`--run-time`	`LOCUST_RUN_TIME`	`run-time`	在指定的时间值后停止运行。例如(300s,20m,3h,1h30m等)。只能和`-headless`或`-autostart`一起使用。默认是一直运行
`--web-host`	`LOCUST_WEB_HOST`	`web-host`	绑定web界面的主机。默认为’*'(所有接口)
`--web-port`,`-P`	`LOCUST_WEB_PORT`	`web-port`	指定运行web主机的端口
`--headless`	`LOCUST_HEADLESS`	`headless`	禁用web界面，立即启动测试。使用`-u`和`-t`来控制用户数和运行时间
`--autostart`	`LOCUST_AUTOSTART`	`autostart`	立即启动测试(和`--headless`一样，但不禁用web UI界面)
`--autoquit`	`LOCUST_AUTOQUIT`	`autoquit`	在运行结束后X秒，完全退出Locust。只能和`-autostart`一起使用。默认是保持Locust运行直至按下`CTRL+C`才退出
`--web-auth`	`LOCUST_WEB_AUTH`	`web-auth`	启用web界面的基本身份验证。应按以下格式提供:用户名:密码
`--tls-cert`	`LOCUST_TLS_CERT`	`tls-cert`	用于HTTPS提供服务的TLS证书的可选路径
`--tls-key`	`LOCUST_TLS_KEY`	`tls-key`	用于HTTPS提供服务的TLS私钥的可选路径
`--class-picker`	`LOCUST_USERCLASS_PICKER`	`class-picker`	启用web界面中的选择框，从所有可用的用户类和形态类中进行选择
`--master`	`LOCUST_MODE_MASTER`	`master`	将locust设置为以分布式模式运行，并将此进程作为master(主服务器)
`--master-bind-host`	`LOCUST_MASTER_BIND_HOST`	`master-bind-host`	locust master(主服务器)绑定的接口(主机名，ip)。仅在使用`-master`运行时使用。默认为*(所有可用的接口)
`--master-bind-port`	`LOCUST_MASTER_BIND_PORT`	`master-bind-port`	locust master(主服务器)绑定的端口，仅在使用`-master`运行时使用。默认是`5557`
`--expect-workers`	`LOCUST_EXPECT_WORKERS`	`expect-workers`	在开始测试之前需要连接多少worker主机(辅助服务器)(仅当`-headless/autostart`被使用时)
`--expect-workers-max-wait`	`LOCUST_EXPECT_WORKERS_MAX_WAIT`	`expect-workers-max-wait`	主进程在等待worker(辅助服务器)主机连接多久后才可放弃。默认是一直等待
`--worker`	`LOCUST_MODE_WORKER`	`worker`	将locust设置为以分布式模式运行，并将此进程设置为worker(辅助服务器)
`--master-host`	`LOCUST_MASTER_NODE_HOST`	`master-host`	用于分布式负载测试的locust master(主服务器)的主机或IP地址。仅在使用-worker运行时使用。默认为127.0.0.1
`--master-port`	`LOCUST_MASTER_NODE_PORT`	`master-port`	在分布式测试时locust主服务器的连接端口，仅在使用`-worker`运行时使用。默认是`5557`
`-T`,`--tags`	`LOCUST_TAGS`	`tags`	从测试用例中得到包含标记的列表，以便只执行具有任何匹配标记的任务
`-E`,`--exclude-tags`	`LOCUST_EXCLUDE_TAGS`	`exclude-tags`	从测试用例中排除标记的列表，因此只执行不匹配标记的任务
`--csv`	`LOCUST_CSV`	`csv`	将当前请求统计数据以CSV格式存储到文件中。设置这个参数将会得到三个文件:`[CSV_PREFIX]_stats.csv`,`[CSV_PREFIX]_stats_history.csv`和`[CSV_PREFIX]_failures.csv`
`--csv-full-history`	`LOCUST_CSV_FULL_HISTORY`	`csv-full-history`	将每个统计的条目以CSV格式存储到`_stats_history.csv`文件中。必须指定`-csv`参数来启用此功能
`--print-stats`	`LOCUST_PRINT_STATS`	`print-stats`	在UI运行中启用定期打印请求统计信息
`--only-summary`	`LOCUST_ONLY_SUMMARY`	`only-summary`	禁用在-headless运行期间定期打印请求统计信息
`--reset-stats`	`LOCUST_RESET_STATS`	`reset-stats`	生成完成后重置统计数据。在分布式模式下运行时，应该在master(主服务器)和worker(辅助服务器)上同时设置
`--html`	`LOCUST_HTML`	`html`	将HTML报告存储到指定的文件路径
`--skip-log-setup`	`LOCUST_SKIP_LOG_SETUP`	`skip-log-setup`	禁用Locust的日志记录设置。相反，配置是由Locust测试或Python默认值提供的
`--loglevel`,`-L`	`LOCUST_LOGLEVEL`	`loglevel`	在`DEBUG/INFO/WARNING/ERROR/CRITICAL`中选择，默认是`INFO`级别
`--logfile`	`LOCUST_LOGFILE`	`logfile`	指定日志文件的路径。如果未设置，log将转到stderr
`--exit-code-on-error`	`LOCUST_EXIT_CODE_ON_ERROR`	`exit-code-on-error`	设置当测试结果包含任何失败或错误时使用的程序退出代码
`-s`,`--stop-timeout`	`LOCUST_STOP_TIMEOUT`	`stop-timeout`	模拟用户在退出前完成任何执行任务所需要等待的秒数。默认值是立即终止。该参数只需要在运行Locust分布式时为主进程指定。

在没有web UI的情况下运行

参考在没有web UI的情况下运行

同时使用多个Locustfile

-f/--locustfile指令接收一个locustfile目录作为选项。Locust将递归搜索目录中所有的.py文件忽略locust.py或_开头的文件。
例如：
使用以下文件结构：

├── locustfiles/
│   ├── locustfile1.py
│   ├── locustfile2.py
│   └── more_files/
│       ├── locustfile3.py
│       ├── locust.py
│       ├── _ignoreme.py

$locust -f locustfiles

Locust将会使用到locustfile1.py,locustfile2.py,more_files/locustfile3.py。
此外，-f/--locustfile接受多个以逗号隔开的locustfiles。
例如：

$locust -f locustfiles/locustfile1.py,locustfiles/locustfile2.py,locustfiles/more_files/locustfile3.py

Locust将会使用到locustfile1.py,locustfile2.py,more_files/locustfile3.py。

使用用户类UI选择器运行Locust

当通过--class-picker参数来运行Locust时，在Web UI界面上可以选择你想执行测试的形态类和用户类。没有选择则执行所有的用户类。
例如：
使用以下文件结构：

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

Web UI界面将显示：
[外链图片转存失败,源站可能有防盗链机制,建议将图片保存下来直接上传(img-uwsCBlIT-1671073326649)(image/userclass_picker_example.png)]

自定义参数

参考自定义参数章节

自定义统计设置

Locust统计信息的默认配置设置在stats.py文件的常量中。可以通过重置这些常量值来达到特定场景的需求。为此需要导入locust.stats模块以及重置常量的设置：

import locust.stats
locust.stats.CONSOLE_STATS_INTERVAL_SEC = 15

它可以直接在locust文件中使用或提取到单独的文件供所有的locust文件来调用。
可修改的统计参数列表如下:

参数名称	用途描述
`STATS_NAME_WIDTH`	控制台输出内容中请求名称的列宽度
`STATS_TYPE_WIDTH`	控制台输出内容中请求类型的列宽度
`CSV_STATS_INTERVAL_SEC`	设置此选项，实现CSV文件写入的时间间隔
`CONSOLE_STATS_INTERVAL_SEC`	测试结果写入控制台的时间间隔
`CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW`	计算当前响应时间百分比时，指定窗口大小/分辨率(以秒为单位)
`PERCENTILES_TO_REPORT`	给要计算和报告的响应时间百分比列表