# 有界任务执行测量

`sdk/go/cmd/orbit-exec-load` 通过公共 Go SDK 运行 HTTP 提交 → WSS Worker 授权/执行/续租/结果确认 → HTTP 读取持久化状态/尝试历史的完整链路。它测量普通 Pulse 任务；`orbit-load` 继续只测受理，两个命令独立。

## 准备及运行

使用一次性数据库或专用测试命名空间。凭据需有 `queues:read`、`tasks:submit`、`tasks:read`、`workers:connect`、`workers:consume`，覆盖指定队列。开发测试可通过 `orbit-admin bootstrap ... --worker-access --output /private/execution.credentials.json` 初始化，完整参数见[鉴权手册](authentication.md)。

启动匹配版本的 Orbit 后，在SDK模块目录执行：

```sh
cd sdk/go
export ORBIT_URL='http://127.0.0.1:8080'
export ORBIT_CREDENTIALS_FILE='/private/execution.credentials.json'

# 空处理器的框架路径
go run ./cmd/orbit-exec-load \
  -requests 96 -concurrency 8 -workers 2 -capacity 4 \
  -durations 0ms -run-timeout 2m

# 按序号依次使用0ms、100ms、1s的混合任务
go run ./cmd/orbit-exec-load \
  -requests 96 -concurrency 8 -workers 2 -capacity 4 \
  -durations 0ms,100ms,1s -run-timeout 2m

# 超过一个租约周期的任务，观察真实续租
go run ./cmd/orbit-exec-load \
  -requests 6 -concurrency 3 -workers 2 -capacity 4 \
  -durations 35s -run-timeout 2m
```

默认从凭据文件读取token和queue_id，也支持 `ORBIT_TOKEN`、`ORBIT_QUEUE_ID`。环境变量中非空token/queue覆盖文件值；`-queue` 和 `-url` 可覆盖对应环境变量。凭据不作为命令行参数或JSON结果输出。每个Worker均为负载进程中的独立WSS运行器，不是独立主机或故障域；Orbit服务进程保持独立。

工具读取并输出当前队列配置，不修改队列和应用额度。因此结果包含实际并发/开始速率限制的影响。运行前记录应用额度、服务连接池、数据库配置、CPU/内存限制及数据量，不能用Worker总capacity直接替代队列的有效许可上限。

## 参数与资源预算

| 参数 | 默认 | 约束 |
| --- | --- | --- |
| `-requests` | 100 | 1–10000，独立任务总数 |
| `-concurrency` | 8 | 1–128，提交和后续核验两个阶段各自的HTTP并发上限；最多等于任务数 |
| `-workers` | 2 | 1–32条独立WSS Worker连接 |
| `-capacity` | 4 | 每Worker 1–256，总计最多1024个物理处理器槽 |
| `-durations` | `0ms` | 1–16个逗号分隔时长，按序号取模；0–60秒的整毫秒 |
| `-timeout` | 5秒 | 单次HTTP请求1毫秒–1分钟，不是任务时限 |
| `-run-timeout` | 2分钟 | 整体1秒–1小时；必须比最大模拟时长至少长1秒，仍须为排队留余量 |
| `-poll-interval` | 250毫秒 | 每个活跃核验器100毫秒–10秒的查询间隔 |

整个运行共用截止上下文，结束时所有Worker有界收尾，最多再等5秒。中断或截止停止继续提交/核验，不自动取消、删除已受理任务。未完成任务继续保留原预算和身份；报告失败后不能把它们当作全部未执行。

每个任务最多一次执行尝试，安全策略为 `RECONCILE_ONLY`。总时限及单次尝试时限等于 `run-timeout`，以数据库首次受理时间计时；客户端整体截止另从本次运行开始计时。提交HTTP不自动重试。Worker沿现有SDK语义重连、续租和恢复控制确认；未知执行不改成明确失败来凑满成功数。

## 固定身份与核验

随机 `run_id` 同时进入本次专属处理器名称 `load.exec.{run_id}`、业务键 `orbit-exec-{run_id}`、提交幂等键 `orbit-exec-{run_id}-{sequence六位十进制}` 及输入。序号从0开始，每项输入和预期结果都是 `{run_id, sequence, duration_ms}`。处理器只有可取消等待和回显，不调用文件、数据库或外部业务接口。

所有提交发起完后，有界核验器读取已确认的任务及尝试。每一项成功必须同时满足：

- 受理回执身份唯一，队列/处理器/版本/关联键/输入/尝试预算符合本次固定请求。
- 任务为 `SUCCEEDED`、`effect_uncertain=false`、`attempt_count=1`，结果匹配预期输入。
- 尝试历史恰好一项、没有后续页；属于原任务，代次1、`SUCCEEDED`，授权和结束时间齐全。
- 数据库时间满足创建、可执行、领取、授权、结束顺序，任务完成时间与尝试结束时间一致。
- 本地处理器对应原任务且该序号恰好调用一次；重复调用及错误输入留在错误计数中。

成功任务通过HTTP读取持久化事实确认；SDK的 `ReportsConfirmed`、事件通知或处理器返回nil不能替代核验。

## 报告与错误退出

标准输出是一行JSON，原始样本见[执行测量报告](../reports/phase-6-execution-load.md)。`complete=true` 才返回退出码0；缺少权限、提交失败/回执未知、读取失败、任务失败/核查、截止、Worker错误或核验不一致均产生不完整报告和非零退出码。

| 字段 | 含义 |
| --- | --- |
| `attempted` / `not_submitted` | 实际提交调用数 / 截止前未提交数 |
| `accepted` / `admission_errors` | 已核验唯一回执数 / 明确拒绝或受理结果无法确认数；后者不等于数据库中没有任务 |
| `verified_success` / `unverified` | 已受理项中最终通过完整核验数 / 其余项数 |
| `handler_calls` / `duplicate_invocations` | 本地有效输入处理器调用数 / 同一序号多余调用数 |
| `unconfirmed_handler_calls` | 处理器执行了但没有收到有效受理回执的调用数；整个运行仍失败 |
| `worker_started` / `worker_reconnects` / `worker_renewals_confirmed` | SDK本进程辅助观测，不代表持久成功数 |
| `errors` | 有限错误分类及数量，既有每项错误，也有运行级错误，不应求和为失败任务数 |

每个耗时分布返回 `count`、`p50_ms`、`p95_ms`、`p99_ms`、`max_ms`，采用最近秩。没有样本时百分位为null。分母分别是：

| 耗时 | 时钟与分母 |
| --- | --- |
| `admission` | 本机单调时钟；所有实际提交的HTTP交换，包含失败 |
| `queue_wait` | 数据库 `available_at` → `authorized_at`；仅完整核验成功项，包含等待领取及开始授权 |
| `authorized_execution` | 数据库 `authorized_at` → `ended_at`；仅完整核验成功项，包含开始确认传输、模拟处理、结果回传至结束事务取时点 |
| `task_completion` | 数据库 `created_at` → `completed_at`；仅完整核验成功项 |

后面三个分布使用同一数据库时钟，避免核验轮询顺序污染执行耗时。时间戳记录事务内取时点，不能测量该取时点之后的COMMIT落盘及确认延迟；这些行最终已持久提交由后续HTTP核验确认。它们依赖数据库墙钟；时间逆序会报告 `TIMESTAMP_MISMATCH`。不完整运行的成功子集存在幸存者偏差，不能与完整样本直接比较。整次墙钟包含预检、读取和Worker收尾，不能拿 `requests / 整次耗时` 声称纯执行吞吐。

## 回归与生产边界

`make integration` 在隔离MySQL及真实服务上执行6项混合任务的命令冒烟；`make sdk-check` 检查独立模块并执行测量计算、失败/超时/错配及重复调用测试。

该工具新增普通任务短/混合/中长执行路径测量能力。定时集中触发、Weave流程和长期积压已有独立工具/报告（见[定时手册](schedule-load.md)、[流程手册](workflow-load.md)和[积压报告](../reports/phase-6-backlog.md)）；仍需要慢消费者/重连风暴、目标硬件资源曲线、复制切换及跨故障域测试，当前样本不能替代这些生产门槛。