k6 custom metrics dashboard

Real-time, zero-configuration, zero-dependency browser dashboard for k6 custom metrics.

TL;DR

Name your custom metrics with a shared suffix — the suffix becomes the chart, the prefix becomes the series. No configuration needed.

homepage_http_req_duration  ─┐
                             ├── chart: "http req duration" (series: homepage, user)
user_http_req_duration      ─┘

How it works

Run your k6 test with --out json=results.json. The dashboard tails the file in real time and creates charts on the fly.

homepage_http_req_duration  ─┐
user_http_req_duration      ─┤── chart: "http req duration" (series: homepage, user)

homepage_error_rate         ─┐
user_error_rate             ─┤── chart: "error rate" (series: homepage, user)

Metrics are grouped by their longest common suffix (split by _). The prefix becomes the series name within the chart. Metrics with a unique name get their own chart.

k6 built-in metrics (http_reqs, vus, iterations, etc.) are shown in charts by default but excluded from the summary table. Set K6_HIDE_BUILTIN=true to hide them from charts as well.

Install

npm install -g k6-custom-metrics-dashboard

Usage

# Start dashboard (watches results.json in the current directory)
k6-custom-metrics-dashboard

# Watch a specific file
k6-custom-metrics-dashboard path/to/output.json

# Custom port (default: 3000)
k6-custom-metrics-dashboard --port 8080

# Run alongside k6
k6-custom-metrics-dashboard & k6 run --out json=results.json test.js

Then open http://localhost:3000 in your browser.

k6 test setup

The dashboard works with any k6 test that outputs JSON. Add --out json=results.json to your k6 command:

k6 run --out json=results.json my-test.js

Example k6 script

import http from "k6/http";
import { Rate, Trend } from "k6/metrics";

// Define custom metrics with a shared suffix pattern
const homepageDuration = new Trend("homepage_http_req_duration");
const userDuration = new Trend("user_http_req_duration");
const homepageErrorRate = new Rate("homepage_error_rate");
const userErrorRate = new Rate("user_error_rate");

export default function () {
  const home = http.get("https://example.com/");
  homepageDuration.add(home.timings.duration);
  homepageErrorRate.add(home.status >= 400);

  const user = http.get("https://example.com/user/1");
  userDuration.add(user.timings.duration);
  userErrorRate.add(user.status >= 400);
}

The dashboard will automatically create:

• A "http req duration" chart with homepage and user as series
• An "error rate" chart with homepage and user as series

Features

• Auto-discovery — no configuration needed. Charts are created dynamically as metrics appear.
• Smart grouping — metrics sharing a common suffix are grouped into the same chart. The prefix becomes the series label.
• Real-time updates — uses Server-Sent Events to push data to the browser as k6 writes to the JSON file.
• Toggleable series — click series labels above each chart to show/hide individual series.
• Summary table — shows count, average, P95, min, and max for every metric.
• Dark mode — follows system preference automatically.
• Zero dependencies — only uses Node.js built-ins. Chart.js and Tailwind CSS are loaded from CDN in the browser.

Environment variables

| Variable | Default | Description | | ----------------- | ------- | ----------------------------------------------------- | | DASHBOARD_PORT | 3000 | Port for the dashboard server | | K6_HIDE_BUILTIN | false | Set to true to hide k6 built-in metrics from charts |

Requirements

• Node.js >= 18
• k6 with --out json=results.json

License

MIT