Load Testing Node.js APIs with k6 and Grafana Dashboards

Every API I ship eventually gets asked the same question in an incident review: how many concurrent users can it actually take before it falls over? Guessing is not an answer. Load testing turns that guess into a number you can defend, and k6 is the tool I reach for because the tests are plain JavaScript, they run from the command line, and they fail a CI pipeline the moment performance regresses.

k6 is an open-source load-testing tool maintained by Grafana Labs. You write a script that describes what one virtual user does, tell k6 how many virtual users to run and for how long, and it replays that behaviour under load while recording latency, throughput, and error rate. In this post I walk through writing a test, gating a pipeline on thresholds, choosing the right test profile, streaming results to Grafana, and using all of that to find the point where a database connection pool becomes the bottleneck.

Writing a k6 test: virtual users and stages

A k6 script has two parts: an exported options object that configures the run, and a default function that is the code each virtual user executes in a loop. A virtual user, or VU, is one simulated concurrent client. The options object is where you decide how many VUs run and how the count changes over time.

The stages array is the most useful way to shape a run. Each entry is a target VU count and a duration, and k6 ramps the active VU count linearly toward that target over that period. It is a shortcut for the ramping-VUs executor. The script below warms up to 50 VUs, holds, pushes to 100, holds again, then ramps back down.

import http from 'k6/http';
import { check, sleep } from 'k6';

export const options = {
  // A ramping-VUs profile: warm up, hold, push higher, ramp down.
  stages: [
    { duration: '1m', target: 50 },
    { duration: '3m', target: 50 },
    { duration: '1m', target: 100 },
    { duration: '3m', target: 100 },
    { duration: '1m', target: 0 },
  ],
  // Thresholds are the pass/fail contract. Any breach = non-zero exit.
  thresholds: {
    http_req_failed: ['rate<0.01'],            // < 1% of requests may error
    http_req_duration: ['p(95)<300', 'p(99)<800'], // ms
    checks: ['rate>0.99'],                     // > 99% of checks must pass
  },
};

export default function () {
  const res = http.get('https://api.example.com/orders');
  check(res, {
    'status is 200': (r) => r.status === 200,
    'body is not empty': (r) => r.body.length > 0,
  });
  sleep(1);
}

Inside the default function, http.get fires the request and check runs assertions against the response. Checks never fail the test on their own; they only record a pass or fail rate. The sleep call models think time between requests so the VUs behave a little more like real users instead of a tight hammering loop.

Thresholds: turning a run into a CI pass or fail gate

Thresholds are what make k6 useful in a pipeline. Each threshold is an expression over a metric that must hold at the end of the run; if it evaluates to false, k6 exits with a non-zero code and the pipeline step fails. The expression follows an aggregation, operator, value shape — for example a 95th-percentile latency below a limit, or an error rate below a ceiling. The metrics I gate on most often are these three.

• http_req_duration with p(95) under 300 and p(99) under 800 milliseconds — the request latency percentiles that users actually feel.
• http_req_failed with rate under 0.01 — the share of requests that errored, capped here at one percent.
• checks with rate above 0.99 — the pass rate of your own assertions, so a build fails if responses stop being correct under load.

By default a threshold is only evaluated once, at the end of the test. Add abortOnFail to a threshold and k6 stops the run the instant it is breached, which saves minutes on an obviously failing build; delayAbortEval gives the run a grace period to collect data before enforcement kicks in. Because a failed threshold is a non-zero exit code, no extra glue is needed — GitHub Actions, GitLab CI, or Jenkins already treat that as a failed step.

Smoke, load, stress, soak, and spike: pick the right profile

The same script becomes a different test depending on how you set the VUs and duration. Grafana documents a small family of test types, each answering a different question. I keep a smoke test in every pipeline and run the heavier profiles on a schedule or before a big release.

Streaming results to Prometheus and Grafana

k6 prints a summary when a run ends, but the interesting story is what happens during the run. The experimental Prometheus remote-write output streams every metric to a Prometheus instance in real time, so you can watch latency climb live on a Grafana dashboard. You point k6 at a remote-write endpoint with an environment variable and add the output flag.

# Point k6 at a Prometheus endpoint that accepts remote write.
# Default target is http://localhost:9090/api/v1/write
export K6_PROMETHEUS_RW_SERVER_URL=http://localhost:9090/api/v1/write

# Ship percentiles, not just the p(99) default, so dashboards are useful.
export K6_PROMETHEUS_RW_TREND_STATS="p(95),p(99),min,max"

# Stream every metric to Prometheus in real time as the test runs.
k6 run -o experimental-prometheus-rw load-test.js

By default k6 sends only the p(99) for trend metrics; setting K6_PROMETHEUS_RW_TREND_STATS to a list like p(95),p(99),min,max ships the percentiles a dashboard needs. Grafana Labs publishes ready-made k6 Prometheus dashboards you can import, so you get panels for request rate, error rate, and latency percentiles without building them by hand. For the highest fidelity you can enable native histograms, which requires a recent Prometheus with that feature turned on.

Finding the database connection-pool ceiling

This is where load testing earns its keep. A Node.js API usually talks to its database through a fixed-size connection pool. Below the pool size, extra concurrency mostly just uses idle connections and latency stays flat. Once concurrent in-flight queries exceed the pool, new requests queue waiting for a free connection, and that queue time shows up as a sharp, sudden climb in p(95) and p(99) — even though CPU and error rate still look fine.

A stress or breakpoint profile makes that ceiling visible. Ramp VUs steadily upward and watch the latency percentiles on the Grafana dashboard: the knee in the curve, where latency turns from flat to a steep line while throughput stops rising, is your pool ceiling. From there you either raise the pool size, add read replicas, or shorten the queries — but now the decision is driven by a measured breaking point, not a hunch. The database, not k6 or Node, is usually the real limit.

How I put it together

My rule of thumb: a smoke test on every pull request as a fast gate, a load test with real thresholds before each release, and an occasional soak or stress run streamed to Grafana when I need to size infrastructure. The script barely changes between them — only the VUs, duration, and thresholds do. Start with one endpoint, gate it on a p(95) threshold, and let a red pipeline teach you where your API actually breaks.