xk6-output-influxdb

k6 extension for InfluxDB v2, it adds the support for the latest v2 version and the compatibility API for v1.8+.

Why is this output not directly part of k6 core?

The k6 core already supports the InfluxDB v1 so the natural feeling would be to do the same for the v2. Unfortunately, the v2 has introduced some breaking changes in the core parts of the API. This would make it difficult to support both versions without taking a bunch of compromises for maintaining the retro-compatibility or introducing breaking changes in the current user experience of the k6's InfluxDB output, with a high probability to create more confusion for k6's users. For this main reason, the k6 development team has decided to create a new and independent extension for InfluxDB v2.

Install

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

• Go toolchain
• Git
• xk6

1. Build with xk6:

xk6 build --with github.com/grafana/xk6-output-influxdb

This will result in a k6 binary in the current directory.

2. Run with the just built k6 binary:

K6_INFLUXDB_ORGANIZATION=<insert-here-org-name> \
K6_INFLUXDB_BUCKET=<insert-here-bucket-name> \
K6_INFLUXDB_TOKEN=<insert-here-valid-token> \
./k6 run -o xk6-influxdb=http://localhost:8086 <script.js>

Using Docker

This Dockerfile builds a docker image with the k6 binary.

Configuration

Options for fine-grained control for flushing and connections.

ENV	Default	Description
K6_INFLUXDB_ORGANIZATION		The Organization.
K6_INFLUXDB_BUCKET		The Bucket.
K6_INFLUXDB_TOKEN		The Token.
K6_INFLUXDB_ADDR	http://localhost:8086	The address of the instance.
K6_INFLUXDB_PUSH_INTERVAL	1s	The flush's frequency of the k6 metrics.
K6_INFLUXDB_CONCURRENT_WRITES	4	Number of concurrent requests for flushing data. It is useful when a request takes more than the expected time (more than flush interval).
K6_INFLUXDB_TAGS_AS_FIELDS	vu:int,iter:int,url	A comma-separated string to set k6 metrics as non-indexable fields (instead of tags). An optional type can be specified using :type as in vu:int will make the field integer. The possible field types are int, bool, float and string, which is the default. Example: vu:int,iter:int,url:string,event_time:int.
K6_INFLUXDB_INSECURE	false	When true, it will skip https certificate verification.
K6_INFLUXDB_PRECISION	1ns	The timestamp Precision.

Docker Compose

This repo includes a docker-compose.yml file that starts InfluxDB, Grafana and k6. This is just a quick 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-influxdb_influxdb_1 ... done
   Creating xk6-output-influxdb_k6_1       ... done
   Creating xk6-output-influxdb_grafana_1  ... done

3. Use the k6 Docker image to run the k6 script and send metrics to the InfluxDB 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

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

   This repository includes a basic dashboard. If you want to build a custom Dashboard, contact the k6 team in Slack.

Compatibility API

The v2 includes a InfluxDB v1.8+ compatibility API that adds endpoints for communicating with an InfluxDB v1.

Client API usage differences summary:

1. Use the form username:password for an authentication token. Example: my-user:my-password. Use an empty string ("") if the server doesn't require authentication.
2. The organization parameter is not used. Use an empty string ("") where necessary.
3. Use the form database/retention-policy where a bucket is required. Skip retention policy if the default retention policy should be used. Examples: telegraf/autogen, telegraf.