feat: add bounded admission load tool

This commit is contained in:
2026-09-19 23:43:09 +08:00
parent 7766b0b710
commit 3954efef70
9 changed files with 450 additions and 0 deletions

35
docs/api/load.md Normal file
View File

@@ -0,0 +1,35 @@
# 有界受理负载工具
`orbit-load` 是独立 Go SDK module 中的受理负载工具,用于在隔离环境测量 HTTP 受理请求的延迟分布。它只提交带独立幂等键的任务,不启动 Worker、不执行业务副作用、不自动重试,也不把测量结果解释为生产吞吐或租户容量保证。
## 运行
先为专用测试命名空间准备凭据,再运行:
```sh
cd sdk/go
ORBIT_URL='http://127.0.0.1:8080' \
ORBIT_CREDENTIALS_FILE='/private/orbit-load.credentials.json' \
go run ./cmd/orbit-load \
-requests 1000 \
-concurrency 32 \
-timeout 10s
```
也可以直接传 `-url`、`-token` 和 `-queue`。命令拒绝非 32 位小写十六进制队列 ID,默认上限是 100000 次请求和 1024 个并发请求;并发数超过请求数时自动降到请求数。每次请求的超时独立计算,超时或 HTTP 错误不会再次提交。
每个任务使用形如 `orbit-load-{run_id}-{sequence}` 的幂等键,输入只包含本次运行标识和序号,处理器默认为 `load.noop`,任务尝试预算固定为 1。命令不会删除生成的任务;测试必须使用一次性数据库或专用命名空间,结束后按保留策略处理,不能直接对生产命名空间运行。
## 输出
标准输出是一行 JSON:
```json
{"started_at":"2026-09-19T00:00:00Z","finished_at":"2026-09-19T00:00:02Z","requests":100,"concurrency":8,"success":100,"errors":0,"p50_ms":11.2,"p95_ms":24.7,"p99_ms":31.4,"max_ms":35.1}
```
`p50_ms`、`p95_ms`、`p99_ms` 和 `max_ms` 统计所有请求(包括失败请求)的端到端 HTTP 交换耗时,百分位采用最近秩;`error_codes` 只保留有限错误分类,例如 `TIMEOUT`、`TRANSPORT`、`HTTP_409` 或服务端稳定错误码,不输出令牌、请求体或内部错误文本。存在失败请求时仍输出报告,并以非零状态退出。
## 解释边界
这项工具固定的是客户端请求数、并发和消息形状,不能替代以下验证:真实 Worker 执行吞吐、定时触发、流程推进、数据库锁等待、复制延迟、磁盘与网络 I/O、故障恢复、跨主机拓扑或长时间积压。正式容量报告必须同时记录硬件、MySQL 拓扑、连接池、数据量、任务时长、结果大小、故障注入和积压清空时间,并将本工具结果与其他阶段指标分开。