xk6-output-timescaledb

xk6-output-timescaledb is a k6 extension to send k6 metrics to TimescaleDB in a predefined schema.

Install

You will need go

# Install xk6
go install go.k6.io/xk6/cmd/xk6@latest

# Build the k6 binary
xk6 build --with github.com/grafana/xk6-output-timescaledb

... [INFO] Build environment ready
... [INFO] Building k6
... [INFO] Build complete: ./k6

You will have a k6 binary in the current directory.

Using Docker

This Dockerfile builds a docker image with the k6 binary.

Configuration

First, find the Postgres connection string of the TimescaleDB instance.

To run the test and send the k6 metrics to TimescaleDB, use the k6 run command setting the k6 output option as timescaledb=YOUR_POSTGRES_CONNECTION_STRING. For example:

k6 run -o timescaledb=postgresql://k6:k6@timescaledb:5432/k6 script.js

or set an environment variable:

K6_OUT=timescaledb=postgresql://k6:k6@timescaledb:5432/k6 k6 run script.js

Options

The xk6-output-timescaledb extension supports this additional option:

• K6_TIMESCALEDB_PUSH_INTERVAL: to define how often metrics are sent to TimescaleDB. The default value is 1s (1 second).

Docker Compose

This repo includes a docker-compose.yml file that starts TimescaleDB, Grafana, and a custom build of k6 having the xk6-output-timescaledb extension. This is just a quick to setup to show the usage, for real use case you might want to deploy outside of docker, use volumes and probably update versions.

Clone the repo to get started and follow these steps:

1. Put your k6 scripts in the samples directory or use the http_2.js example.

2. Start the docker compose environment.

   docker compose up -d

   # Output
   Creating xk6-output-timescaledb_grafana_1     ... done
   Creating xk6-output-timescaledb_k6_1          ... done
   Creating xk6-output-timescaledb_timescaledb_1 ... done

3. Use the k6 Docker image to run the k6 script and send metrics to the TimescaleDB container started on the previous step. You must set the testid tag with a unique identifier to segment the metrics into discrete test runs for the Grafana dashboards.

   docker compose run --rm -T k6 run -<samples/http_2.js --tag testid=<SOME-ID>

   For convenience, the docker-run.sh can be used to simply:

   ./docker-run.sh samples/http_2.js

   Note that the docker-compose command to run k6 tests might differ depending your OS.

4. Visit http://localhost:3000/ to view results in Grafana.

Dashboards

The docker-compose setup comes with two pre-built dashboards. One for listing the discrete test runs as a list, and the other for visualizing the results of a specific test run.

Test list dashboard

Test result dashboard