Using k6 Thresholds to Automate SLA Validation in Load Tests

Problem: manual SLA checks slow down CI pipelines

When you run a load test, you often need to decide whether the result meets your service‑level agreement. Manually scanning the k6 output for response‑time percentiles or error rates is tedious and error‑prone, especially when the test is part of an automated pipeline that should fail fast on regression.

Thesis: k6 thresholds turn SLA rules into first‑class test assertions

By declaring thresholds directly in the test script, you let k6 evaluate the pass/fail condition at runtime, emit a clear PASS/FAIL flag in the end‑of‑test summary, and return an appropriate exit code. This makes the test self‑validating and suitable for gating CI/CD stages.

How thresholds work in k6

A threshold is a JavaScript object attached to the options block of a script. Each key is a metric name (e.g., http_req_duration) and the value is an array of expressions. Expressions use built‑in functions:

• p(percentile) – value at the given percentile
• max, min – extreme values
• count – number of samples
• rate – proportion of samples that are truthy (often used for error rates)

If any expression evaluates to false, the whole test is considered failed. k6 prints a summary line like thresholds ✓ http_req_duration... PASS or ✗ ... FAIL and exits with code 0 for PASS or 1 for FAIL.

Worked example: validating a 95th‑percentile latency SLA

Suppose you have an endpoint https://api.example.com/health and you want to assert that 95 % of requests finish under 200 ms.

1. Create a file latency-test.js:

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

export const options = {
  thresholds: {
    // 95th percentile of request duration must be < 200 ms
    http_req_duration: ['p(95)<200'],
  },
};

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

1. Run the test from a machine where k6 is installed (no special privileges needed):

k6 run latency-test.js

If the observed 95th‑percentile latency is below 200 ms, the terminal will end with:

....
thresholds     ✓  http_req_duration... PASS

and the process will exit with code 0. If the latency exceeds the bound, you will see:

....
thresholds     ✗  http_req_duration... FAIL

and the exit code will be 1.

Trade‑offs and limitations

• Numeric‑only metrics: thresholds can only be applied to metrics that yield numbers. Trying to use a string tag (e.g., a URL label) inside a threshold expression will throw a runtime error.
• Undefined metrics cause failure: If a threshold references a metric that never receives a sample (for example, a URL that gets no requests during the test), k6 treats the metric as undefined and the threshold fails. This can be misleading for sparsely exercised endpoints; you can guard against it by ensuring the metric is sampled or by using a rate threshold that tolerates zero samples.
• No mixed‑type logic in a single expression: You cannot write something like p(95)<200 && rate<0.01 inside one array entry. Each threshold entry must contain a homogeneous expression; combine multiple criteria by adding separate entries to the array.

These constraints mean you should design your threshold list carefully, verify that each referenced metric is actually generated, and keep each expression simple enough to read at a glance.

Actionable closing

To start using thresholds in your own pipelines:

1. Identify the SLA you want to enforce (latency, error rate, throughput).
2. Add a thresholds block to options with the appropriate metric and expression.
3. Commit the script and invoke k6 run in your CI step; treat a non‑zero exit code as a failure.
4. Monitor the summary output for the PASS/FAIL flag to quickly see which SLA component caused a regression.

With thresholds in place, your load tests become self‑checking gates, reducing manual inspection and giving you fast, reliable feedback on performance changes.