Skip to content
Tutorials Center
My learning

Topics

Lesson 12 of 36 ยท Checks and Thresholds

Thresholds: Pass or Fail Your Load Test

Define pass/fail criteria with k6 thresholds, write conditions on trends, rates, counters and gauges, filter by tags, abort early with abortOnFail, and use the exit code in CI.

A load test without pass/fail criteria is just a report that someone has to read. Thresholds make the test self-judging: you declare what "good enough" means, and k6 evaluates it at the end (or continuously) and exits with a non-zero code when you miss. This is what lets a CI pipeline block a deploy that made the API slower. Thresholds are how you encode service level objectives (SLOs) such as "99% of requests succeed and 95% finish within 300 ms".

Writing a threshold

Thresholds live in options.thresholds. Each key is a metric name, each value is a list of conditions written as strings:

JavaScript
export const options = {
  thresholds: {
    http_req_failed: ['rate<0.01'],          // less than 1% errors
    http_req_duration: ['p(95)<300', 'p(99)<800'], // two conditions
    checks: ['rate>0.99'],
  },
};

All conditions on a metric must hold for the threshold to pass. If any fails, k6 marks the test as failed: the summary shows a red cross next to the metric, and the process exits with code 99.

The aggregation methods depend on the metric type

k6 has four metric types, and each offers different aggregations:

Type Examples Aggregations you can use
Counter http_reqs, iterations count, rate
Gauge vus value
Rate http_req_failed, checks rate
Trend http_req_duration, iteration_duration avg, min, max, med, p(N)

The comparison operators are <, <=, >, >=, == and !=. Examples:

JavaScript
thresholds: {
  http_reqs: ['count>1000'],               // at least 1000 requests
  iterations: ['rate>10'],                  // more than 10 iterations per second
  http_req_duration: ['avg<200', 'max<2000', 'med<150', 'p(90)<250'],
  vus: ['value<=50'],
}

Percentiles are written p(95), p(99.9) and so on. Using a trend aggregation on a counter, or rate on a trend, is a configuration error and k6 refuses to start, which is a good early warning.

Thresholds on tagged sub-metrics

Combine thresholds with tags to hold different endpoints to different standards:

JavaScript
export const options = {
  thresholds: {
    'http_req_duration{name:Home}': ['p(95)<200'],
    'http_req_duration{name:Checkout}': ['p(95)<1000'],
    'http_req_failed{status:500}': ['rate==0'],
    'checks{endpoint:login}': ['rate>0.999'],
  },
};

A sub-metric only exists if at least one data point has the tag. If a threshold names a sub-metric that no request creates, it is evaluated on an empty set and may pass trivially, so always confirm that the sub-metric appears in the summary.

abortOnFail

By default k6 finishes the whole run and then evaluates thresholds. When a system is clearly failing, continuing to hammer it wastes time and money. Use the object form to stop early:

JavaScript
thresholds: {
  http_req_failed: [
    { threshold: 'rate<0.05', abortOnFail: true, delayAbortEval: '10s' },
  ],
},

abortOnFail: true ends the test as soon as the condition is violated. delayAbortEval waits a while first, which stops a noisy start (cold caches, a handful of early errors) from aborting too soon. This pattern is the heart of a breakpoint test: keep ramping until the threshold breaks, then stop.

Using the exit code

Terminal
k6 run script.js
echo $?   # 0 = all thresholds passed, 99 = a threshold failed

Other non-zero codes mean different things (for example, 107 for a script error, 108 for a timeout), so scripts and CI systems can tell "performance regression" from "broken test". In CI you normally do nothing special: the job fails because the command returned non-zero. See CI chapters later for pipelines.

Choosing good thresholds

  • Start from your SLO, not from today's numbers. If users need responses in 400 ms, write p(95)<400 even if you currently achieve 150 ms.
  • Use percentiles, not averages, for latency (see Reading the Summary).
  • Always include an error-rate threshold. A test with only latency thresholds passes happily when every request returns a fast 500.
  • Add a checks threshold so incorrect responses count.
  • Keep it stable. A threshold that flaps between runs trains people to ignore failures. Run the baseline several times and leave headroom.

A stand-in threshold evaluator

The program below is not k6. It parses threshold strings of the form p(95)<300, rate<0.01 and count>5, evaluates them against collected samples, and prints a verdict with an exit-code-style result. It is useful to see exactly what k6 does conceptually when it reads your options.

Node.js Stand-in: evaluate thresholds like k6

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The single 480 ms request pushes p(95) to 480 and fails that condition, and the 10% error rate fails rate<0.05, so the pretend run exits with 99. One slow request in ten is enough to fail the p(95) threshold, which shows how strict percentile thresholds are on small samples.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What exit code does k6 return when a threshold fails?

    Exit code 99 means the test ran but at least one threshold failed. 0 means all passed.
  2. 2. Which condition is valid for the trend metric http_req_duration?

    Trend metrics support avg, min, max, med and percentiles such as p(95).
  3. 3. What does abortOnFail: true do?

    It aborts the run on violation; delayAbortEval postpones the first evaluation to avoid noisy starts.
  4. 4. Why should a latency-only threshold set not be your only protection?

    Failing requests are often quick, so latency alone can look healthy while everything is broken.

Summary

  • Thresholds are pass/fail rules in options.thresholds; failing ones make k6 exit with code 99.
  • Match the aggregation to the metric type: counters (count, rate), gauges (value), rates (rate), trends (avg, med, p(N)).
  • Filter with tags: http_req_duration{name:Checkout}.
  • Use abortOnFail with delayAbortEval to stop a failing run early.
  • Combine latency, error-rate and checks thresholds, and base them on SLOs.

Next: Custom Metrics