k6-cloud-investigate-test

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

k6 Cloud test investigator

k6 Cloud测试调查工具

Structured 9-step workflow for investigating a Grafana Cloud k6 test or run.

This skill is workflow-only. All API calls go through

gcx api

against the plugin proxy, using v6 for REST and v5 for metrics. For the underlying mechanics (gcx auth, path conventions, endpoint discovery, log queries, script editing, threshold semantics, gotchas), see the

k6-manage

skill — every step below references it.

The content unique to this skill is:

the ordered investigation flow (Steps 1-9 below)
the date-alignment check ("last 7 days" ≠ "last 7 runs")
the 3-layer pass/fail determination (
```
result
```
vs
```
status
```
vs per-check
```
checks
```
query)
a worked example with realistic numbers (
```
references/worked-example.md
```
)

针对Grafana Cloud k6测试或运行的结构化9步调查工作流。

本技能仅包含工作流。所有API调用均通过

gcx api

对接插件代理，REST接口使用v6版本，指标接口使用v5版本。关于底层机制（gcx认证、路径约定、端点发现、日志查询、脚本编辑、阈值语义、常见陷阱），请查看

k6-manage

技能——以下每一步都会引用该技能的内容。

本技能独有的内容包括：

有序的调查流程（下文第1-9步）
日期对齐检查（“最近7天”≠“最近7次运行”）
三层通过/失败判定机制（
```
result
```
vs
```
status
```
vs 基于
```
checks
```
查询的逐检查判定）
带有真实数据的示例（
```
references/worked-example.md
```
）

Core principles

核心原则

Read before write. Always GET the script before any PUT.
```
gcx k6 load-tests update-script
```
is a write that replaces the live script with whatever file you pass — running it "just to see the URL it hits" has cost users their production scripts. If you need to learn URLs, run any non-mutating command with
```
-vvv --log-http-payload
```
instead.
Paginate when enumerating runs. The
```
/test_runs
```
endpoint caps at 1000 rows and
```
gcx k6 runs list --limit 0
```
does not auto-follow
```
@nextLink
```
. Use the
```
gcx api
```
loop documented in
```
k6-manage
```
§3.
Verify date framing. When the user says "last 7 days", "this week", "recent runs" — confirm the most-recent run's
```
created
```
actually falls in that window. Surface the gap if not.
check()
doesn't fail runs; only
thresholds
do. And thresholds with zero observations are reported as ✓ pass. See "Threshold semantics" below for the full deep dive; the per-check
```
checks
```
metric query in Step 5 catches both cases.

先读再写。执行任何PUT操作前务必先获取（GET）脚本。
```
gcx k6 load-tests update-script
```
是一个写入操作，会用你传入的文件替换线上脚本——仅仅为了查看它请求的URL而运行该命令曾导致用户丢失生产环境脚本。如果需要了解请求的URL，请在任何非变更命令后添加
```
-vvv --log-http-payload
```
参数来运行。
枚举运行时需分页。
```
/test_runs
```
端点最多返回1000条数据，且
```
gcx k6 runs list --limit 0
```
不会自动跟进
```
@nextLink
```
。请使用
```
k6-manage
```
第3节中记录的
```
gcx api
```
循环方式。
验证时间范围。当用户提到“最近7天”“本周”“近期运行”时——确认最新运行的
```
created
```
时间确实落在该范围内。如果不符合，需向用户说明这一差异。
check()
不会导致运行失败；只有
thresholds
会。且没有观测数据的阈值会被标记为✓通过。下文的“阈值语义”部分会详细说明；第5步中基于
```
checks
```
指标的逐检查查询可以同时捕捉这两种情况。

Prerequisites

前置条件

gcx

installed and authenticated against the user's stack. See

k6-manage

§1. Verify with:

bash

gcx --context <stack> config check    # expect "✔ Connectivity: online"

已安装

gcx

并针对用户的栈完成认证。请查看

k6-manage

第1节。可通过以下命令验证：

bash

gcx --context <stack> config check    # 预期输出："✔ Connectivity: online"

Investigation workflow

调查工作流

Step 1: Identify the test and target run(s)

步骤1：确定测试及目标运行实例

From the user's URL:

```
/a/k6-app/tests/<id>
```
→ load test (parent of many runs)
```
/a/k6-app/runs/<id>
```
→ a specific run

To go run → test: fetch the run via

gcx api

, see

k6-manage

§2 for the path-shape rules:

bash

gcx --context <stack> api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/<run_id>

and read

.test_id

from the response. To list runs for a test, see Step 3.

从用户提供的URL中识别：

```
/a/k6-app/tests/<id>
```
→ 负载测试（多个运行实例的父资源）
```
/a/k6-app/runs/<id>
```
→ 特定的运行实例

若要从运行实例关联到测试：通过

gcx api

获取运行实例信息，路径规则请查看

k6-manage

第2节：

bash

gcx --context <stack> api /api/plugins/k6-app/resources/cloud/cloud/v6/test_runs/<run_id>

然后从响应中读取

.test_id

字段。若要列出某个测试的所有运行实例，请查看步骤3。

Step 2: Fetch test metadata and script

步骤2：获取测试元数据及脚本

bash

gcx --context <stack> k6 load-tests get <test_id> -o json

For the script, follow the GET half of the safe-edit recipe in

k6-manage

§5 — save a backup if you'll be editing later.

Two script endpoints exist, and the difference matters for investigation.

k6-manage

§5 documents both: the current load-test script and the per-run snapshot that was actually executed. They drift apart whenever the script is edited after a run. Whenever the question involves "what changed", "why did this run fail", or you're examining a run more than a few days old, also fetch the run-bundled snapshot(s) via

k6-manage

§5's run-script endpoint and diff against the current load-test script (or against another run's snapshot). The current load-test script is the wrong artifact to reason about a past run.

bash

gcx --context <stack> k6 load-tests get <test_id> -o json

获取脚本时，请遵循

k6-manage

第5节中安全编辑流程的GET部分——如果后续需要编辑，请先备份脚本。

存在两个脚本端点，二者的差异对调查至关重要。

k6-manage

第5节记录了这两个端点：当前负载测试脚本，以及实际执行的运行实例快照脚本。每当运行实例执行后脚本被编辑，二者就会产生差异。当问题涉及“发生了什么变化”“为什么这次运行失败”，或者你正在检查的是几天前的运行实例时，还需通过

k6-manage

第5节中的运行实例脚本端点获取该运行的快照脚本，并与当前负载测试脚本（或其他运行实例的快照脚本）进行对比。当前负载测试脚本并非分析过去运行实例的正确依据。

Step 3: List runs WITH pagination

步骤3：列出所有运行实例（含分页）

Use the

gcx api

@nextLink

loop pattern documented in

k6-manage

§3 against

/cloud/v6/load_tests/<test_id>/test_runs

. After collecting

all_runs

python

print(f"Total: {len(all_runs)}")
runs_sorted = sorted(all_runs, key=lambda r: r['created'], reverse=True)
for r in runs_sorted[:10]:
    print(f"  {r['created']:30s} id={r['id']:>8} status={r['status']:<10} result={r.get('result','?')}")

Report to user: total run count, date range, latest run date. If "latest run" is more than a day old, call it out — they may believe the schedule is firing when it isn't.

使用

k6-manage

第3节中记录的

gcx api

@nextLink

循环方式，对接

/cloud/v6/load_tests/<test_id>/test_runs

端点。收集完

all_runs

后：

python

print(f"Total: {len(all_runs)}")
runs_sorted = sorted(all_runs, key=lambda r: r['created'], reverse=True)
for r in runs_sorted[:10]:
    print(f"  {r['created']:30s} id={r['id']:>8} status={r['status']:<10} result={r.get('result','?')}")

向用户报告：总运行次数、时间范围、最新运行时间。如果“最新运行”已超过一天，需特别指出——用户可能以为定时任务仍在正常执行。

Step 4: Verify date alignment with user's intent

步骤4：验证时间范围与用户意图一致

If the user asked for "last 7 days" / "this week" / "recent": filter by date range, not by row count — "7 most recent runs" could span a day or a year depending on how often the test runs.

python

last7 = [r for r in all_runs if r['created'] >= '<today_minus_7_days_iso>']

len(last7) == 0

: surface this to the user immediately. Don't proceed with stale data.

如果用户要求查看“最近7天”“本周”“近期”的运行：请按日期范围过滤，而非按行数过滤——“最近7次运行”可能仅间隔一天，也可能跨越一年，取决于测试的执行频率。

python

last7 = [r for r in all_runs if r['created'] >= '<today_minus_7_days_iso>']

如果

len(last7) == 0

：需立即告知用户。不要继续使用过期数据进行分析。

Step 5: Determine pass/fail status

步骤5：判定通过/失败状态

For each run examine three independent layers:

Layer	Field	Meaning
Run-level outcome	`result` ( `passed` / `failed` / `error` / `aborted` )	Whether thresholds breached
Run-level status	`status` ( `completed` / `aborted` )	Whether the run finished orderly
In-script checks	v5 `checks` metric, aggregated by the `check` label	Per-check success rate

For a run that the user thinks is "failing" but reports

result: passed

: check the third layer. Common pattern: every iteration's

check()

returns false but the run still "passes" because no threshold is defined on

checks

. See "Threshold semantics" below for the full deep dive (zero-observation trap,

abortOnFail

cloud delay, operator support).

Query the per-check breakdown via v5 (see

k6-manage/references/metrics.md

§7 for

query_aggregate_k6

shape):

bash

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')"

Each result entry in the response carries a

check

label with the check name and a single value: the success ratio (0.0–1.0). For raw success/fail counts, also query

increase_nz by (check)

(successes) and

increase_z by (check)

(failures).

针对每个运行实例，检查三个独立维度：

维度	字段	含义
运行级结果	`result` （ `passed` / `failed` / `error` / `aborted` ）	是否有阈值被违反
运行级状态	`status` （ `completed` / `aborted` ）	运行是否正常完成
脚本内检查	v5版本的 `checks` 指标，按 `check` 标签聚合	逐检查的成功率

如果用户认为某个运行“失败”但

result

显示为

passed

：请检查第三个维度。常见情况：每次迭代的

check()

都返回false，但由于未针对

checks

定义阈值，运行仍显示“通过”。下文的“阈值语义”部分会详细说明（零观测陷阱、

abortOnFail

云端延迟、运算符支持）。

通过v5接口查询逐检查的详细情况（

query_aggregate_k6

的格式请查看

k6-manage/references/metrics.md

第7节）：

bash

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')"

响应中的每个结果条目都带有

check

标签（包含检查名称）和一个数值：成功率（0.0–1.0）。若要获取原始的成功/失败次数，还需查询

increase_nz by (check)

（成功次数）和

increase_z by (check)

（失败次数）。

Step 6: Fetch metrics for a run

步骤6：获取运行实例的指标

Use the v5 metrics endpoints documented in

k6-manage/references/metrics.md

. Typical workflow:

bash

undefined

使用

k6-manage/references/metrics.md

中记录的v5版本指标端点。典型工作流如下：

bash

undefined

6a. List metrics available for the run (metrics.md §1)

6a. 列出该运行实例可用的指标（metrics.md第1节）

gcx --context <stack> api /api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/metrics

6b. List labels for a metric to know what's available to filter/group by (metrics.md §4)

6b. 列出某个指标的标签，了解可用于过滤/分组的维度（metrics.md第4节）

gcx --context <stack> api
"/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/labels?match[]=http_req_duration"

6c. Time-series — pick a query method that matches the metric's type (metrics.md §6)

6c. 时间序列数据——根据指标类型选择合适的查询方式（metrics.md第6节）

gcx --context <stack> api
"/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/query_range_k6(query='histogram_quantile(0.95) by (name,status)',metric='http_req_duration',step=10)"

6d. Scalar aggregate over the whole run (metrics.md §7)

6d. 整个运行周期内的标量聚合数据（metrics.md第7节）

gcx --context <stack> api
"/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/query_aggregate_k6(query='increase',metric='http_reqs')"


Picking the right query method per metric type matters — see the "Query methods" tables in `k6-manage/references/metrics.md`. For browser tests, the URL/status breakdown comes from `labels` + `label/{name}/values` (metrics.md §4/§5), not from a separate tags endpoint.

gcx --context <stack> api
"/api/plugins/k6-app/resources/cloud/cloud/v5/test_runs/<run_id>/query_aggregate_k6(query='increase',metric='http_reqs')"


根据指标类型选择正确的查询方式至关重要——请查看`k6-manage/references/metrics.md`中的“查询方式”表格。对于浏览器测试，URL/状态的细分信息来自`labels` + `label/{name}/values`（metrics.md第4/5节），而非单独的标签端点。

Step 7: Fetch logs for a run

步骤7：获取运行实例的日志

Follow the Loki recipe in

k6-manage

§4 (

gcx api

against

/api/plugins/k6-app/resources/logs/...

{test_run_id="<id>"}

selector, mandatory

X-K6TestRun-Id

header, scope

start

end

run.created

run.ended

). Save the response to

/tmp/run_<id>_logs.json

and summarise from the file as described there.

遵循

k6-manage

第4节中的Loki操作指南（通过

gcx api

对接

/api/plugins/k6-app/resources/logs/...

，使用

{test_run_id="<id>"}

选择器，必须添加

X-K6TestRun-Id

请求头，将时间范围限定在

run.created

run.ended

之间）。将响应保存到

/tmp/run_<id>_logs.json

，并按照该指南中的说明从文件中提取摘要。

Step 8: (If asked) edit the script safely

步骤8：（若用户要求）安全编辑脚本

Use the full safe-edit recipe in

k6-manage

§5 (GET → backup → edit →

k6 inspect

→ 1-iter smoke → PUT with

Content-Type: application/octet-stream

→ sha256 verify).

When the edit involves thresholds, also read "Threshold semantics" below for the zero-observation trap, the

abortOnFail

cloud delay, and operator support (

==

!=

work despite docs).

使用

k6-manage

第5节中的完整安全编辑流程（GET → 备份 → 编辑 →

k6 inspect

→ 单次迭代冒烟测试 → 以

Content-Type: application/octet-stream

为请求头执行PUT → sha256校验）。

当编辑涉及阈值时，请同时阅读下文的“阈值语义”部分，了解零观测陷阱、

abortOnFail

云端延迟以及运算符支持（

==

!=

可正常使用，尽管文档中未提及）。

Step 9: Report

步骤9：生成报告

Pick a template based on the question shape.

For single-run investigations ("what's going on with run X"):

Test: <name> (id <test_id>)
Run:  <run_id> @ <created> → <ended>, load_zone=<zone>, result=<result>

Logs (<n> streams, <m> lines):
  - <stream summary>

Metrics (key indicators):
  - <metric>: <method> = <value> (n=<count>)
  ...

Per-check breakdown:
  - <check name>: <success_rate> (succ=<n>, fail=<n>)
  ...

Diagnosis: <one-paragraph>

For multi-run comparisons ("what's different between passing and failing runs", "did this change cause the failures"):

Question: <one-line restatement of what the user is trying to attribute>

Run timeline (relevant window):

| Run ID | Created (UTC) | Result | exec_duration | processing_duration | k6 build | error code | key check ratios |
|---|---|---|---|---|---|---|---|
| ... | ... | passed | 60s | 195s | <build> | — | 1.0/1.0/1.0 |
| ... | ... | failed | 27s | 193s | <build> | — | 0.0/n=0/n=0 |
| ... | ... | error  | 51s | 3601s aborted | <build> | 8016 | 1.0/1.0/1.0 |

Differences that matter:
  - <field>: <value-in-passing> vs <value-in-failing> — <interpretation>
  ...

Script diff (if relevant): <bundled-script diff between a representative passing and failing run, summarised>

Diagnosis: <one-paragraph attributing the change to test-side, SUT-side, or platform-side, with the supporting evidence>

The table makes side-by-side anomalies obvious (e.g. a column that's identical across passing and failing rules out that dimension as the cause; a column that flips between them is your candidate).

If the user asked for raw data dumps, also save them to

/tmp/k6inv/run<id>/

and tell them the paths.

根据用户的问题类型选择合适的模板。

针对单运行实例调查（“运行X发生了什么”）：

测试：<名称>（ID <test_id>）
运行实例：<run_id> @ <created> → <ended>，负载区域=<zone>，结果=<result>

日志（<n>个流，<m>行）：
  - <流摘要>

指标（关键指标）：
  - <指标>: <统计方法> = <数值>（样本数=<count>）
  ...

逐检查详情：
  - <检查名称>: <成功率>（成功=<n>，失败=<n>）
  ...

诊断结论：<一段文字>

针对多运行实例对比（“通过和失败的运行实例有什么不同”“这次变更是否导致了失败”）：

问题：<用户试图确认的问题的一行概括>

运行时间线（相关时间范围）：

| 运行ID | 创建时间（UTC） | 结果 | 执行时长 | 处理时长 | k6构建版本 | 错误码 | 关键检查成功率 |
|---|---|---|---|---|---|---|---|
| ... | ... | passed | 60s | 195s | <build> | — | 1.0/1.0/1.0 |
| ... | ... | failed | 27s | 193s | <build> | — | 0.0/n=0/n=0 |
| ... | ... | error  | 51s | 3601s aborted | <build> | 8016 | 1.0/1.0/1.0 |

关键差异：
  - <字段>: <通过运行的数值> vs <失败运行的数值> — <解读>
  ...

脚本差异（若相关）：<选取一个代表性的通过运行和失败运行的快照脚本差异，进行摘要>

诊断结论：<一段文字，将变更归因于测试端、被测系统端或平台端，并提供支持证据>

表格可以清晰展示并排的异常情况（例如，通过和失败运行中数值完全相同的字段可排除为原因；数值在二者间切换的字段是重点排查对象）。

如果用户要求原始数据导出，请将数据保存到

/tmp/k6inv/run<id>/

并告知用户路径。

Threshold semantics

阈值语义

Thresholds, not

check()

calls, are what determine a run's

result

. The behaviour has several non-obvious corners that mislead first-time investigators, so they're collected here. Step 5 ("Determine pass/fail status") and Step 8 ("edit the script safely") both depend on this section.

决定运行实例

result

的是阈值，而非

check()

调用。其行为存在一些不明显的细节，容易误导首次进行调查的人员，因此在此汇总。第5步（“判定通过/失败状态”）和第8步（“安全编辑脚本”）均依赖本节内容。

What

result

means

result

字段的含义

`result` value	Meaning
`passed`	All thresholds passed (or none defined)
`failed`	At least one threshold failed
`error`	Either the script crashed before finishing (e.g. browser wouldn't launch) or k6 Cloud aborted the run platform-side. To tell which, check `status_history[*].extra.code` on the run — a non-null code indicates a platform abort (e.g. `8016` = "Test run max lifetime exceeded" during `processing_metrics` ). Platform aborts are not your code's fault even though they surface as `error` .
`aborted`	User or system aborted the run

check()

calls do not affect

result

directly. They emit observations into the built-in

checks

rate metric, which a threshold may then evaluate. If no threshold references

checks

, failing checks are invisible to the run-level

result

`result` 值	含义
`passed`	所有阈值均通过（或未定义任何阈值）
`failed`	至少有一个阈值未通过
`error`	脚本在完成前崩溃（例如，浏览器无法启动）或k6 Cloud平台端终止了运行实例。要区分这两种情况，请检查运行实例的 `status_history[*].extra.code` 字段——非空代码表示平台端终止（例如， `8016` = “处理指标时超出测试运行最大生命周期”）。即使显示为 `error` ，平台端终止也并非代码问题导致。
`aborted`	用户或系统终止了运行实例

check()

调用不会直接影响

result

。它们会将观测数据发送到内置的

checks

比率指标，然后阈值会对该指标进行评估。如果没有阈值引用

checks

，失败的检查不会体现在运行级的

result

中。

The "zero observations = pass" trap

“零观测数据=通过”陷阱

k6 reports a threshold as ✓ pass when the underlying metric has zero samples — even if the threshold expression would otherwise evaluate to false:

checks{check:response is 200}
✓ 'rate==1.0' rate=0.00%       ← ✓ pass!?

This bites when the script throws before reaching the relevant

check()

call. Force a check observation in a

catch

block to make the threshold see something:

javascript

try {
  const r = await page.goto(URL);
  check(r, { "response is 200": x => x.status() === 200 });
  // ... rest of iteration body
  check(true, { "script completed without exception": () => true });
} catch (e) {
  console.error(e);
  check(null, { "script completed without exception": () => false });
} finally {
  await page.close();
}

Then add

'checks{check:script completed without exception}': ['rate==1.0']

to thresholds. This catches both navigation failures AND later-stage exceptions.

当底层指标没有样本数据时，k6会将阈值标记为✓通过——即使阈值表达式在正常情况下会评估为false：

checks{check:response is 200}
✓ 'rate==1.0' rate=0.00%       ← ✓ 通过？

当脚本在执行到相关

check()

调用前抛出异常时，就会出现这种情况。请在

catch

块中强制生成一个检查观测数据，让阈值能够获取到数据：

javascript

try {
  const r = await page.goto(URL);
  check(r, { "response is 200": x => x.status() === 200 });
  // ... 迭代体剩余部分
  check(true, { "脚本无异常完成": () => true });
} catch (e) {
  console.error(e);
  check(null, { "脚本无异常完成": () => false });
} finally {
  await page.close();
}

然后在阈值中添加

'checks{check:脚本无异常完成}': ['rate==1.0']

。这样可以同时捕获导航失败和后续阶段的异常。

abortOnFail

cloud delay

abortOnFail

云端延迟

When k6 runs in the cloud, thresholds are evaluated every 60 seconds. The
abortOnFail
feature may be delayed by up to 60 seconds.

For runs shorter than 60 s,

abortOnFail

may not fire before iterations complete naturally. The threshold is still evaluated at end-of-run and

result

flips to

failed

— abort just doesn't save execution time.

当k6在云端运行时，阈值每60秒评估一次。
abortOnFail
功能可能会延迟最多60秒触发。

对于时长不足60秒的运行实例，

abortOnFail

可能在迭代自然完成前无法触发。阈值仍会在运行结束时评估，

result

会切换为

failed

——只是终止操作无法节省执行时间。

Operators

运算符

Docs show

<=

>=

. ==
and
!=
also work even though they aren't in the docs. For

rate

metrics (value 0.00–1.00),

rate==1.0

means "every observation was non-zero" and

rate==0

means "all observations were zero."

文档中展示了

、

<=

、

>=

。==
和
!=
也可正常使用，尽管文档中未提及。对于比率指标（值为0.00–1.00），

rate==1.0

表示“所有观测数据均为非零”，

rate==0

表示“所有观测数据均为零”。

Workflow-specific gotchas

工作流专属陷阱

For the canonical gotcha list (auth expiry, doubled

cloud/cloud/

, 415 on script PUT, Loki missing

X-K6TestRun-Id

, script PUT not bumping

updated

gcx k6 runs list --limit 0

not following

@nextLink

), see

k6-manage

§7. The entries below are specific to this investigation workflow:

Symptom	Cause	Fix
"Latest run was 6 months ago" but schedule says daily	You didn't paginate `/test_runs`	Use the `@nextLink` loop in `k6-manage` §3 (Step 3)
"Last 7 days" report contains only old runs	Filtered by row count, not date	Re-filter by `created >= <iso_date>` (Step 4)
Threshold reports ✓ pass but checks fail	Zero check observations; iteration aborted before `check()` ran	See "Threshold semantics" above
`result: error` but the script logs/metrics look fine	Likely a platform abort (e.g. `processing_metrics` exceeded the 1h cap, `code 8016` ). The execution itself completed normally.	Check `status_history[*].extra.code` on the run. Non-null platform code → not your code's fault. See "Threshold semantics"
Investigating a past run by reading the current load-test script	Script may have been edited since the run executed — what you're reading isn't what ran	GET the run's bundled script via the per-run endpoint ( `k6-manage` §5) and diff against the current load-test script before drawing conclusions
Just overwrote the user's script	Invoked `update-script` to "see the URL"	Restore from the backup taken in Step 2. To learn URLs without writing, use `-vvv --log-http-payload` on any non-mutating command.
CLI `--iterations 1` breaks browser scenarios	Overrides scenario block entirely	Edit `iterations:` in-file with sed instead

关于标准陷阱列表（认证过期、重复的

cloud/cloud/

、脚本PUT请求返回415、Loki请求缺少

X-K6TestRun-Id

、脚本PUT未更新

updated

字段、

gcx k6 runs list --limit 0

不跟进

@nextLink

），请查看

k6-manage

第7节。以下是本调查工作流特有的陷阱：

症状	原因	解决方法
“最新运行是6个月前”但定时任务设置为每日执行	未对 `/test_runs` 进行分页	使用 `k6-manage` 第3节中的 `@nextLink` 循环方式（步骤3）
“最近7天”报告仅包含旧运行实例	按行数过滤而非按日期过滤	使用 `created >= <iso_date>` 重新过滤（步骤4）
阈值显示✓通过但检查失败	无检查观测数据；迭代在执行 `check()` 前终止	查看上文的“阈值语义”部分
`result: error` 但脚本日志/指标看起来正常	可能是平台端终止（例如， `processing_metrics` 超出1小时上限，错误码 `8016` ）。执行本身已正常完成。	检查运行实例的 `status_history[*].extra.code` 字段。非空平台错误码→并非代码问题导致。查看“阈值语义”部分
通过读取当前负载测试脚本分析过去的运行实例	脚本可能在运行实例执行后被编辑——你读取的并非实际运行的脚本	通过运行实例专属端点获取该运行的快照脚本（ `k6-manage` 第5节），并与当前负载测试脚本对比后再得出结论
刚刚覆盖了用户的脚本	调用 `update-script` 来“查看URL”	从步骤2中创建的备份恢复脚本。若要在不写入的情况下了解URL，请在任何非变更命令后添加 `-vvv --log-http-payload` 参数。
CLI参数 `--iterations 1` 破坏了浏览器场景	完全覆盖了场景配置块	使用sed在文件中编辑 `iterations:` 字段

Reference

参考资料

```
references/worked-example.md
```
— a synthetic investigation with realistic findings, useful as a template for the Step 9 report.

```
references/worked-example.md
```
— 一个带有真实调查结果的模拟案例，可作为步骤9报告的模板。

k6-cloud-investigate-test

Original

Translation

k6 Cloud test investigator

k6 Cloud测试调查工具

Core principles

核心原则

Prerequisites

前置条件

Investigation workflow

调查工作流

Step 1: Identify the test and target run(s)

步骤1：确定测试及目标运行实例

Step 2: Fetch test metadata and script

步骤2：获取测试元数据及脚本

Step 3: List runs WITH pagination

步骤3：列出所有运行实例（含分页）

Step 4: Verify date alignment with user's intent

步骤4：验证时间范围与用户意图一致

Step 5: Determine pass/fail status

步骤5：判定通过/失败状态

Step 6: Fetch metrics for a run

步骤6：获取运行实例的指标

6a. List metrics available for the run (metrics.md §1)

6a. 列出该运行实例可用的指标（metrics.md第1节）

6b. List labels for a metric to know what's available to filter/group by (metrics.md §4)

6b. 列出某个指标的标签，了解可用于过滤/分组的维度（metrics.md第4节）

6c. Time-series — pick a query method that matches the metric's type (metrics.md §6)

6c. 时间序列数据——根据指标类型选择合适的查询方式（metrics.md第6节）

6d. Scalar aggregate over the whole run (metrics.md §7)

6d. 整个运行周期内的标量聚合数据（metrics.md第7节）

Step 7: Fetch logs for a run

步骤7：获取运行实例的日志

Step 8: (If asked) edit the script safely

步骤8：（若用户要求）安全编辑脚本

Step 9: Report

步骤9：生成报告

Threshold semantics

阈值语义

What result means

result字段的含义

The "zero observations = pass" trap

“零观测数据=通过”陷阱

abortOnFail cloud delay

abortOnFail云端延迟

Operators

运算符

Workflow-specific gotchas

工作流专属陷阱

Reference

参考资料

What
`result`
means

`result`
字段的含义

`abortOnFail`
cloud delay

`abortOnFail`
云端延迟