k6 Load Testing: Architecture, Workload Models, and CI Gating

k6 is a Grafana-maintained load-testing tool that runs JavaScript or TypeScript test scripts on top of a Go execution engine. This article is for senior engineers who already know what load testing is and want a working mental model of how k6 generates load, what it measures, and where it fits in a CI/CD pipeline. By the end you should be able to choose between an open and closed workload model, write a test whose pass/fail is enforceable in CI, and know when k6 is the wrong tool.

TL;DR

• k6 is a single Go binary that embeds a pure-Go JavaScript runtime (Sobek, forked from goja in k6 v0.52.0). One process can sustain 30,000–40,000 VUs and ~300k RPS on a single machine before you need to fan out.
• Each Virtual User is a goroutine with its own Sobek runtime and event loop. There is no shared global state and no Node.js — fs, path, and npm modules are not available.
• Workload modelling separates what traffic looks like (open vs closed model, seven executors) from what behaviour you simulate (the test function). Open (arrival-rate) models avoid coordinated omission; closed (VU-based) models match fixed-pool, user-think-time scenarios.
• The metrics-and-thresholds pair is the CI gate: every metric is one of Counter, Gauge, Rate, or Trend, and any unmet threshold makes k6 run exit code 99.
• As of k6 1.0 (released 2025-05-08 at GrafanaCON) the project follows strict SemVer; TypeScript runs natively from v0.57, the browser module has been bundled into the core binary since v0.52 (the standalone xk6-browser repository was archived on 2025-01-30 once the migration completed by v0.56), and k6/net/grpc (stable since v0.49.0) plus the new global-event-loop k6/websockets are stable.

Mental model

Three abstractions explain almost everything k6 does:

1. Virtual User (VU) — a goroutine running an isolated JavaScript runtime. The default exported function is the iteration body; the VU runs it in a loop until the scenario ends.
2. Scenario — a named load profile that decides how many VUs run and when iterations start. Each scenario picks one executor and optionally an exec function and startTime.
3. Threshold — a per-metric SLO declared in options.thresholds. If any threshold fails, k6 run exits non-zero and the CI job fails.

Hold those three in your head and the rest of k6 — checks, tags, custom metrics, xk6 extensions — slots in around them.

Architecture: Go, goroutines, and the embedded JS runtime

Why Go and goroutines, not the JVM

Load generators that map each VU to an OS thread inherit the kernel’s per-thread cost. HotSpot JVM threads default to a 512 KB–1 MB stack (configurable via -Xss — the exact default is platform- and VM-dependent), so a JMeter instance comfortably runs around a thousand threads and then needs distributed mode to grow further¹.

Goroutines are user-space tasks scheduled by the Go runtime. They start with a ~2 KB stack that grows and shrinks on demand, so a single k6 process can hold tens of thousands of them with realistic per-VU memory budgets — Grafana cites roughly 100 KB per VU at scale². The practical headroom from those numbers, as of the v1.0 docs, is 30,000–40,000 VUs and ~300,000 RPS per machine before you need to fan out across load generators.

The embedded JavaScript runtime: Sobek (formerly goja)

k6 has never run on Node.js. Test scripts execute inside an embedded pure-Go ECMAScript runtime so the entire toolchain ships as one binary.

Practical implications of an embedded, non-Node runtime:

• The standard library is the k6 module set (k6/http, k6/check, k6/metrics, k6/data, k6/browser, …). Node-only modules like fs, path, crypto, child_process are not available.
• Browser-targeted JavaScript libraries usually work after bundling with Webpack or esbuild; anything that imports a Node built-in or a native add-on does not.
• File I/O is restricted to the open() helper in init context, which loads a file once into memory. Use SharedArray so the data isn’t copied per VU.

The per-VU event loop

Each VU has its own JavaScript runtime and its own event loop. There is no global event loop and no shared state across VUs⁴. The Go side coordinates with JS through a single contract: when a Go module starts an asynchronous operation (an HTTP request, a setTimeout, a Promise), it calls RegisterCallback() on the per-VU event loop and the loop will not consider the iteration complete until that callback has run.

Three properties fall out of this design:

• async/await and Promise work as expected, but only inside a single iteration. There is no cross-VU await.
• Background work that outlives an iteration (a forgotten setInterval, a never-resolved promise) blocks the iteration from finishing and inflates iteration_duration.
• Shared state across VUs is impossible by construction. SharedArray is the only escape hatch and it is read-only.

Your first script

1import http from "k6/http"2import { check, sleep } from "k6"34export const options = {5  vus: 5,6  duration: "30s",7  thresholds: {8    http_req_failed: ["rate<0.01"],9    http_req_duration: ["p(95)<500"],10  },11}1213export default function () {14  const res = http.get("https://test-api.k6.io/public/crocodiles/")15  check(res, { "status is 200": (r) => r.status === 200 })16  sleep(1)17}

1brew install k6           # macOS2docker pull grafana/k6    # container3k6 run hello.js

Three things to notice:

• options is parsed once before any VU starts; it cannot reference per-iteration state.
• The default-exported function is the iteration body, not the test entry point. k6 calls it many times per VU.
• Thresholds inside options make this a gated test — k6 run exits 99 if any threshold fails, which is enough for CI to mark the build red⁵.

Workload modelling: scenarios and executors

A k6 scenario attaches a load profile to one of seven executors. Two executor families exist; their difference is the most important architectural choice in a load test.

Closed model (VU-based)

You fix the number of VUs. Each VU runs the iteration body, then immediately runs it again. Throughput emerges from the VU count and the system’s response time — when the system slows down, throughput drops with it. This matches a “fixed pool of users repeatedly clicking around” scenario and naturally includes think-time via sleep().

Executors: constant-vus, ramping-vus, per-vu-iterations, shared-iterations.

1export const options = {2  stages: [3    { duration: "30s", target: 20 },4    { duration: "1m",  target: 20 },5    { duration: "30s", target: 0 },6  ],7}

Open model (arrival-rate)

You fix the iteration rate (e.g. 50 RPS). k6 starts a new iteration on schedule whether or not the previous one has finished, and scales VUs from a preAllocatedVUs pool up to maxVUs to keep the rate. VU count emerges from how slow the system is.

Executors: constant-arrival-rate, ramping-arrival-rate.

1export const options = {2  scenarios: {3    api: {4      executor: "constant-arrival-rate",5      rate: 50,6      timeUnit: "1s",7      duration: "2m",8      preAllocatedVUs: 20,9      maxVUs: 200,10    },11  },12}

The seven executors at a glance

Source: k6 docs — Executors.

Composing scenarios

A single test can run several scenarios in parallel or sequentially via startTime:

Show 2 hidden lines3export const options = {4  scenarios: {5    api_steady: {6      executor: "constant-arrival-rate",7      rate: 50, timeUnit: "1s", duration: "5m",8      preAllocatedVUs: 20, maxVUs: 100,9      exec: "hitApi",10    },11    web_ramp: {12      executor: "ramping-vus",13      startTime: "30s",14      startVUs: 0,15      stages: [16        { duration: "1m", target: 20 },17        { duration: "2m", target: 20 },18        { duration: "1m", target: 0 },19      ],20      exec: "browseUI",21    },22  },23}2425export function hitApi()  { http.get("https://test-api.k6.io/public/crocodiles/") }26export function browseUI(){ http.get("https://test.k6.io/") }

startTime, gracefulStop, exec, env, and tags are valid on every executor.

The five canonical test shapes

These are workload patterns, not k6 features — they are conventions for how to set the executor’s parameters to answer a specific business question. The ASCII shapes below are summaries; the k6 testing guides give the official definitions.

1export const options = {2  vus: 3, duration: "1m",3  thresholds: {4    http_req_failed: ["rate<0.01"],5    http_req_duration: ["p(95)<500"],6  },7}

1export const options = {2  scenarios: {3    avg: {4      executor: "ramping-arrival-rate",5      timeUnit: "1s",6      preAllocatedVUs: 50, maxVUs: 200,7      stages: [8        { duration: "5m",  target: 100 }, // ramp to 100 RPS9        { duration: "30m", target: 100 }, // hold10        { duration: "5m",  target: 0 },11      ],12    },13  },14  thresholds: {15    http_req_duration: ["p(95)<1000"],16    http_req_failed: ["rate<0.01"],17  },18}

1export const options = {2  scenarios: {3    spike: {4      executor: "ramping-arrival-rate",5      timeUnit: "1s",6      preAllocatedVUs: 200, maxVUs: 2000,7      stages: [8        { duration: "30s", target: 2000 }, // sharp burst9        { duration: "1m",  target: 2000 }, // hold10        { duration: "30s", target: 0 },11      ],12    },13  },14  thresholds: {15    http_req_failed: ["rate<0.10"],16  },17}

Metrics and thresholds: the CI gate

k6’s value as a CI tool comes from the metrics-and-thresholds loop, not from raw load generation. Every measurement — built-in or custom — is one of four metric types, and any threshold expression that is unsatisfied at the end of the test makes k6 run exit non-zero.

Built-in HTTP metrics

For an HTTP request, k6 emits seven timing metrics plus one rate metric, all in milliseconds⁷:

The decomposition is what makes k6 useful for diagnosing where latency comes from — a regression in http_req_tls_handshaking is a different bug from one in http_req_waiting.

The four metric types

1import http from "k6/http"2import { Trend, Rate, Counter } from "k6/metrics"3import { sleep } from "k6"45const checkoutDuration = new Trend("checkout_duration", true) // true → ms6const checkoutSuccess  = new Rate("checkout_success")7const checkoutCount    = new Counter("checkout_count")89export const options = {10  vus: 10,11  duration: "5m",12  thresholds: {13    "http_req_failed": ["rate<0.01"],14    "http_req_duration{endpoint:checkout}": ["p(95)<800"],15    "checkout_duration": ["p(95)<2000"],16    "checkout_success": ["rate>0.99"],17  },18}1920export default function () {21  const start = Date.now()22  const res = http.post("https://test-api.k6.io/checkout", null,23    { tags: { endpoint: "checkout" } })2425  checkoutDuration.add(Date.now() - start)26  checkoutSuccess.add(res.status === 200)27  checkoutCount.add(1)28  sleep(1)29}

Two non-obvious details:

• Tags partition metrics. http_req_duration{endpoint:checkout} is a separate aggregation from the global http_req_duration, and you can put thresholds on either. This is how you keep a fast endpoint’s SLO from being washed out by a slow one in the same test.
• checks is a Rate, not a fail counter. A failing check() does not fail the test on its own. Either gate checks with a threshold ('checks{tag:critical}': ['rate>0.99']) or use fail() explicitly when you want hard failures.

CI integration

GitHub Actions

Use the official grafana/setup-k6-action and grafana/run-k6-action — they replace the older “curl the release tarball” recipes that floated around before k6 1.0.

1name: Performance tests2on:3  pull_request:4    paths: ["src/**", "tests/perf/**"]5  push:6    branches: [main]78jobs:9  k6:10    runs-on: ubuntu-latest11    steps:12      - uses: actions/checkout@v413      - uses: grafana/setup-k6-action@v114      - uses: grafana/run-k6-action@v115        with:16          path: tests/perf/smoke.js17      - if: github.ref == 'refs/heads/main'18        uses: grafana/run-k6-action@v119        with:20          path: tests/perf/average-load.js

The job fails when any threshold fails (exit 99), so the gate is intrinsic — no extra “publish report and parse” step needed.

Other runners

• Jenkins: the same threshold-based exit code drives currentBuild.result = 'FAILURE'. Use the grafana/k6 Docker image for hermetic execution.
• GitLab CI: add image: grafana/k6:latest and run k6 run. Pipe --out json=results.json into a GitLab artifact for downstream analysis.
• Grafana Cloud k6: k6 cloud run script.js shifts execution to Grafana Cloud (formerly k6 Cloud / Load Impact) with the same script, useful when you need distributed load from clean network egress across global zones.

Distributed runs and output backends

A single k6 process is enough for almost every CI gate. Distributed execution and external metric stores show up when one of two things is true: the target needs more than ~40k VUs / ~300k RPS of generated load, or the team wants per-test results to land in the same observability stack as production telemetry.

Three ways to fan out

--execution-segment slices the workload deterministically across instances; e.g. --execution-segment "0:1/2" --execution-segment-sequence "0,1/2,1" runs the first half on one machine and the second half on another. Thresholds are evaluated per process unless every runner streams to the same backend (Cloud, Prometheus, or InfluxDB) where aggregation can re-evaluate over the merged stream⁸.

Output backends

The default k6 run summary is human-readable but discards per-iteration samples on exit. For trend analysis or distributed aggregation you stream samples to a real backend with --out.

Multiple --out flags are allowed on the same run, so a CI job can simultaneously emit JSON to a build artifact and stream Prometheus RW to Grafana Cloud.

Comparative analysis

When to pick what:

• k6 when the team writes JavaScript or TypeScript already, the SLO needs to be a CI gate, and you want a single binary on every runner.
• JMeter when an existing investment in .jmx plans, custom samplers, or Bzm cloud workflows outweighs migration cost.
• Gatling when the team is JVM-native and Scala / Kotlin DSLs are not a barrier; Gatling’s reports are still the prettiest in the category.
• Locust when the test logic is already a Python service-client and you want to reuse it.
• Artillery when the test definition is mostly YAML and you want managed Lambda / Fargate fan-out without operating Kubernetes.

Extending k6 with xk6

Out-of-the-box k6 1.x speaks HTTP/1.1, HTTP/2, WebSocket (k6/websockets, with a global event loop that lets one VU drive many sockets), gRPC (k6/net/grpc, stable since v0.49.0), browser (Chromium via CDP), and a handful of utility modules. Beyond that you compose a custom binary with xk6:

1# Build a k6 with Kafka and SQL extensions baked in2xk6 build --with github.com/grafana/xk6-kafka \3          --with github.com/grafana/xk6-sql

Two extension shapes exist:

• JavaScript extensions add new built-in modules (import kafka from "k6/x/kafka").
• Output extensions add --out targets — typically Elasticsearch, AWS Timestream, or in-house sinks. Prometheus Remote Write and the original xk6-browser are no longer extensions: both have been merged into the core binary.

Operational footguns

• Closed-model VUs when you wanted arrival-rate. The single most common k6 mistake: setting vus: 50, duration: "10m" to “simulate 50 users” when the real SLO is “hold 200 RPS”. As the SUT slows, throughput collapses and the histogram looks reassuringly flat — a textbook coordinated omission artefact. If the SLO is in RPS or P95 latency, use constant-arrival-rate or ramping-arrival-rate, full stop.
• No warm-up. The first 30–60 seconds of any non-trivial run are dominated by JIT, connection-pool fill, cold caches, and lazy DNS. Either ramp through them with a ramping-arrival-rate stage you intend to throw away, or scope thresholds to a sub-metric tagged after warm-up (http_req_duration{phase:steady}). Otherwise P95 carries the cold-start tail forever.
• Skipping response sanity checks. k6 run happily reports a 200-RPS test where every response is a 401 or a CDN error page — the transport is fine, your test is meaningless. Always combine check(res, { "status is 2xx": (r) => r.status >= 200 && r.status < 300 }) with a threshold on checks ('checks': ['rate>0.99']); without that, checks is a Rate metric whose failures do not fail the test on their own.
• Ephemeral port exhaustion. Tens of thousands of VUs against a small target IP set will exhaust the source-port range (default ~28k usable on stock Linux). Tune net.ipv4.ip_local_port_range and net.ipv4.tcp_tw_reuse, or split load across source IPs¹⁰.
• DNS as a hidden bottleneck. Per-iteration DNS lookups add latency that you will attribute to the SUT. Pre-resolve to an IP and pin it via --hosts, or set http.setResponseCallback and reuse the connection pool aggressively.
• SharedArray is JSON-deserialised once per VU. Reading a 100 MB CSV becomes a per-VU memory cliff. Pre-trim test data to what you actually use; reach for open() only for small fixtures.
• open() only works in init context. Call it at the top of the file, not inside the iteration body — the runtime throws if you try.
• The browser module is heavy. Each browser context launches a Chromium process. A single load generator can drive maybe 5–20 browsers, not 5,000 — model browser tests as functional + Web Vitals checks, not as load tests.

Practical defaults

• Always start with a smoke test (3 VUs, 1 minute, the same thresholds you intend to ship). If smoke is red, the script is broken, not the system.
• Default to arrival-rate executors for any test whose SLO is in RPS or P95 latency. Closed-model tests are fine for “fixed pool of users” simulations and almost nothing else.
• Three thresholds is the floor. http_req_failed, http_req_duration per critical endpoint, and checks per critical assertion.
• Tag everything. tags: { endpoint: "checkout" } on the request makes per-endpoint thresholds trivial and saves having to re-run the test to slice the data.
• Use SharedArray for any test data over 1 MB. Anything else is duplicated per VU.
• Run the gated test in CI on every PR. Run the average-load and soak tests on a schedule against a pre-prod environment with production-shaped data.

References

• k6 documentation home
• k6 release notes (v0.52.0 — Sobek)
• Grafana k6 1.0 launch post
• Running large tests
• Test types
• Open vs closed models
• Executors reference
• Thresholds
• HTTP-specific built-in metrics
• k6 vs JMeter benchmark
• xk6 build tool
• setup-k6-action and run-k6-action
• Running distributed tests and k6 Operator
• Results output reference (Prometheus RW, InfluxDB, JSON, CSV, Cloud)
• k6/net/grpc and k6/websockets module references