Pulse 定时触发测量工具

orbit-schedule-load 在隔离环境创建多个有限的固定间隔计划，让它们共享同一组触发时间，再通过真实 Worker 和持久化记录逐项核验。处理器只回显固定 JSON，没有外部业务副作用；工具不修改队列额度，不需要额外消息队列或缓存。

运行场景

在 SDK 模块目录执行，凭据需要队列读取、Worker 执行、任务读取及计划创建/读取/控制权限。隔离测试凭据可由 orbit-admin bootstrap --worker-access --schedule-access 签发，完整步骤见管理手册；不要使用生产队列做样本。

# 当前目录：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 验证截止不足的失败报告；它必须非零退出，未观察到的触发点不能算成功。

参数边界

参数	默认值	限制/语义
`-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、构建哈希和实际工具链见定时测量报告。该工具覆盖固定间隔的同时触发；Cron/DST、其他漏跑和重叠策略、计划版本竞争由原调度功能集成测试覆盖。此次样本不证明这些场景的容量，也不证明长期积压、资源曲线、跨故障域高可用或生产 SLA。

6.5 KiB Raw Blame History Unescape Escape