xk6-dashboard

A k6 extension that enables creating a web based metrics dashboard for k6.

By using the xk6-dashboard output extension you can access metrics from k6 process via server-sent events (SSE). All custom k6 metrics (Counter, Gauge, Rate, Trend) and built-in metrics are accessible in the event stream.

The test run report can be exported to a responsive self-contained HTML file, which can be displayed even without an Internet connection.

Screenshots

Overview

The overview tab provides an overview of the most important metrics of the test run. Graphs plot the value of metrics over time.

Timings

The timings tab provides an overview of test run HTTP timing metrics. Graphs plot the value of metrics over time.

Summary Tab

The summary tab contains a summary of the test run metrics. The tables contain the aggregated values of the metrics for the entire test run.

HTML Report

The report can be saved in a single responsive HTML file.

Single file HTML report

See sample HTML report or try the online version

Table of Contents

• Download
• Build
• Usage
• Exit
• Parameters
• Environment
• Docker
• Save report
• Events
• Command Line
  • Docker

Download

You can download pre-built k6 binaries from the Releases page. Check the Packages page for pre-built k6 Docker images.

Build

To build a k6 binary with this extension, first ensure you have the prerequisites:

• Go toolchain
• Git

Then:

1. Download xk6:

$ go install go.k6.io/xk6/cmd/xk6@latest

2. Build the binary:

$ xk6 build --with github.com/grafana/xk6-dashboard@latest

Usage

Without parameters the dashboard will be accessible on port 5665 with any web browser: http://127.0.0.1:5665

$ ./k6 run --out dashboard script.js

          /\      |‾‾| /‾‾/   /‾‾/   
     /\  /  \     |  |/  /   /  /    
    /  \/    \    |     (   /   ‾‾\  
   /          \   |  |\  \ |  (‾)  | 
  / __________ \  |__| \__\ \_____/ .io

  execution: local
     script: script.js
     output: dashboard (:5665) http://127.0.0.1:5665

Using --out dashboard=open will automatically open a new browser window.

Exit

The k6 process waits to exit as long as there is at least one open browser window for the dashboard extension. In this way, the report can be downloaded, for example, even after the test has been completed.

In certain environments, it is not allowed that the k6 process does not exit after the test run (eg CI/CD pipeline). In this case, it is advisable to disable the HTTP port (with the -1 value of port parameter).

Parameters

The output extension accepts parameters in a standard query string format:

k6 run --out 'dashboard=param1=value1&param2=value2&param3=value3'

Note the apostrophes (') around the --out parameter! You should use it to escape & characters from the shell (or use backslash before &).

The following parameters are recognized:

parameter	description
host	Hostname or IP address for HTTP endpoint (default: "", empty, listen on all interfaces)
port	TCP port for HTTP endpoint (default: 5665; 0 = random, -1 = no HTTP), example: 8080
period	Event emitting frequency (default: 10s), example: 1m
open	Set to true (or empty) to open the browser window automatically
export	File name to save the report (default: "", empty, the report will not be saved)
record	File name to save the dashboard events (default: "", empty, the events will not be saved)
tag	Precomputed metric tag name(s) (default: "group"), can be specified more than once

The export parameter used to be report, for compatibility reasons the name report can still be used.

Environment

The dashboard parameters can also be specified in environment variables. The name of the environment variable belonging to the given parameter is created by converting the parameter name to uppercase and adding the K6_WEB_DASHBOARD_ prefix.

environment variable	description
K6_WEB_DASHBOARD_HOST	Hostname or IP address for HTTP endpoint (default: "", empty, listen on all interfaces)
K6_WEB_DASHBOARD_PORT	TCP port for HTTP endpoint (default: 5665; 0 = random, -1 = no HTTP), example: 8080
K6_WEB_DASHBOARD_PERIOD	Event emitting frequency (default: 10s), example: 1m
K6_WEB_DASHBOARD_OPEN	Set to true (or empty) to open the browser window automatically
K6_WEB_DASHBOARD_EXPORT	File name to save the report (default: "", empty, the report will not be saved)
K6_WEB_DASHBOARD_RECORD	File name to save the dashboard events (default: "", empty, the events will not be saved)
K6_WEB_DASHBOARD_TAG	Precomputed metric tag name(s) (default: "group"), can be specified more than once

Docker

You can also use pre-built k6 image within a Docker container. In order to do that you will need to execute something like the following:

Linux

docker run -v $(pwd):/scripts -p 5665:5665 -it --rm ghcr.io/grafana/xk6-dashboard:latest run --out=dashboard /scripts/script.js

Windows

docker run -v %cd%:/scripts -p 5665:5665 -it --rm ghcr.io/grafana/xk6-dashboard:latest run --out=dashboard /scripts/script.js

The dashboard will accessible on port 5665 with any web browser: http://127.0.0.1:5665

Save report

The test run report can be exported to a responsive self-contained HTML file. For export, the file name must be specified in the export parameter. If the file name ends with .gz, the HTML report will automatically be gzip compressed.

k6 run --out dashboard=export=test-report.html script.js

The exported HTML report file does not contain external dependencies, so it can be displayed even without an Internet connection. Graphs can be zoomed by selecting a time interval. If necessary, the report can be printed or converted to PDF format.

By using the --export switch of the dashboard replay command, the report can also be generated afterwards from the previously saved JSON format result (--out json=test-result.json).

The report can also be viewed and downloaded from the dashboard UI using the buttons on the "Report" tab.

k6 dashboard replay --export test-report.html test-result.json

Example HTML report

See sample HTML report or try the online version

Events

The /events endpoint (default: http://127.0.0.1:5665/events) is a standard SSE source endpoint. Using this event source you can create your own dashboard UI.

Events will be emitted periodically based on the period parameter (default: 10s). The event's data is a JSON object with metric names as property names and metric values as property values. The format is similar to the List Metrics response format from the k6 REST API.

Two kind of events will be emitted:

• config contains ui configuration
• param contains main extension parameters (period, scenarios, thresholds, etc)
• start contains start timestamp
• stop contains stop timestamp
• metric contains new metric definitions
• snapshot contains metric values from last period
• cumulative contains cumulative metric values from the test starting point

Command Line

The xk6-dashboard extension adds a dashboard command to the k6 command line:

$ ./k6 dashboard --help

xk6-dashboard commands

Usage:
  k6 dashboard [command]

Available Commands:
  aggregate   convert saved json output to recorded dashboard events
  replay      load the recorded dashboard events and replay it for the UI
  report      create report from a recorded event file  

Flags:
  -h, --help   help for dashboard

Use "k6 dashboard [command] --help" for more information about a command.

At the moment, the dashboard command has three subcommand, replay (which can be used to play back dashboard events previously saved with record parameter), aggregate (which can be used to convert test run results previously saved in JSON format from k6 to dashboard events format NDJSON) and report (which can be used to generate report from dashboard events previously saved with record parameter).

$ ./k6 dashboard replay --help

The replay command load the recorded dashboard events (NDJSON format) and replay it for the dashboard UI.
The compressed file will be automatically decompressed if the file extension is .gz

Usage:
  k6 dashboard replay file [flags]

Flags:
      --host string     Hostname or IP address for HTTP endpoint (default: '', empty, listen on all interfaces)
      --open            Open browser window automatically
      --port int        TCP port for HTTP endpoint (0=random, -1=no HTTP), example: 8080 (default 5665)
      --export string   Report file location (default: '', no report)
  -h, --help            help for replay

$ ./k6 dashboard aggregate --help

The aggregate command converts the file saved by json output to dashboard format events file.
The files will be automatically compressed/decompressed if the file extension is .gz

Usage:
  k6 dashboard aggregate input-file output-file [flags]

Flags:
      --period 1m      Event emitting frequency, example: 1m (default 10s)
      --tags strings   Precomputed metric tags, can be specified more than once (default [group])
  -h, --help           help for aggregate

$ ./k6 dashboard report --help

The report command loads recorded dashboard events (NDJSON format) and creates a report.
The compressed events file will be automatically decompressed if the file extension is .gz

Usage:
  k6 dashboard report events-file report-file [flags]

Flags:
      --open   Open browser window with generated report
  -h, --help   help for report

To visualize the result of a previous test run (using events file):

./k6 run --out dashboard=record=test_result.ndjson script.js
./k6 dashboard replay test_result.ndjson

To visualize the result of a previous test run (using json output):

./k6 run --out json=test_result.json script.js
./k6 dashboard aggregate test_result.json test_result.ndjson
./k6 dashboard replay test_result.ndjson

To generate report from previous test run (using events file):

./k6 run --out dashboard=record=test_result.ndjson script.js
./k6 dashboard report test_result.ndjson test_result_report.html

Docker

You can also use pre-built k6 image within a Docker container. In order to do that, you will need to execute something like the following:

Linux

docker run -v $(pwd):/work -v /tmp:/tmp/work -it --rm ghcr.io/grafana/xk6-dashboard:latest run --out=json=/tmp/work/test_result.json.gz /work/script.js
docker run -v /tmp:/tmp/work -p 5665:5665 -it --rm ghcr.io/grafana/xk6-dashboard:latest dashboard replay /tmp/work/test_result.json.gz

Windows

docker run -v %cd%:/work -v %USERPROFILE%\AppData\Local\Temp:/tmp/work -it --rm ghcr.io/grafana/xk6-dashboard:latest run --out=json=/tmp/work/test_result.json.gz /work/script.js
docker run -v %USERPROFILE%\AppData\Local\Temp:/tmp/work -p 5665:5665 -it --rm ghcr.io/grafana/xk6-dashboard:latest dashboard replay /tmp/work/test_result.json.gz

The dashboard will accessible on port 5665 with any web browser: http://127.0.0.1:5665