调查 Grafana Cloud k6…

当用户给出 k6 云测试/运行链接或问“这个测试是否通过/为什么失败/看某次运行的指标和日志”时，按 9 步流程定位测试、分页列运行、三层判定结果、拉取指标日志并安全编辑脚本。

适用场景

解决思路

1. 先确认 gcx 已安装并对目标 stack 完成认证：运行 `gcx --context <stack> config check`，期望输出 "✔ Connectivity: online"。
2. 从用户 URL 识别对象：`/a/k6-app/tests/<id>` 是负载测试（多个运行的父级），`/a/k6-app/runs/<id>` 是具体运行；若给的是 run，用 `gcx --context <stack> api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/<run_id>` 取响应中的 `.test_id` 反查所属测试。
3. 获取测试元数据与脚本：`gcx --context <stack> k6 load-tests get <test_id> -o json`；脚本按 k6-manage §5 的 GET 半段获取并备份。注意存在两个脚本端点——当前负载测试脚本与每次运行实际执行的快照；凡涉及“改了什么/为什么这次失败”或查看几天前的运行，必须同时取该运行的 bundled 快照并与当前脚本（或另一运行的快照）做 diff，当前脚本不能代表过去运行。
4. 分页列出运行：对 `/cloud/v6/load_tests/<test_id>/test_runs` 使用 k6-manage §3 的 `gcx api` + `@nextLink` 循环（`/test_runs` 上限 1000 行，`gcx k6 runs list --limit 0` 不会自动跟随 `@nextLink`）；收集后按 `created` 倒序打印总数、日期范围、最新运行时间；若最新运行超过一天前要主动指出，用户可能误以为调度仍在触发。
5. 校验日期口径：用户说“最近 7 天/本周/近期”时按日期过滤而非按行数（`last7 = [r for r in all_runs if r['created'] >= '<today_minus_7_days_iso>']`），因为“最近 7 次运行”可能横跨一天也可能横跨一年；若 `len(last7) == 0` 立即告知用户，不要用陈旧数据继续。
6. 三层判定通过/失败：① 运行级 `result`（passed/failed/error/aborted，表示是否违反阈值）；② 运行级 `status`（completed/aborted，表示是否正常结束）；③ 脚本内 `check()` 的 v5 `checks` 指标按 `check` 标签聚合的每项成功率。对“用户认为失败但 result: passed”的运行重点查第三层——常见模式是每次迭代 `check()` 都返回 false 但没在 `checks` 上定义阈值，所以运行仍“通过”。用 `gcx --context <stack> api "/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/query_aggregate_k6(query='ratio by (check)',metric='checks')"` 查每项成功率（0.0–1.0），再用 `increase_nz by (check)`（成功数）和 `increase_z by (check)`（失败数）取原始计数。
7. 拉取运行指标（v5 端点）：6a 用 `/v5/test_runs/<run_id>/metrics` 列出可用指标；6b 用 `/v5/test_runs/<run_id>/labels?match[]=http_req_duration` 列出标签以确定可过滤/分组维度；6c 用 `/v5/test_runs/<run_id>/query_range_k6(query='histogram_quantile(0.95) by (name,status)',metric='http_req_duration',step=10)` 取时间序列（按指标类型选查询方法，见 metrics.md 的 Query methods 表）；6d 用 `/v5/test_runs/<run_id>/query_aggregate_k6(query='increase',metric='http_reqs')` 取整段运行的标量聚合。浏览器测试的 URL/状态分布来自 `labels` + `label/{name}/values`，不是单独的 tags 端点。
8. 拉取运行日志：按 k6-manage §4 的 Loki 配方，用 `gcx api` 访问 `/api/plugins/k6-app/resources/logs/...`，选择器 `{test_run_id="<id>"}`，必须带 `X-K6TestRun-Id` 头，时间范围 scope 到 `run.created`/`run.ended`；把响应保存到 `/tmp/run_<id>_logs.json` 再从文件汇总。
9. （若被要求）安全编辑脚本：走 k6-manage §5 完整流程——GET → 备份 → 编辑 → `k6 inspect` → 1 次迭代 smoke → PUT（`Content-Type: application/octet-stream`）→ sha256 校验。涉及阈值时同时参考“阈值语义”中的零观测陷阱、`abortOnFail` 云延迟与运算符支持。
10. 按问题形态选报告模板。单次运行调查输出：Test 名称与 id、Run id/created→ended/load_zone/result、日志（流数与行数摘要）、关键指标（指标: 方法 = 值 (n=计数)）、每项 check 分解（名称: 成功率 (succ/fail)）、一段诊断。多次运行对比输出：一句话重述归因问题、运行时间线表格（Run ID | Created (UTC) | Result | exec_duration | processing_duration | k6 build | error code | key check ratios）、关键差异列表（字段: 通过值 vs 失败值 — 解读）、相关脚本 diff 摘要、一段归因诊断（测试侧/SUT 侧/平台侧并给证据）。表格能让并排异常一目了然：各列在通过与失败间完全一致即可排除该维度，翻转的列就是候选原因。若用户要原始数据，另存到 `/tmp/k6inv/run<id>/` 并告知路径。
11. 理解阈值语义：`result` 中 passed=所有阈值通过（或未定义阈值）、failed=至少一个阈值失败、error=脚本崩溃（如浏览器无法启动）或 k6 Cloud 平台侧中止（看 `status_history[*].extra.code`，非空如 `8016` = processing_metrics 超过 1 小时上限，属平台中止而非代码问题）、aborted=用户或系统中止。`check()` 不直接影响 `result`，只向内置 `checks` rate 指标发观测，无阈值引用 `checks` 时失败的 check 对运行级 result 不可见。
12. 规避“零观测=通过”陷阱：底层指标零样本时 k6 会把阈值报为 ✓ pass，即使表达式本应为 false；脚本在到达相关 `check()` 前抛异常时就会这样。在 `catch` 块中强制产生一次 check 观测：try 中 `check(r, { "response is 200": x => x.status() === 200 })` 并追加 `check(true, { "script completed without exception": () => true })`，catch 中 `console.error(e); check(null, { "script completed without exception": () => false })`，finally 中 `await page.close()`；然后在 thresholds 加 `'checks{check:script completed without exception}': ['rate==1.0']`，可同时捕获导航失败与后续阶段异常。
13. 注意 `abortOnFail` 云延迟：k6 云端每 60 秒评估一次阈值，`abortOnFail` 最多延迟 60 秒；短于 60 秒的运行可能在迭代自然结束前不触发 abort，但结束时仍会评估阈值并把 `result` 翻为 failed，abort 只是没省下执行时间。
14. 阈值运算符：文档只列 `<`、`>`、`<=`、`>=`，但 `==` 和 `!=` 实际也可用；对 rate 指标（0.00–1.00），`rate==1.0` 表示每次观测都非零，`rate==0` 表示所有观测都为零。
15. 处理本工作流特有陷阱：最新运行显示 6 个月前但调度是每日 → 没分页 `/test_runs`，用 `@nextLink` 循环；“最近 7 天”报告只含旧运行 → 按行数而非日期过滤，改用 `created >= <iso_date>`；阈值 ✓ pass 但 check 失败 → 零 check 观测，迭代在 `check()` 前中止；`result: error` 但日志/指标正常 → 可能是平台中止（如 processing_metrics 超 1 小时上限，code 8016），查 `status_history[*].extra.code`，非空平台码不怪代码；用当前负载测试脚本调查过去运行 → 脚本可能已被编辑，先取该运行的 bundled 脚本再 diff；刚覆盖了用户脚本 → 从 Step 2 的备份恢复，想了解 URL 就用任意非变更命令加 `-vvv --log-http-payload`；CLI `--iterations 1` 破坏浏览器场景 → 它会整体覆盖 scenario 块，改用 sed 在文件内编辑 `iterations:`。

适用边界 · 注意事项

• 未安装或未对目标 Grafana Cloud stack 认证 gcx 时无法执行（依赖 `gcx` 与 k6-app 插件代理）。
• 没有 Grafana Cloud k6 账号/测试或运行数据时无从调查。
• 用户只想了解 k6 脚本语法或本地运行 k6，而非调查云端测试/运行时，不适用。