Grafana k6 入門:寫負載腳本,也讀懂測試結果
從 k6 安裝、HTTP 腳本、VU 與到達率,到檢查、門檻和具依賴保護的使用者旅程,釐清結果輸出與應用遙測的不同路徑。
Grafana k6 用程式碼定義負載,並記錄測試產生的工作與指標。引擎由 Go 實作,腳本使用 JavaScript,目前版本也支援 TypeScript,但不是在 Node.js 裡執行。能產生多少負載,取決於腳本、協定與施壓機資源,不能把某個 VU 數量當成所有環境的效能保證。
第一個測試就得說清楚什麼算成功。預設規則把 HTTP 302 視為預期回應,它仍可能不符合自己寫的「狀態碼為 200」檢查。VU 目標也不等於每秒請求數。要把結果當成 CI 門檻,需先分清這些口徑。
本文依官方文件整理,未執行 k6 負載測試或效能基準。介面和資料須由專案提供。k6 在 2021 年由 Grafana Labs 收購(英文),測試結果可經合適的儲存後端在 Grafana 呈現。
為什麼使用 k6
腳本可以進 Git、接受程式碼審查,也能在 CI 執行。不過這並非 k6 獨有:JMeter 可用非 GUI 模式,Locust 也採腳本方式。應比較語言、協定、執行模型與維護方式,不能把其他工具都視為只能手動點選。
k6 有自己的 JS/TS 執行環境,不能直接假定依賴 Node.js 內建 API 的套件可以使用。以下是協定層 HTTP 範例,不執行頁面 JavaScript 或繪製頁面;瀏覽器測試需要對應模組和另一份資源預算。
安裝與執行
將下文存為 script.js。執行前,把獲授權測試 API 的基底位址匯出為 BASE_URL,不包含查詢字串或片段。api.example.com 這類名稱只是說明,不是可直接施壓的公開服務。
# macOS 安裝
brew install k6
# 備妥 script.js 與已匯出的 BASE_URL 後在本機執行
k6 run script.js
# 或用 Docker:傳入已匯出的 BASE_URL,從標準輸入讀取腳本
docker run --rm -i -e BASE_URL grafana/k6:2.3.0 run - < script.js
Docker 範例固定使用已核對的 2.3.0 標籤;標籤不保證映像內容不變,需要時可用核對過的 digest 固定。-i 保留標準輸入以讀取腳本。其他本機檔案或相對路徑模組還需要掛載。Homebrew 安裝的版本可能不同,先以 k6 version 確認。安裝(英文) · 執行腳本(英文)
第一個腳本
import http from 'k6/http';
import { check, sleep } from 'k6';
if (!__ENV.BASE_URL) throw new Error('Set BASE_URL to an authorized test API');
const baseUrl = __ENV.BASE_URL.replace(/\/+$/, '');
export const options = {
vus: 20, // 20 個虛擬使用者,不是 20 RPS
duration: '30s', // 固定 VU 情境的執行時間
thresholds: {
http_req_failed: ['rate<0.01'],
http_req_duration: ['p(95)<500'],
checks: ['rate>0.99'],
},
};
export default function () {
const res = http.get(`${baseUrl}/users`);
check(res, {
'狀態碼為 200': (r) => r.status === 200,
'回應小於 500ms': (r) => r.timings.duration < 500,
});
sleep(1);
}
vus 與 duration 是固定 VU 情境的簡寫。每個 VU 反覆執行請求和 sleep,不代表固定 RPS;結束時間也受 graceful stop 等設定影響。/users 和回傳 200 的契約須由專案實作。
check 失敗會記錄結果,但本身不會讓程序以失敗碼結束,CI 判定要使用 thresholds。rate<0.01 要求失敗請求比例嚴格小於 1%,p(95)<500 要求耗時指標的 P95 嚴格小於 500ms;checks 的 rate>0.99 則要求兩項檢查合併後的通過率嚴格大於 99%,並非每項檢查各自達到 99%。若需逐項約束,要按檢查或請求標籤設定相應門檻。
http_req_failed 預設把 200–399 視為預期回應,和自訂的 status === 200 並不相同。未篩選的 http_req_duration 門檻涵蓋該指標的所有請求樣本,不只成功請求或某個介面;P95 也不是使用者比例。耗時是傳送、等待、接收的總和,不包含最初 DNS 查詢與連線建立等時間。
這些數值只是語法範例,不是通用 SLO。應在自己擁有或獲授權的隔離環境,先以少量 VU 確認資料與施壓機餘裕。一般 threshold 不是立即停止開關,提早中止須明確設定 abortOnFail 等機制;資源與費用限制還需要對應量測或外部控制。訂單案例應使用測試訂單與付款沙箱。檢查與門檻(英文) · 預期回應(英文)
讓 VU 數隨時間變化
stages 描述 VU 數量的變化。以下是取代前面 options 的另一份設定,不要在同一個腳本重複宣告,也不要直接疊加固定情境的 vus/duration 簡寫。
export const options = {
stages: [
{ duration: '2m', target: 100 }, // 2 分鐘內增加到 100 VU
{ duration: '5m', target: 100 }, // 維持 100 VU 5 分鐘
{ duration: '2m', target: 0 }, // 2 分鐘內降到 0 VU
],
};
target 是 VU 數,不是每秒請求。回應時間、每次迭代的請求數或思考時間改變時,即使 VU 相同,吞吐量也可能不同。可據此安排階段、尖峰(spike)與長時間浸泡(soak)等模式。這份取代設定未保留先前 thresholds,須按同一個測試目標加回所需門檻。Ramping VUs(英文)
使用者旅程:先擋住失敗後的相依操作
旅程適合測試跨介面的業務流程,單一 API 測試也能用來調查容量或回歸。以下為另一個獨立腳本,依示例專案契約編寫:登入接收 JSON user/pass,成功回傳 200 與字串 token;商品回傳含 sku 的陣列;測試訂單回傳 201 與字串 id。這些不是 k6 提供的公開 API,每個路徑及欄位都須對照專案調整。
除了 BASE_URL,還要提供 TEST_USER、TEST_PASS、TEST_SKU,Docker 也需明確傳入。範例只執行一次旅程;擴成並行負載前,應準備隔離帳戶、SKU 與測試資料。
import http from 'k6/http';
import { check, sleep } from 'k6';
const required = ['BASE_URL', 'TEST_USER', 'TEST_PASS', 'TEST_SKU'];
if (required.some((key) => !__ENV[key])) {
throw new Error('Set BASE_URL, TEST_USER, TEST_PASS, and TEST_SKU for your test API');
}
const baseUrl = __ENV.BASE_URL.replace(/\/+$/, '');
export const options = { vus: 1, iterations: 1, thresholds: { checks: ['rate==1'] } };
function jsonOrNull(response) {
try { return response.json(); } catch (_) { return null; }
}
export default function () {
const login = http.post(`${baseUrl}/login`, JSON.stringify({
user: __ENV.TEST_USER, pass: __ENV.TEST_PASS,
}), { headers: { 'Content-Type': 'application/json' } });
const loginBody = jsonOrNull(login);
const token = typeof loginBody?.token === 'string' ? loginBody.token : '';
if (!check(login, { '登入回傳 200 與 token': (r) => r.status === 200 && token.length > 0 })) {
sleep(1);
return;
}
const params = { headers: {
Authorization: `Bearer ${token}`, 'Content-Type': 'application/json',
} };
const products = http.get(`${baseUrl}/products`, params);
const catalog = jsonOrNull(products);
if (!check(products, { '商品清單含測試 SKU': (r) => r.status === 200
&& Array.isArray(catalog) && catalog.some((item) => item?.sku === __ENV.TEST_SKU) })) {
sleep(1);
return;
}
const order = http.post(`${baseUrl}/orders`, JSON.stringify({
sku: __ENV.TEST_SKU, qty: 1,
}), params);
const created = jsonOrNull(order);
check(order, { '測試訂單已建立': (r) => r.status === 201
&& typeof created?.id === 'string' && created.id.length > 0 });
sleep(2);
}
jsonOrNull 讓非 JSON 回應成為檢查失敗,避免在 token 解析時直接拋出例外。認證或商品檢查失敗就返回,不繼續送出相依的訂單,訂單本身也會檢查回應。這裡的 checks 門檻要求全部已執行檢查通過,但無法代替業務正確性、測試資料清理或吞吐目標的定義。
結果要看清楚統計對象
內建指標要分清請求、迭代與檢查:
| 指標 | 意義 |
|---|---|
http_req_duration |
HTTP 傳送、等待、接收的耗時分布,不含最初 DNS/連線時間;P90/P95 是請求樣本的分位數 |
http_req_failed |
依預期回應規則計算的失敗比例,不等於所有業務錯誤 |
vus / iterations |
目前活動 VU 數/累計迭代數;一次旅程可有多個請求,也可能提早返回 |
checks |
所有已執行檢查的通過率,與請求數、使用者數不是同一口徑 |
設定對應輸出與相容的儲存後端。例如目前文件中的實驗性 experimental-prometheus-rw,會把指標送往已設定的 Prometheus remote-write 接收端。Grafana 查詢該儲存後端做視覺化,並不是任意 --out 都能直接寫入的時序儲存。接收位址、驗證、TLS 與版本支援仍須一致。內建指標(英文) · Prometheus remote write(英文)
記錄每輪開始與結束時間、應用版本和測試識別碼,把延遲上升區間與應用日誌、資源指標對齊。若需拆解伺服器端呼叫,先替受測應用加入計測,依 OpenTelemetry 接入觀測雲(英文文件)設定收集,再查看同一視窗內已收集的下游 Span。這和 k6 結果輸出是兩條不同路徑。
k6 標籤不會自動成為日誌或 Span 欄位。傳遞測試識別碼需要約定的請求標頭和應用記錄方式;鏈路關聯還需核對上下文傳播、取樣、保留期限和權限,無法用未收集的鏈路重建整輪負載。
常見問題
如何與 JMeter、Locust 比較? 看腳本語言、協定支援與團隊經驗。k6 使用自己的 JS/TS 執行環境,Locust 用 Python,JMeter 可不經 GUI 執行。施壓效能應以同一情境評估,不能保證某個工具在所有腳本下都能承載更多 VU。
腳本一定要有 sleep 嗎? 取決於模型。模擬使用者工作階段時可能需要思考時間;到達率 executor 已控制迭代開始率,通常不在迭代末另加 sleep 來控制這個速率。每次迭代可能有多個 HTTP 請求,因此迭代到達率也不等於 HTTP RPS。VU 不代表固定 RPS,施壓機也可能成為瓶頸。
該選哪個測試環境? 優先使用接近正式環境的預備環境;直接對正式環境施壓,需要先評估風險、限制負載並準備中止方式。預備環境的資源、資料量或依賴不同,也不能把結果當成正式環境的容量保證。
官方參考
技術資料核對日期:2026 年 11 月 5 日。示例映像為 2.3.0,更新時應重新核對執行行為與輸出支援。
