Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/grafana/xk6-output-timescaledb
k6 extension to output real-time test metrics to TimescaleDB.
https://github.com/grafana/xk6-output-timescaledb
grafana-dashboard k6 k6-output timescaledb xk6
Last synced: 2 months ago
JSON representation
k6 extension to output real-time test metrics to TimescaleDB.
- Host: GitHub
- URL: https://github.com/grafana/xk6-output-timescaledb
- Owner: grafana
- License: apache-2.0
- Created: 2021-07-29T06:12:57.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2024-06-10T09:35:37.000Z (6 months ago)
- Last Synced: 2024-09-28T15:01:58.262Z (2 months ago)
- Topics: grafana-dashboard, k6, k6-output, timescaledb, xk6
- Language: Go
- Homepage:
- Size: 1.16 MB
- Stars: 30
- Watchers: 142
- Forks: 14
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
- awesome-k6 - xk6-output-timescaledb - Export k6 results to TimescaleDB. (Extensions / Official)
- awesome-k6 - xk6-output-timescaledb - Export k6 results to TimescaleDB. (Extensions / Official)
README
# xk6-output-timescaledb
`xk6-output-timescaledb` is a [k6 extension](https://k6.io/docs/extensions/) to send k6 metrics to TimescaleDB in a predefined schema.
# Install
You will need [go](https://golang.org/)
```bash
# 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](./Dockerfile) builds a docker image with the k6 binary.
# Configuration
First, find the [Postgres connection string](https://www.postgresql.org/docs/current/libpq-connect.html#LIBPQ-CONNSTRING) 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](https://k6.io/docs/using-k6/options/#results-output) as `timescaledb=YOUR_POSTGRES_CONNECTION_STRING`. For example:
```bash
k6 run -o timescaledb=postgresql://k6:k6@timescaledb:5432/k6 script.js
```
or set an environment variable:
```bash
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](./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.
3. Start the docker compose environment.
```shell
docker compose up -d
```
```shell
# Output
Creating xk6-output-timescaledb_grafana_1 ... done
Creating xk6-output-timescaledb_k6_1 ... done
Creating xk6-output-timescaledb_timescaledb_1 ... done
```
4. 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](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](#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
```
> Note that the [docker-compose command to run k6 tests](https://k6.io/docs/getting-started/running-k6/) might differ depending your OS.
5. 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
