Your first performance test on Grafana Labs

Your first performance test

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

Your first performance test

What you’ll do in this module:

How k6 runs your test script — Virtual users, iterations, and the three parts of a script
First test learning path — Install k6, write the QuickPizza script, run locally, send to Grafana Cloud k6
What k6 measures — Built-in metrics in the terminal and in dashboards
Local vs cloud execution — When to reach for k6 run vs k6 cloud run
First test complete — Debrief and questions to take into Module 3

Estimated time: 10-15 minutes

How k6 runs your test script

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

How k6 runs your test

Virtual users (VUs) run your default function in parallel loops without shared variables. One iteration is one full run of default by one VU. Duration or stages decide how long VUs keep looping.

Three parts of a k6 script

A k6 script has up to three parts. In the first learning path, you only use options and the default function.

Minimal example

export const options = {
  vus: 10,
  duration: '30s',
  thresholds: {
    http_req_duration: ['p(95)<500'],
  },
};

export default function () {
  http.get('https://quickpizza.grafana.com');
  sleep(1);
}

options — how hard you push, for how long, and what pass or fail means for the run.
default — what each virtual user does each iteration: requests and checks.
setup / teardown (optional) — one-time shared prep and cleanup, for tokens or test data. Refer to Test lifecycle when a later script needs them.

First test learning path

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

Learning path: Run your first k6 performance test

Step	What you’ll do	Outcome
1. Install k6	Download and install the k6 CLI	k6 available in your terminal
2. Write a test script	Create a JavaScript file with HTTP requests and checks	A complete test script
3. Run locally	Execute `k6 run test.js` and read the output	Terminal metrics: latency, throughput, errors
4. Connect to Grafana Cloud	Authorize the CLI with a Grafana Cloud k6 API token (`k6 cloud login`)	Ready for Grafana Cloud k6
5. Run on Grafana Cloud k6	Execute `k6 cloud run test.js`	Stored run in Grafana Cloud k6 dashboards

Before you start

Have these ready before you open the path (the path itself installs k6 and walks through the script):

Terminal, code editor, and your Grafana Cloud account
Targets QuickPizza only in this path (not your production systems)
Optional — help with the script: In Grafana Cloud, use Grafana Assistant in k6 Script Authoring mode to draft or refine the JavaScript before you run locally. Refer to Use k6 Script Authoring mode; the Prerequisites slide summarizes access, when Assistant is not visible, and an example prompt you can paste. Use Assistant output as a draft and match the path’s script.js before k6 run.

Learning path

Run your first k6 performance test

Welcome to the Grafana learning path that shows you how to write, run, and analyze your first k6 performance test, from installation to visualizing results in Grafana Cloud.

15 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

What k6 measures

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

Built-in metrics

k6 collects these metrics automatically for every HTTP request.

Metric	What it measures	Why it matters
`http_req_duration`	Time from request start to response end	The primary measure of response speed
`http_reqs`	Total requests and requests per second	Your throughput under load
`http_req_failed`	Percentage of requests that returned errors	Error rate under load
`checks`	Pass rate of response assertions	Whether responses are correct, not just fast

Prefer percentiles for gates

p95 and p99 describe tail latency: how slow the slowest slice of requests were. Prefer them over avg, which can hide slow outliers. For pass/fail limits — the kind of target you might write into a service-level objective (SLO), like “95% of requests under 500ms” — start from p95 on http_req_duration, then add p99 when tail risk matters (payments, auth, checkout). Full metric definitions and extra aggregates live in HTTP metrics in the k6 docs.

When the numbers look wrong

Symptom	First place to look
You doubled VUs but RPS barely moved	Requests taking longer (`http_req_duration`), long `sleep`, or many requests per iteration eating the window
Errors spike with load	Saturation in the system under test, rate limits, or a script assumption (wrong header, shared test user)
You need one login for many VUs	`setup()` to fetch a token once, pass data into VUs; still no shared mutable state between VUs

If you doubled VUs but requests per second barely moved, the links below explain why iteration pacing and open versus closed load models matter. Refer to Request rate and open vs closed models. For any run, anchor on http_req_duration and the summary tables.

Think about it

Pick one endpoint you might baseline later and a rough “too slow” number. You will reuse that intuition when you set thresholds in Module 3.

Local vs cloud execution

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

When to reach for each

You ran both k6 run and k6 cloud run in the path. Most teams use both: iterate locally, then promote to Grafana Cloud k6 when a script is ready to keep around. The table below is the cheat sheet for choosing between them next time.

	Local execution	Grafana Cloud k6
Command	`k6 run test.js`	`k6 cloud run test.js`
Where load runs	Your machine	Grafana Cloud k6 infrastructure
Results	Terminal summary (session-only unless you add an output)	Stored in Grafana Cloud with dashboards
History	None by default	Compare runs over time
Collaboration	Share logs manually	Share dashboards and links
Best for	Script development, quick checks	Team baselines, CI artifacts, trend analysis

For optional output modes (for example streaming a local run to Grafana Cloud), refer to k6 results output and Grafana Cloud k6.

First test complete

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

First test complete!

What you accomplished:

Installed k6 on your machine
Wrote a test script with HTTP requests and checks
Ran a test locally and read the terminal output
Sent results to Grafana Cloud k6
Analyzed response time, throughput, and error rate in dashboards

Skills unlocked

Skill	You can now
Script writing	Write k6 test scripts in JavaScript
Local execution	Run tests from the terminal and read results
Cloud reporting	Stream results to Grafana Cloud for dashboards and history
Metric reading	Interpret http_req_duration, http_reqs, and checks

Examine your results

Before moving on, look at the test results you just produced and consider:

p95 latency. Was it higher or lower than you expected? What in the system or test data could explain that value?
Ramp-up vs steady state. Did response times change as VUs increased? If yes, what does that suggest about capacity or queueing?
Check pass rate. Were all checks at 100%? If any failed, what response shape or timing would explain it?
Your own system. If you tested your own endpoint instead of QuickPizza, what p95 would you call too slow for that route?

These notes feed the threshold choices you will make in the next module.

What’s next

You have test results, but no way to know if they’re “good.” In the next module, you’ll define what good looks like by establishing a performance baseline with automated pass/fail thresholds.