grafana/xk6-output-timescaledb

k6 extension to output real-time test metrics to TimescaleDB.

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

xk6-output-timescaledb's Issues

Tagged thresholds improperly saved in the TimescaleDB's threshold table

As mentioned it the title, when passing tagged metrics in thresholds like so:
'http_req_duration{name:login}': ['p(95)<55000'],

they are not saved properly in the database, namely the metrics are not separated from their tags and the 'tags' column in the threshold table is populated with nulls.

Docker build is broken

The Dockerfile pulls golang:1.17-alpine as the builder for k6.

It references <...>net/netip which is only introduced in golang 1.18

Updating the Dockerfile to use a later image (ex golang:1.19-alpine) fixes the build issue.

Improve Grafana dashboard in samples

Improve upon the currently provided dashboards (samples/).

Another goal for this change would be to align the look-and-feel for the Timescale-backed dashboard (this extension), the xk6-output-influxdb, and xk6-output-prometheus-remote possibly with the output provided by the k6 Cloud App. This would provide a consistent user experience for the varied data sources.

Ideally, this dashboard would be promoted to the Grafana site as the "official" dashboard for displaying k6 metrics backed by TimescaleDB datasources.

This issue may supersede the need for #5.

Add dashboard to compare two testids

@codebien found this so it seems pretty doable

Can't find modul during preparing image

Hello,

I've been attempting to build a Docker image using your Dockerfile from the xk6-output-timescaledb repository (link: https://github.com/grafana/xk6-output-timescaledb/blob/main/Dockerfile), but I've run into an issue.

During the image build process, the build fails on the step RUN CGO_ENABLED=0 xk6 build --with github.com/grafana/xk6-output-timescaledb=. --output /tmp/k6, with an error indicating the github.com/grafana/xk6-output-timescaledb module cannot be found.

Could you assist in understanding how I can successfully build this Docker image with this extension? Is there anything I may have overlooked in the documentation or the structure of your project?

Thank you for your help.

Need CI with Github Actions

Need automated build and testing.

Batch writing to postgresql (timescale) with pgx isn't really a batch write to the db

Using batch from pgx doesn't write the data to the db in a batch write.

In effect it just piles all the inserts in a a big package (the "batch") and sends the big package in one go.

The db then commences to do all the inserts in one transaction but in sequence. If the sequence of inserts takes too much time, the connection will be severed and the fail ignored by pgx.

Batches are very limited in capacity for high volume use cases and need a better implementation.

Needed to maintain listing in k6 Extensions Registry

We've recently updated the requirements for maintaining an extension within the listing on our site. As such, please address the following items to maintain your listing within the registry:

• needs to build with a recent version of k6; minimum v0.43 but v0.45 would be great...

For more information on these and other listing requirements, please take a look at the registry requirements.

Filter based on the testid in test list dashboard

After #4 the tests list dashboard will give you a link for a testid and will "zoom" on it but it will still not actually filter only the testid results.

Out of memory for high req rate tests

We have a test running at ~1200 req/s with 1 K vu. It runs from a 16 Gb memory 8 core EC2 of some sort on Ubuntu Linux.

The test itself is a rather simple two-request use case.

It ramps up fine to the max rate over 20 min so a pretty slow ramp up.

Once at max it just gobbles up memory until it runs out.

Running the same test using no output except the console summary consumes some 7% total of the memory.

Running the same test setting the K6_TIMESCALEDB_PUSH_INTERVAL to 500ms or even shorter makes the test work. It still uses a lot of memory but not as much.

We would like to optimize memory usage a bit better so as not to consume such large amounts of memory.

A self sizing reporting window could be one possibility.

With a well scaled db reverting the connection pool and having parallel connections to the db would also work very well. The db has very high parallel throughput but shortening to push interval to something like 200 ms will max out the one core tied to the connection.

This is of course only valid for a monolith running the entire test. Scaling out using several smaller loadgens will not hit this issue unless they are pressed for high request rates.

Update k6 to 0.38.0

What?

Update k6 to 0.38.0 once it released

https://github.com/grafana/xk6-output-timescaledb/pull/7/files#r852767434

Why?

Keep go.mod clean