77 lines
6.9 KiB
Markdown
77 lines
6.9 KiB
Markdown
# Pulse 定时触发测量工具
|
||
|
||
`orbit-schedule-load` 在隔离环境创建多个有限的固定间隔计划，让它们共享同一组触发时间，再通过真实 Worker 和持久化记录逐项核验。处理器只回显固定 JSON，没有外部业务副作用；工具不修改队列额度，不需要额外消息队列或缓存。
|
||
|
||
## 运行场景
|
||
|
||
在 SDK 模块目录执行，凭据需要队列读取、Worker 执行、任务读取及计划创建/读取/控制权限。隔离测试凭据可由 `orbit-admin bootstrap --worker-access --schedule-access` 签发，完整步骤见[管理手册](operations.md)；不要使用生产队列做样本。
|
||
|
||
```sh
|
||
# 当前目录：sdk/go
|
||
ORBIT_URL=https://orbit.example.test \
|
||
ORBIT_CREDENTIALS_FILE=/run/secrets/orbit-sample.json \
|
||
go run ./cmd/orbit-schedule-load \
|
||
-schedules 4 -requests 6 -interval 1s \
|
||
-workers 2 -capacity 4 -start-delay 5s \
|
||
-run-timeout 90s -poll-interval 100ms
|
||
```
|
||
|
||
这个例子预期产生 **4 个计划 × 每计划 6 次 = 24 个任务**。每计划先以暂停状态创建，全部创建完后启动 Worker 并恢复计划。恢复必须在共同起点之前完成，迟到会判定本次样本失败。排他的 `end_at = start_at + requests × interval` 限制触发总量；即使工具被强制终止，计划也有固定终点。
|
||
|
||
可以把 `-schedules` 调到 32、`-requests` 设为 4，观察同一秒集中触发及现有队列速率限制下的排队。队列默认并发和每秒授权量仍由部署配置决定，工具只记录预检快照，不提高配额。另可使用 `-schedules 2 -requests 12 -start-delay 1s -run-timeout 5s` 验证截止不足的失败报告；它必须非零退出，未观察到的触发点不能算成功。
|
||
|
||
要观察持久化积压，可在一次性数据库使用 `-schedules 32 -requests 8 -workers 1 -capacity 1 -start-delay 5s -run-timeout 180s`。该配置会让256个触发点集中进入队列，报告预期非零并保留未核验分母；独立连接应每2秒读取 `pulse_tasks` 的 `WAITING/LEASED/RUNNING/SUCCEEDED` 计数，示例结果见[长期积压报告](../reports/phase-6-backlog.md)。
|
||
|
||
## 参数边界
|
||
|
||
| 参数 | 默认值 | 限制/语义 |
|
||
| --- | --- | --- |
|
||
| `-requests` | 6 | 每计划 1–100 次，不是总任务数 |
|
||
| `-schedules` | 1 | 1–32 个，共享起止和间隔 |
|
||
| `-interval` | 1s | 1s–1m，整毫秒 |
|
||
| `-start-delay` | 5s | 1s–1m，整毫秒；预留创建、注册和恢复时间，不保证 Worker 已连接 |
|
||
| `-workers` | 2 | 1–16 个 WSS 连接，均在一个负载进程中 |
|
||
| `-capacity` | 2 | 每 Worker 1–128，总容量不超过 256 |
|
||
| `-timeout` | 5s | 单个 HTTP 请求 1ms–1m |
|
||
| `-run-timeout` | 2m | 整次测量 5s–1h，另外最多 5s Worker 收尾及 5s 计划暂停收尾 |
|
||
| `-poll-interval` | 250ms | 100ms–10s，每轮顺序查询各计划及未核验任务 |
|
||
| `-credentials` | 环境变量路径 | 最大 16 KiB 的私密 JSON，包含 `token`、`queue_id` |
|
||
|
||
URL、凭据路径和队列也可从 `ORBIT_URL`、`ORBIT_CREDENTIALS_FILE`、`ORBIT_QUEUE_ID` 读取。HTTP 明文仅用于 SDK 允许的本机隔离测试；远端使用 HTTPS/WSS。
|
||
|
||
计划使用 `FIXED_RATE`、`UTC`、`CATCH_UP`、`PARALLEL`，批量补跑上限 100，补跑窗口覆盖整次样本及计划跨度。发布版本固定为 1，服务端时区快照标识与生效时间从首次回执保存，后续不得变化。任务策略固定一次尝试、`RECONCILE_ONLY`，总时限和尝试时限为 `run-timeout`；未知结果不会被工具自动重跑。
|
||
|
||
## 核验和报告
|
||
|
||
输出一行 JSON，退出码 0 只表示本次有界样本完整通过。以下分母分别报告：
|
||
|
||
| 字段 | 解释 |
|
||
| --- | --- |
|
||
| `expected_occurrences` | 配置的总触发数，包含尚未观察到的部分 |
|
||
| `occurrences` | 已看到的唯一预期触发点 |
|
||
| `fired` | 单点触发且关联唯一任务的数量，不等于执行成功 |
|
||
| `verified_success` | 任务结果、唯一尝试、来源与时间顺序全部通过的数量 |
|
||
| `unobserved` | 预期数减已观察触发点数 |
|
||
| `unverified` | 已触发数减已核验成功数 |
|
||
| `handler_calls` / `duplicate_invocations` | 有效输入的本地调用数 / 同任务额外调用数 |
|
||
| `unconfirmed_invocations` | 尚未对应到已核验任务和同一尝试的本地调用数 |
|
||
| `plans` | 原计划身份、创建/恢复/暂停键、版本、生效时间和逐计划计数 |
|
||
|
||
核验拒绝错配计划、固定版本变化、非预期时间槽、重复触发/任务、历史消失、分页溢出、跳过/合并、错误输入/结果、额外尝试、来源错配和时间倒置。只有 `SUCCEEDED` 任务与唯一成功尝试一致才计为成功。已通过核验的槽位只计一次，重复轮询不会放大分母。
|
||
|
||
`trigger_lag` 是计划时间到任务受理，`queue_wait` 是受理到开始授权，`authorized_execution` 是授权到结果落库，`completion` 是计划时间到结果落库。这些时间均来自数据库，不混入客户端轮询等待；授权执行耗时包含通信和事务，不是纯函数执行时间。分布只纳入已核验成功样本，空分布百分位为 `null`。
|
||
|
||
`complete=true` 还要求全部计划恢复成功、固定触发范围耗尽、暂停已确认，且每个已核验任务能对应到本地唯一调用/尝试，Worker 启动数一致、无错误或重复。超时、调用过多或收尾不明均不得显示完整通过。
|
||
|
||
## 超时与原身份核查
|
||
|
||
创建和恢复请求不自动重试。创建请求结果不明时，`plans[].id` 可能为空；原创建请求的 `paused=true` 保证它不会自行开始触发。用报告里的 `create_key`、`run_id`、计划序号和时间/策略字段重建原请求，按原键读取回执，不能生成新键替代。收到计划 ID 后的所有退出路径都会尝试暂停。
|
||
|
||
暂停先读当前 revision，再带固定键提交。仅明确收到 `409 STATE_CONFLICT` 时，才重新读版本并使用下一个已记录键，最多三次；超时、断线或其他冲突停止重试，保留最后的 `pause_key` 和 `pause_revision`。恢复原因固定为 `start bounded schedule verification`，暂停原因为 `stop bounded schedule verification`。收尾使用独立上下文，最多 5 秒，多个已知计划并发暂停。
|
||
|
||
`pause_confirmed=true` 只表示停止后续触发，已经生成的任务仍可执行。截止后报告是观察快照，任务可能在工具停止后完成；应沿原计划的触发历史、任务与尝试查询核对。工具不删除计划、任务、操作回执或审计。若创建回执不明、暂停不明或进程被强杀，报告不构成清理完成的证明。
|
||
|
||
## 验证范围
|
||
|
||
复现样本、原始 JSON、构建哈希和实际工具链见[定时测量报告](../reports/phase-6-schedule-load.md)。该工具覆盖固定间隔的同时触发；Cron/DST、其他漏跑和重叠策略、计划版本竞争由原调度功能集成测试覆盖。此次样本不证明这些场景的容量，也不证明长期积压、资源曲线、跨故障域高可用或生产 SLA。
|