Locust运行配置与高级功能

发表于 更新于

本文是一份关于 Locust 性能测试工具的全面配置与运行指南，涵盖环境变量、配置文件、命令行参数、无头模式、分布式运行以及自定义扩展等核心内容。

一、 配置方式总览

Locust 支持多种配置方式，优先级从低到高依次为：

  1. ~/locust.conf (用户主目录)
  2. ./locust.conf (当前目录)
  3. --config 参数指定的文件
  4. 环境变量 (格式：LOCUST_<OPTION_NAME>)
  5. 命令行参数 (最高优先级)
1.1 通过环境变量配置
1
2
3
4
5
6
# Linux/macOS
LOCUST_LOCUSTFILE=custom_locustfile.py locust

# Windows (cmd)
set LOCUST_LOCUSTFILE=custom_locustfile.py
locust
1.2 通过配置文件配置

创建 locust.conf 或 master.conf 文件：

1
2
3
4
5
6
7
8
9
# 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

使用配置文件运行：

1
locust --config=master.conf

二、 核心运行模式

2.1 基础命令与常用选项
命令行参数 环境变量 描述
-f, --locustfile LOCUST_LOCUSTFILE 指定 Locust 测试脚本文件或目录。
-H, --host LOCUST_HOST 设置待测试系统的基准 URL。
-u, --users LOCUST_USERS 模拟的最大并发用户数。
-r, --spawn-rate LOCUST_SPAWN_RATE 每秒孵化的用户数。
--web-host, --web-port -P LOCUST_WEB_HOST, LOCUST_WEB_PORT 指定 Web UI 绑定的主机和端口。
2.2 无头模式运行 (Headless)

禁用 Web UI，直接通过命令行控制测试。

1
locust -f locustfile.py --headless -u 100 -r 5
  • 设置运行时间：使用 -t, --run-time 参数（例如 1h30m, 300s）。
  • 允许任务完成：使用 -s, --stop-timeout 参数，在停止前等待任务完成迭代（例如 --stop-timeout 10s）。
  • 动态调整用户数：即使在无头模式下，也可按 w/W（增加1/10用户）或 s/S（减少1/10用户）实时调整。
2.3 分布式运行

**主节点 (Master)**：负责协调和收集数据。

1
locust -f locustfile.py --master --expect-workers 3
  • --expect-workers：指定期望连接的工作节点数，连接齐备后才开始测试。
  • --master-bind-host/--master-bind-port：绑定主节点的接口和端口（默认 *:5557）。

**工作节点 (Worker)**：执行实际的负载生成。

1
locust -f locustfile.py --worker --master-host=192.168.1.100
  • --master-host/--master-port：指向主节点的地址。

无头模式下的分布式：主节点必须指定 --expect-workers 以等待工作节点就绪。

2.4 使用多个 Locustfile
  1. 指定目录：Locust 会递归扫描目录下的 .py 文件（忽略 locust.py 和以 _ 开头的文件）。
    1
    locust -f locustfiles/
  2. 指定多个文件：用逗号分隔。
    1
    locust -f locustfile1.py,locustfile2.py,locustfile3.py
2.5 用户类选择器 (Class Picker)

使用 --class-picker 参数启动，可在 Web UI 中选择本次运行要使用的特定 User 类或 Shape 类，而不是运行所有类。

1
locust -f locustfiles/ --class-picker

Web UI Class Picker

三、 高级功能与定制

3.1 自定义命令行参数

通过 init_command_line_parser 事件钩子添加自定义参数，这些参数可自动同步到工作节点并在 Web UI 中显示。

1
2
3
4
5
6
7
8
9
10
11
from locust import events

@events.init_command_line_parser.add_listener
def _(parser):
    parser.add_argument("--my-argument", type=str, env_var="LOCUST_MY_ARGUMENT", default="", help="自定义参数说明")
    # 设置 include_in_web_ui=False 可在 Web UI 中隐藏此参数
    parser.add_argument("--hidden-arg", include_in_web_ui=False, default="invisible")

@events.test_start.add_listener
def _(environment, **kw):
    print(f"自定义参数值: {environment.parsed_options.my_argument}")
3.2 定制统计信息设置

通过修改 locust.stats 模块的常量来调整统计行为。

1
2
3
4
5
6
7
8
import locust.stats

# 调整控制台输出间隔为15秒
locust.stats.CONSOLE_STATS_INTERVAL_SEC = 15
# 调整 CSV 文件写入间隔为5秒
locust.stats.CSV_STATS_INTERVAL_SEC = 5
# 调整要报告的百分位数
locust.stats.PERCENTILES_TO_REPORT = [0.5, 0.95, 0.99]

可定制参数：

  • STATS_NAME_WIDTH：控制台输出中请求名称列的宽度。
  • CURRENT_RESPONSE_TIME_PERCENTILE_WINDOW：计算当前响应时间百分位数的窗口大小（秒）。
3.3 自定义退出条件与退出码

通过 quitting 事件监听器，可以基于测试结果（如失败率、响应时间）自定义进程退出码，便于集成到 CI/CD 流程。

1
2
3
4
5
6
7
8
9
10
11
12
13
from locust import events
import logging

@events.quitting.add_listener
def _(environment, **kw):
    if environment.stats.total.fail_ratio > 0.01:
        logging.error("失败率超过1%")
        environment.process_exit_code = 1
    elif environment.stats.total.avg_response_time > 200:
        logging.error("平均响应时间超过200ms")
        environment.process_exit_code = 1
    else:
        environment.process_exit_code = 0

注意：默认情况下，如果有任何请求失败，Locust 会以退出码 1 结束。可使用 --exit-code-on-error 参数改变此行为。

四、 其他实用配置选项速查

命令行参数 环境变量 用途简述
--autostart LOCUST_AUTOSTART 自动开始测试（保留 Web UI）。
--autoquit LOCUST_AUTOQUIT 测试结束后自动退出（需与 --autostart 同用）。
--web-auth LOCUST_WEB_AUTH 为 Web UI 设置基础认证（格式：username:password）。
-T, --tags LOCUST_TAGS 仅执行带有指定标签的任务。
-E, --exclude-tags LOCUST_EXCLUDE_TAGS 排除带有指定标签的任务。
--csv LOCUST_CSV 将统计数据保存为 CSV 文件（生成 *_stats.csv, *_stats_history.csv, *_failures.csv）。
--html LOCUST_HTML 将 HTML 报告保存到指定文件。
--print-stats LOCUST_PRINT_STATS 在控制台定期打印统计信息。
--only-summary LOCUST_ONLY_SUMMARY 在无头模式下只打印最终摘要，禁止定期打印。
--loglevel -L LOCUST_LOGLEVEL 设置日志级别（DEBUG/INFO/WARNING/ERROR/CRITICAL）。
--logfile LOCUST_LOGFILE 指定日志文件路径。