Many people have started using k6 to test their web services and APIs, but not all are aware of the different results output options offered by k6. This article shows how simple it is to use Grafana to visualise your k6 test results.
Grafana is a hugely popular, open-source data visualisation tool that is widely used for e.g. performance- and uptime monitoring. It can display time series data in almost any way imaginable using the built-in functionality plus lots of community-contributed plugins. Given that Grafana is becoming an industry standard and is very good at visualising the type of data generated by k6, we made sure early on that k6 would integrate well with Grafana.
Specifically, we did this by integrating with another very popular application: InfluxDB. InfluxDB is a database specialised on time series data, and a very common data storage backend for Grafana. As both Grafana and k6 come with built-in support for InfluxDB, connecting the two is quite simple. Let's get into how.
You'll need three things: k6, InfluxDB and Grafana. Each can be installed in several different ways and I'll get into that further down, but it's not hard at all. When you have all of them, however, you just run k6 using a command line like this (provided there is a k6 script called script.js):
k6 run -o influxdb=http://localhost:8086/mydb script.js
-o influxdb=<adress-to-influxdb> is of course the thing that tells k6 to send results to an InfluxDB instance. "mydb" is the name of the database on the InfluxDB server. If this database does not exist, k6 will create it automatically.
When you have data on your InfluxDB instance, you just use a browser to connect to your Grafana installation (found on http://localhost:3000 by default) where you can setup dashboards visualising your results data in real time. You can also install dashboards created by the k6 community - go to https://grafana.com/dashboards?search=k6
Installation using docker-compose
$ git clone https://github.com/loadimpact/k6 && cd k6
$ git submodule update --init $ docker-compose up -d influxdb grafana
docker-compose will read the `docker-compose.yml` configuration file found in the root of the k6 repository and then understand that you want three different applications: k6, InfluxDB and Grafana, for which individual Docker images are retrieved. The options `up -d influxdb grafana` means that docker-compose should start those two applications in the background. After you have done this you will have a default Grafana server running on port 3000 on your machine. If you connect to it you'll see a new Grafana installation looking like this:
Grafana will have been configured to read data from your local InfluxDB that was also started by docker-compose. You can go on to create dashboards, but there is no data to visualise yet: we haven't run any k6 tests. To run a k6 test and get the results stored in the InfluxDB database you just do:
docker-compose run -v $PWD:/scripts k6 run /scripts/myscript.js
(provided there was a k6 script called myscript.js in your current directory)
Normally, you'd have to use the `-o influxdb=...` option when running k6, to get k6 to connect to InfluxDB and store results there, but when using this docker-compose setup, k6 will be preconfigured to send results to InfluxDB, so no need to specify anything.
The -v option for docker-compose will mount your current working directory ($PWD) under /scripts in the Docker container, so that k6 is able to read files from the current directory by accessing /scripts.
You can also skip Docker and install everything natively on your machine, of course. Here is how you do that:
1. Installing k6 natively
- On a mac you can use brew:
brew tap loadimpact/k6
brew install k6
- On any one of Mac, Windows or Linux you can grab a pre-built binary from https://github.com/loadimpact/k6/releases
2. Installing InfluxDB natively
- On a Mac you can use brew again, and then start influxdb manually:
brew install influxdb
influxd -config /usr/local/etc/influxdb.conf
- On other systems, follow the instructions at the influxdata site: https://docs.influxdata.com/influxdb/v1.5/introduction/installation/
3. Installing Grafana natively
- On a Mac, use brew to install and start InfluxDB:
brew install grafana
brew services start grafana
- On other systems, follow the Grafana installation instructions: http://docs.grafana.org/installation/
Unless you're using docker-compose to set things up (as described above), you're going to have to tell Grafana to use InfluxDB as data source - open up http://localhost:3000 and configure a data source:
The default address for InfluxDB will be http://localhost:8086 and you can enter the name of a database that doesn't exist, as long as you tell k6 to use the same database (so k6 creates it the first time it tries to store data in it). Again, note that this step is not necessary if you use the docker-compose setup, in which case Grafana will be preconfigured to use the correct InfluxDB server and database as its data source.
Regardless of how you install things, you'll now need to create a dashboard to show the k6 data you're going to create. You can set one up yourself, or you can download and install a dashboard made by someone else. There are a couple of community-contributed k6 dashboards at grafana.com.
Setting up a dashboard yourself is not too hard though. Click the "New dashboard" link:
On the "New dashboard" page you want to create a new panel of the "Graph" type:
The panel will occupy half the width of the window - drag it out so it uses up the whole window and then click the "Panel title" to get a small dropdown menu where you can choose "Edit" to edit the panel:
The "Edit panel" UI looks like this. The interesting thing here is the "select measurement" field:
Clicking that will either show you a drop-down list of lots of different metrics you can choose to plot in the graph, or the list will be completely empty.
If the list is empty, you need to run a k6 test that inserts some data into InfluxDB so that Grafana can see the metrics k6 uses. If you have a metrics-producing k6 script (any script that makes HTTP requests will produce lots of metrics) called "script.js" in the current working directory and are using docker-compose, do this:
docker-compose run -v $PWD:/scripts k6 run /scripts/script.js
If you've installed things natively and are not using docker-compose, you should execute something like:
k6 run -o influxdb=http://localhost:8086/myinfluxdb script.js
After this, Grafana should be able to detect the metrics k6 is storing in InfluxDB, and you should now get something like this when you click "select measurement":
Choose e.g. the "http_req_duration" metric to plot. You may see something in the graph already, but if not, try clicking the time period control in the upper right corner of the window (the one that says "Last 6 hours") and use a shorter time period to look at. The "Last 1 hour" perhaps.
If the k6 test you ran earlier was short and did not produce a lot of measurements, you may need to run a new test that is longer and that creates more measurement samples. Try setting the time period to "Last 5 minutes" and then run a k6 test that takes a bit more time and is reasonably intensive (generates at least a measurement each second). Suggested is to use a script that does nothing but load a single URL. Something like this:
Run it with 2 VU for a few minutes:
k6 run --vus 2 --duration 3m -o influxdb=http://localhost:8086/myinfluxdb script.js
docker-compose run -v $PWD:/scripts k6 run --vus 2 --duration 3m /scripts/script.js
While running, refresh your dashboard regularly (or turn on auto-refresh - see if you can find that option!) and see what happens. You should be able to see some green lines appear:
Sometimes it can be tricky to find the right settings in Grafana to display things the way you want. Especially if you're running very short k6 tests, the default settings in Grafana may make it hard to see any data at all, because the data points/samples are few and close together in time.
When starting out, it is therefore a good idea to:
- Try showing different time periods and when running k6, set your Grafana dashboard to display results for "Last 5 minutes" - click upper right corner of the window to bring up the time picker:
Grafana: making your dashboard display data from the last 5 minutes
- Either enable auto-refresh (seen at bottom left on above screenshot: "Refreshing every: off"), or click the refresh arrow icon at the top right of the screen regularly while you're running the k6 tests that generate results data.
- Make sure your k6 test runs for at least a couple of minutes (2+ minutes).
- Make sure your k6 test generates result samples every second (which usually means your test should make >=1 HTTP request per second while it is running). If your script just performs an HTTP request and contains no sleeps etc. this should not be a problem, but otherwise you can just increase the number of VUs in the test, in order to increase the total throughput.
- Choose a frequently-generated metric to visualise on your dashboard: http_req_duration is probably such a metric, if your script performs a reasonable number of HTTP requests (see previous point).
You should now be able to at least get up and running with k6+Grafana. There is of course a ton of functionality hidden here that we cannot cover in a blog article like this, so there is plenty to discover.
Oh, and if you manage to create a cool Grafana dashboard, please share it with other k6 users! Go to https://grafana.com/dashboards where you'll find information about how to share dashboards. Ping us in the k6 Slack channels about any new dashboards also - We try to mention user-contributed dashboards on the k6 docs site: https://docs.k6.io/docs/tools-add-ons
Let's end with a final screenshot of a user-contributed Grafana k6 dashboard, and may the graphs be with you!