Establishing a baseline on Grafana Labs

Establishing a baseline

Fri, 05 Jun 2026 12:46:32 -0400

Establishing a baseline

What you learned in Module 2:

How k6 runs your test (virtual users, iterations, three script parts)
How to install k6, write a script, and run it locally
How to send the same run to Grafana Cloud k6 for stored results and dashboards
Which built-in metrics k6 reports and when to lean on local vs cloud execution

What you’ll do in this module:

What is a baseline? — Why it comes before stress, spike, and soak
Key baseline metrics — Latency, throughput, errors, and check pass rate
Designing a load profile — Stages and ramping
Checks vs thresholds — Per-response correctness vs whole-run pass or fail
Results to thresholds — Set thresholds from what you measured
When thresholds fail — Terminal output, exit codes, and regression patterns
Establish a baseline learning path — The hands-on path
Baseline complete — Debrief and what carries into the wrap-up

Estimated time: 20-25 minutes

The baseline methodology

Fri, 05 Jun 2026 12:46:32 -0400

Scenario

A change passes functional tests and feels fine when you click through alone, but the p95 you care about was never written down. Under dozens of concurrent users, the same build might already be slow or noisy; you would not know until a release or an incident. A baseline turns “it felt OK” into numbers you can compare next week.

The baseline workflow

Step	What you do	What it produces
1. Observe	Run without thresholds at realistic load	Actual p95, error rate, throughput
2. Set	Add thresholds based on observed values + headroom	Script with pass/fail criteria
3. Validate	Re-run with thresholds, confirm consistency	Working quality gate

Why this order matters

Observe before you set thresholds. Use measured values. Guesses drift and break trust in the gate.
Validate before you wire CI. Stable thresholds first. Flaky gates waste the whole team’s time.
Leave headroom on p95. A gap between what you saw and the limit absorbs normal jitter. It still catches real regressions.

The shift

Before baselines	After baselines
“The results looked okay to me”	The test passed with exit code 0
Someone reviews metrics manually	CI/CD decides automatically
Regressions found in production	Regressions blocked at merge

Reading k6 output

Fri, 05 Jun 2026 12:46:32 -0400

What “good” looks like in the summary

Thresholds section shows your gate first; every line should be green before you trust CI with the script.
p95 on http_req_duration is stable across two runs at the same profile (small drift is normal; wild swings mean the profile or environment is not ready).
http_req_failed stays at zero or inside your agreed budget; mystery 4xx or 5xx under steady load deserve a check or environment fix before you tighten thresholds.
Checks reflect a real success condition, not only “HTTP 200.”

Sample k6 terminal output

The block below matches the k6 v1 end-of-test summary layout (thresholds first, then grouped totals). Layout and labels can change between versions; for section order, --summary-mode, and other options, refer to End-of-test summary in the k6 documentation.

  █ THRESHOLDS

    http_req_duration
    ✓ 'p(95)<1500' p(95)=148.21ms
    ✓ 'p(90)<2000' p(90)=146.88ms

    http_req_failed
    ✓ 'rate<0.01' rate=0.00%


  █ TOTAL RESULTS

    checks_total.......................: 90      13.122179/s
    checks_succeeded...................: 100.00% 90 out of 90
    checks_failed......................: 0.00%   0 out of 90

    ✓ status is 200
    ✓ body is not empty

    CUSTOM
    custom_waiting_time................: avg=152.355556 min=120      med=141      max=684      p(90)=147.2    p(95)=148.8

    HTTP
    http_req_duration..................: avg=140.36ms   min=119.08ms med=140.96ms max=154.63ms p(90)=146.88ms p(95)=148.21ms
      { expected_response:true }.......: avg=140.36ms   min=119.08ms med=140.96ms max=154.63ms p(90)=146.88ms p(95)=148.21ms
    http_req_failed....................: 0.00%  0 out of 45
    http_reqs..........................: 45     6.56109/s

    EXECUTION
    iteration_duration.................: avg=152.38ms   min=119.37ms med=141.27ms max=684.62ms p(90)=147.11ms p(95)=148.39ms
    iterations.........................: 45     6.56109/s
    vus................................: 1      min=1       max=1
    vus_max............................: 1      min=1       max=1

    NETWORK
    data_received......................: 519 kB 76 kB/s
    data_sent..........................: 4.9 kB 718 B/s

Where to look

Values in the Example column are taken from the sample summary above so the table stays internally consistent.

What you need	Where to find it	Example from sample
Latency (p95)	`http_req_duration` → `p(95)`	148.21 ms
Throughput	`http_reqs` → numeric rate before `/s` on that line (here `6.56109/s`)	6.56109/s
Error rate	`http_req_failed` → percentage	0.00%
Check pass rate	`checks_succeeded` / `checks_total` (summary layout varies by version)	100.00% (90 of 90)
VU count	`vus`	1

Reading threshold results

When thresholds are set, each one shows a verdict:

  █ THRESHOLDS

    http_req_duration
    ✓ 'p(95)<1500' p(95)=148.21ms
    ✓ 'p(90)<2000' p(90)=146.88ms

    http_req_failed
    ✓ 'rate<0.01' rate=0.00%

✓ (check mark) means the threshold passed. ✗ (X) means the threshold was breached (exit code 99).

What the numbers mean together

Read one run through three lenses. You almost never trust a single number alone.

Lens	Ask
Latency (p95)	Are responses getting slower over time?
Throughput	Does request rate keep up with how many VUs you added?
Correctness	Are HTTP failures or check failures climbing?

Four common stories (heuristics for HTTP tests at steady VUs, not guarantees):

If you see…	Often means…
p95 steady and low, throughput matches your ramp, errors near zero	The system looks healthy at this load.
p95 climbs while VUs stay flat and throughput stalls or falls	Work is backing up (responses slower, queueing, or saturation).
Errors or failed checks rise while p95 stays low	Answers are wrong or rejected even when they arrive fast. Reread checks and response bodies.
Throughput drops with the same VU count	Each request is costing more time somewhere (network, app, or dependencies). Pair with `http_req_duration` trends.

Designing a realistic load profile

Fri, 05 Jun 2026 12:46:32 -0400

Load profile shape

A baseline load profile has three phases.

Phase	Purpose	Duration
Ramp-up	Gradually increase VUs to avoid cold-start spikes	30 seconds to 1 minute
Steady state	Hold at target load to collect stable metrics	1-2 minutes minimum
Ramp-down	Reduce VUs back to zero for clean shutdown	30 seconds

Scenarios, executors, and stages

k6 uses scenarios to describe how a test runs. Each scenario picks an executor that schedules virtual users or iteration rate. The ramping-vus executor changes the target number of VUs over time using a stages array, which matches the ramp-up, steady-state, and ramp-down idea above.

Putting stages on the root options object is a shortcut for a single scenario that uses the ramping-vus executor. For several traffic shapes in one script, or when you want scenario names in results, configure the scenarios object explicitly instead.

Example: shortcut with `stages`

export const options = {
  stages: [
    { duration: '30s', target: 20 },  // ramp up
    { duration: '1m',  target: 20 },  // steady state
    { duration: '30s', target: 0 },   // ramp down
  ],
};

Example: explicit scenario with `ramping-vus`

export const options = {
  scenarios: {
    baseline: {
      executor: 'ramping-vus',
      stages: [
        { duration: '30s', target: 20 },
        { duration: '1m',  target: 20 },
        { duration: '30s', target: 0 },
      ],
    },
  },
};

Choosing your VU count

Match VUs to observed or expected concurrency for the traffic slice you are baselining, not an arbitrary round number. If you do not yet have production metrics, start from staging access logs or product assumptions, then adjust after you see stable http_req_duration and error rate in the steady-state window.

If your profile uses ramping-vus, the target in each stage is the number of VUs k6 tries to schedule; combined with iteration time, that determines how much load you actually generate. For a deliberately constant request rate instead, you would pick an arrival-rate executor; refer to API load testing: request rate. This course stays on ramping VUs because it matches the baseline paths you run next.

A baseline measures normal behavior; deliberately exceeding your production concurrency belongs in stress or load-test scenarios covered in the k6 test types guide after you have a baseline.

Checks vs thresholds

Fri, 05 Jun 2026 12:46:32 -0400

Two layers of validation

Checks: per-request correctness

Checks are assertions that validate each response. They don’t stop the test on failure.

check(res, {
  'status is 200': (r) => r.status === 200,
  'body is not empty': (r) => r.body.length > 0,
});

Thresholds: whole-test pass/fail

Thresholds are pass/fail criteria for the entire test. They evaluate aggregate metrics.

thresholds: {
  http_req_duration: ['p(95)<500'],
  http_req_failed: ['rate<0.01'],
  checks: ['rate>0.99'],
}

How they work together

Layer	Scope	On failure
Checks	Each request	Records failure, test continues
Thresholds	Entire test	Test exits with non-zero code (fails CI/CD)

From results to thresholds

Fri, 05 Jun 2026 12:46:32 -0400

Choosing threshold values

Start with your observed values and add headroom for normal variation:

Metric	Observed	Threshold	Headroom
p95 latency	320 ms	`p(95)<500`	~55% above observed
Error rate	0%	`rate<0.01`	Allows up to 1%
Check pass rate	100%	`rate>0.99`	Allows up to 1% failure

Trade-offs in threshold decisions

Threshold-setting involves judgment, not just formulas. Consider these trade-offs for your system:

Decision	Tighter threshold	Looser threshold
Headroom	Catches small regressions early	Avoids false failures from normal variation
p95 vs p99	p95 reflects most users’ experience	p99 catches tail latency affecting your slowest users
Error tolerance	`rate<0.001` is strict, good for payment flows	`rate<0.01` is practical for non-critical endpoints

A common starting approach: use p95 with 30-50% headroom for general APIs. Switch to p99 with tighter headroom for latency-sensitive paths like checkout or authentication.

When thresholds fail

Fri, 05 Jun 2026 12:46:32 -0400

Failure signals in the terminal

✓ passed that line; ✗ failed the threshold on that line.

When all thresholds pass:

✓ http_req_duration..............: avg=186ms  p(95)=312ms
✓ http_req_failed................: 0.00%
✓ checks.........................: 100.00%

When a threshold fails:

✗ http_req_duration..............: avg=743ms  p(95)=1247ms
                                   ✗ { p(95)<500 }
✓ http_req_failed................: 0.42%
✓ checks.........................: 99.80%

Exit codes and early stop

Exit code	Meaning	CI/CD behavior
0	All thresholds passed	Pipeline continues
99	One or more thresholds breached	Pipeline fails the step

Add abortOnFail to end the run immediately on a critical breach:

thresholds: {
  http_req_duration: [
    { threshold: 'p(95)<500', abortOnFail: true },
  ],
}

Example: regression caught in CI

A change ships with passing unit tests; the baseline gate runs last. p(95)=683ms vs p(95)<500 → exit 99, deploy blocked.

running (2m01.3s), 00/20 VUs, 1847 complete iterations
     ✓ status is 200
     ✓ body is not empty

     ✗ http_req_duration..............: avg=512ms  p(95)=683ms
                                        ✗ { p(95)<500 }
     ✓ http_req_failed................: 0.00%
     ✓ checks.........................: 100.00%

ERRO threshold breached: http_req_duration p(95)<500, got 683.21ms

Metric	Last passing	This run
p95	318 ms	683 ms
Throughput	15.3 requests per second (RPS)	15.1 RPS (similar)
Errors	0%	0%

Latency jumps while throughput is flat usually means per-request work got heavier (for example synchronous database work). Fix the hot path, re-run, pipeline goes green.

Baseline learning path

Fri, 05 Jun 2026 12:46:32 -0400

Learning path: Establish a performance baseline with k6

Step	What you’ll do	Outcome
1. Design load profile	Configure ramp-up, steady state, and ramp-down	Realistic traffic shape
2. Add checks	Assertions on response correctness	Per-request validation
3. Observe	Run without thresholds	Measured p95, errors, throughput
4. Set thresholds	Pass or fail from observed values plus headroom	Quality gate in the script
5. Validate	Re-run until stable	Trusted baseline
6. Review in Cloud	Dashboards in Grafana Cloud k6	History and comparison

Context

Extends the Module 2 script and Cloud setup, with no restart from zero.

Optional — help with the script: Use Grafana Assistant in k6 Script Authoring mode in Grafana Cloud to refine stages, checks, or thresholds. Refer to Use k6 Script Authoring mode and the Prerequisites slide for access notes.

Learning path

Establish a k6 baseline

Welcome to the Grafana learning path that shows you how to establish a performance baseline with k6, from understanding key metrics to enforcing thresholds and sharing results.

19 min

Beginner

Docs & blog posts

Open in Grafana Cloud

Complete this learning path directly in your Grafana Cloud stack with an interactive learning experience.

Open in Grafana Cloud

View on website

Baseline complete

Fri, 05 Jun 2026 12:46:32 -0400

Baseline complete!

What you accomplished:

Designed a realistic load profile with ramp-up, steady state, and ramp-down
Added checks that validate response correctness on every request
Ran a test to observe actual p95 latency, throughput, and error rate
Set thresholds based on measured values with appropriate headroom
Validated that your baseline test passes consistently
Stored results in Grafana Cloud k6 for historical comparison

Skills unlocked

Skill	You can now
Load profile design	Create realistic traffic patterns with ramping VUs
Correctness checks	Validate responses are correct, not just fast
Threshold setting	Turn observed metrics into automated pass/fail criteria
Baseline management	Compare results over time and detect regressions

Examine your baseline

Look at your baseline results in Grafana Cloud k6 and consider:

Threshold headroom. How much buffer did you leave above your observed p95? Tighter thresholds catch regressions sooner. Loose thresholds avoid false failures from normal jitter.
Steady state stability. Were metrics steady during steady state, or did they drift? Drift can mean warm-up, a slow leak, or shifting dependencies.
Check failures. Did any checks fail during the baseline? Decide whether that should change how you threshold the checks metric.
Confidence. If you ran this test three times, would you expect the same outcome? If not, list what might vary (data, time of day, cold caches, shared environments).

You will reuse this same review habit after every code change or infrastructure update.

What’s next

Your baseline answers “what does normal look like?” In the wrap-up module, Apply the pattern to your own service is a short transfer checklist to run the same workflow on a URL your team owns (still on non-production).

After that, the next question is what happens when things are not normal. Stress, spike, and soak testing are the usual follow-on topics; use the k6 test types guide when you are ready to design those runs.

Establishing a baseline on Grafana Labs

Establishing a baseline