Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/grafana/xk6-output-influxdb
k6 extension to output real-time test metrics to an InfluxDB 2.x database.
https://github.com/grafana/xk6-output-influxdb
grafana-dashboard influxdb k6 k6-output xk6
Last synced: 28 days ago
JSON representation
k6 extension to output real-time test metrics to an InfluxDB 2.x database.
- Host: GitHub
- URL: https://github.com/grafana/xk6-output-influxdb
- Owner: grafana
- License: apache-2.0
- Created: 2021-10-18T09:36:15.000Z (about 3 years ago)
- Default Branch: main
- Last Pushed: 2024-08-29T08:58:45.000Z (2 months ago)
- Last Synced: 2024-09-28T15:01:31.270Z (about 1 month ago)
- Topics: grafana-dashboard, influxdb, k6, k6-output, xk6
- Language: Go
- Homepage:
- Size: 104 KB
- Stars: 62
- Watchers: 140
- Forks: 33
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: CODEOWNERS
Awesome Lists containing this project
- awesome-k6 - xk6-output-influxdb - Export results to InfluxDB v2. (Extensions / Official)
README
# xk6-output-influxdb
k6 extension for [InfluxDB v2](https://docs.influxdata.com/influxdb/v2.0), 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](https://k6.io/docs/results-visualization/influxdb-+-grafana) 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](https://go101.org/article/go-toolchain.html)
- Git
- [xk6](https://github.com/grafana/xk6#install)
1. Build with `xk6`:
```bash
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:
```bash
K6_INFLUXDB_ORGANIZATION= \
K6_INFLUXDB_BUCKET= \
K6_INFLUXDB_TOKEN= \
./k6 run -o xk6-influxdb=http://localhost:8086
```
**Using Docker**
This [Dockerfile](./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](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#organization). |
| K6_INFLUXDB_BUCKET | | The [Bucket](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#bucket). |
| K6_INFLUXDB_TOKEN | | The [Token](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#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](https://docs.influxdata.com/influxdb/v2.0/reference/glossary/#precision). |
# Docker Compose
This repo includes a [docker-compose.yml](./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.
```shell
docker compose up -d
```
```shell
# 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](https://k6.io/docs/using-k6/tags-and-groups/#test-wide-tags) with a unique identifier to segment the metrics into discrete test runs for the Grafana dashboards.
```shell
docker compose run --rm -T k6 run -
```
For convenience, the `docker-run.sh` can be used to simply:
```shell
./docker-run.sh samples/http_2.js
```
4. Visit http://localhost:3000/ to view results in Grafana.
> This repository includes a [basic dashboard](./grafana/dashboards/dashboard.yml). 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](https://docs.influxdata.com/influxdb/v2.0/reference/api/influxdb-1x) that adds endpoints for communicating with an InfluxDB v1.
>[Client API usage differences summary](https://github.com/influxdata/influxdb-client-go#influxdb-18-api-compatibility):
>
> 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.