Load Testing Fundamentals with k6

1. 1

   A target to test

   Any HTTP service works. Grafana's QuickPizza demo app has a fast home page and a heavier recommendation API so you can see the difference.

   terminalcopy cmd

   $ docker run -d --name target -p 3333:3333 ghcr.io/grafana/quickpizza-local:latest

   curl -s -o /dev/null -w '%{http_code} %{time_total}s\n' localhost:3333/

   ── expected output ──

   200 0.004s

2. 2

   Write a k6 test with stages and thresholds

   k6 scripts are JavaScript, but the engine is Go (no Node.js), and one machine can generate thousands of requests per second. The ramping-arrival-rate executor is an OPEN model. Thresholds make the run fail (non-zero exit code) when SLO-like targets are missed.

   import http from "k6/http";
   import { check, sleep } from "k6";
   
   export const options = {
     scenarios: {
       shoppers: {
         executor: "ramping-arrival-rate",
         startRate: 10, timeUnit: "1s",
         preAllocatedVUs: 50, maxVUs: 500,
         stages: [
           { target: 50,  duration: "1m" },   // warm up
           { target: 200, duration: "3m" },   // expected peak
           { target: 400, duration: "2m" },   // 2x peak: find the knee
           { target: 0,   duration: "30s" },
         ],
       },
     },
     thresholds: {
       http_req_failed:   ["rate<0.01"],               // < 1% errors
       http_req_duration: ["p(95)<300", "p(99)<800"],  // ms
       "http_req_duration{name:recommend}": ["p(95)<500"],
     },
   };
   
   const BASE = __ENV.BASE_URL || "http://localhost:3333";
   
   export default function () {
     const home = http.get(`${BASE}/`, { tags: { name: "home" } });
     check(home, { "home 200": (r) => r.status === 200 });
   
     const rec = http.post(`${BASE}/api/pizza`, JSON.stringify({ maxCaloriesPerSlice: 1000 }), {
       headers: { "Content-Type": "application/json", Authorization: "token abcdef0123456789" },
       tags: { name: "recommend" },
     });
     check(rec, { "recommend 200": (r) => r.status === 200 });
     sleep(Math.random() * 2);        // think time
   }

3. 3

   Run it and read the summary

   Look at p95/p99 per tagged request, the failure rate, and dropped_iterations: if k6 couldn't start iterations at the requested rate (not enough VUs), the system is already saturated.

   terminalcopy cmd

   $ k6 run loadtest.js

   ── expected output ──

   █ THRESHOLDS

   http_req_duration

   ✓ 'p(95)<300' p(95)=212.4ms

   ✗ 'p(99)<800' p(99)=1.31s

   http_req_duration{name:recommend}

   ✗ 'p(95)<500' p(95)=742.8ms

   http_req_failed

   ✓ 'rate<0.01' rate=0.42%

    

   █ TOTAL RESULTS

   checks.........................: 99.58% 118412 out of 118912

   http_reqs......................: 118912 297.4/s

   dropped_iterations.............: 1843 4.6/s

   ERRO[0391] thresholds on metrics 'http_req_duration, http_req_duration{name:recommend}' have been crossed

4. 4

   Stream results to Prometheus and Grafana

   Correlate load with resource graphs by sending k6 metrics to Prometheus (remote write) and viewing them next to your service dashboards (Observability course).

   terminalcopy cmd

   $ K6_PROMETHEUS_RW_SERVER_URL=http://localhost:9090/api/v1/write k6 run -o experimental-prometheus-rw loadtest.js

5. 5

   Gate CI on the thresholds

   The job fails when thresholds fail. Keep CI runs short (1–2 minutes at modest load) and run big tests on a schedule.

   name: perf-smoke
   on: [pull_request]
   jobs:
     k6:
       runs-on: ubuntu-latest
       steps:
         - uses: actions/checkout@v5
         - uses: grafana/setup-k6-action@v1
         - uses: grafana/run-k6-action@v1
           env:
             BASE_URL: ${{ vars.PREVIEW_URL }}
           with:
             path: tests/perf/smoke.js

Each drill is a real failure mode. Read the scenario and the output, decide what's wrong, then reveal the diagnosis.