Grafana k6 Tutorial | Run Tests and View Results

Grafana k6 makes it surprisingly straightforward to run a performance check, see what happened and send the results to Grafana Cloud. I started by clicking the website monitoring card and asking, “Where do my results actually go?” This Grafana k6 tutorial turns that experiment into a complete Windows-first walkthrough, with a small local test you can understand before increasing the traffic.

Grafana k6 Tutorial: What You Are Building

You will install the command-line tool, create a JavaScript test and inspect response times and failures. Then you can choose a local dashboard or Grafana Cloud for the results. The HTTP example sends requests directly to an endpoint. It does not open Chrome or measure page rendering. Browser-based performance testing uses a separate k6 browser workflow.

Start with a development or staging endpoint you control. The example uses one virtual user and three iterations, so it is a smoke test of the setup. It cannot tell you how many customers your application supports. A useful load test comes later, after you know the normal traffic pattern, agree on targets and have monitoring for the application.

Choose Performance Testing or Uptime Monitoring

In my original Grafana onboarding, I selected the website uptime and performance card and then the k6 performance test option. That is a useful starting point, but the two jobs differ. Synthetic monitoring runs scheduled probes to check availability over time. A k6 performance test generates a defined workload and measures how the target handles it. Choose the workflow that matches the question you are asking.

Install Grafana k6 on Windows

Open PowerShell or Windows Terminal. With Windows Package Manager available, install k6 using the following command. Review any source or installer agreement before accepting it. You do not need to install the JavaScript tool with npm.

winget install k6 --source winget
k6 version

If the second command is not recognised, close that terminal and open a new one so it picks up the updated PATH. An editor terminal may need the editor to restart too. The screenshot below records the version from my original experiment; your current installation can report a different version. On macOS, the equivalent Homebrew command is brew install k6. Linux users should follow the installation route for their distribution.

Write Your First Grafana k6 Test

Create a folder for the experiment and save the following as script.js. Start a local development server on port 8080 that returns HTTP 200 at its root, or set TARGET_URL to your own test endpoint. The default address deliberately stays on your machine. For a minimal local target, if Python 3 is installed, run python -m http.server 8080 in a separate terminal and an empty folder.

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

export const options = {
  vus: 1,
  iterations: 3,
  thresholds: {
    http_req_failed: ['rate<0.01'],
    http_req_duration: ['p(95)<1000'],
    checks: ['rate==1'],
  },
};

export default function () {
  const response = http.get(__ENV.TARGET_URL || 'http://127.0.0.1:8080/');
  check(response, { 'status is 200': (r) => r.status === 200 });
  sleep(1);
}

The default function is the work each virtual user repeats. Here it requests one URL, checks its status and pauses for one second. The pause controls how quickly that user repeats; it does not guarantee an exact request rate. Three iterations means three executions in total for this single-user configuration. Also, this JavaScript runs in k6, so Node.js APIs and packages are not automatically available.

A check records whether a condition passed. A threshold defines the pass or fail rule for a metric. Failed checks alone do not make the process fail, which is why this example also includes a checks threshold. The response-time limit is a teaching example, not a performance promise or a target that every application should adopt.

Run the Test and Read the Summary

k6 run script.js

Run that command in the folder containing your script. For a different owned endpoint in PowerShell, set the environment variable before running it:

$env:TARGET_URL = "http://127.0.0.1:8080/"
k6 run script.js

Look at http_reqs for the request count, http_req_failed for HTTP failures and http_req_duration for request timing. The p(95) value is the 95th percentile: roughly 95 percent of the recorded durations fall at or below that value. With only three samples, treat it as a sanity check rather than a stable estimate. Repeat a suitable workload to build a useful baseline.

Check the threshold indicators as well as the response times. When a threshold fails, k6 finishes with a non-zero exit code. A quick response is not a success if the application returned the wrong result. Conversely, an HTTP status of 200 does not establish that the response content was correct; add checks for the behaviour your endpoint promises.

View a Local Dashboard Without a Cloud Account

For a longer test, the built-in web dashboard lets you inspect live metrics locally. These PowerShell variables enable the dashboard and request an HTML export. Keep the terminal running while you open http://127.0.0.1:5665 in a browser.

$env:K6_WEB_DASHBOARD = "true"
$env:K6_WEB_DASHBOARD_EXPORT = "k6-report.html"
k6 run script.js

A three-iteration smoke test ends quickly and may provide too little time-series data for meaningful charts. Increase the duration only when you are ready to run a longer test against your approved environment. The terminal summary remains the first check. Remove the dashboard variables afterwards if you no longer want them applied to later runs.

Send Grafana k6 Results to Grafana Cloud

Open your Grafana Cloud stack and locate Performance testing under Testing and synthetics. My original screenshots show the project list and run charts there. Labels can move as the interface changes, but the goal is the same: choose the right stack, authenticate k6 and open the resulting test run.

Use k6 cloud login to follow the current interactive authentication flow. For CI, use the required token and stack configuration through your CI secret store. An ordinary .env file is not loaded automatically by k6. Installing dotenv in an unrelated Node.js project does not change that. Keep tokens out of scripts, screenshots and version control.

k6 cloud login
k6 cloud run --local-execution script.js

The second command executes the test on your computer and streams its results to Grafana Cloud. It can consume your Cloud test allowance. By comparison, k6 cloud run script.js uploads the script and executes it on Cloud infrastructure. Make that choice deliberately, especially if the target is reachable only from your own network.

Older walkthroughs may use k6 run –out cloud. For this guide, use the current documented cloud command above. After it finishes, follow the result URL or open the appropriate project in your stack. A new run should appear when you repeat the test. Wait for processing to finish before comparing its final summary.

Compare Results Before Increasing the Load

Nice, results at last! Now compare like with like. Use the same endpoint, dataset and workload, and record whether a deployment or configuration changed between runs. A shorter total run time by itself does not prove that the application improved. Compare request timing, error rate, throughput and threshold outcomes together.

To investigate server CPU, memory or database behaviour, collect the relevant application and infrastructure telemetry separately and correlate it with the test window. k6 HTTP timings do not automatically supply server resource usage. That extra monitoring is what helps you move from “it became slow” to a plausible explanation.

Optional: Prometheus Remote Write

Prometheus remote write is another output route when you already operate a compatible metrics backend. It is separate from the Grafana Cloud k6 run view. You must configure the receiver endpoint and any required credentials, then use the currently documented experimental-prometheus-rw output. The output name and receiver configuration must match the version you install.

For this first tutorial, finish with the local summary or Cloud view before adding that integration. The official Grafana k6 documentation covers installation, thresholds, dashboards, Cloud authentication and remote-write settings for the version you install.

Troubleshooting Your Grafana k6 Setup

For a missing command, verify installation and reopen the terminal. A refused connection usually means you should check that the local server is running and that the URL includes the correct port. If a Cloud run fails to authenticate, confirm the selected stack and token permissions before rerunning. A local dashboard can work without any Cloud login, which helps you isolate setup problems.

If checks pass but a threshold fails, read the failing metric rather than removing the rule immediately. Your target might be slower than the example limit, or a small sample might be unrepresentative. Agree on a meaningful limit, run a suitable workload and keep the result as evidence. You can build on this approach alongside our Selenium test automation introduction, which covers a different part of your testing toolkit.