TimescaleDB is a open-source database that extends PostgreSQL for better storage, processing, and analysis of time-series data at scale. If you want to know more about TimescaleDB, I recommend you look at the official documentation.
k6 can send metrics to various formats and systems. In this tutorial, we will send k6 metrics to TimescaleDB for scalable long-term storage, analytics, and easy querying with SQL.
To store metrics from k6 to TimescaleDB there are five steps you need to follow:
- Step 1: Installing self-hosted TimescaleDB from a pre-built Docker container.
- Step 2: Building the k6 binary with the TimescaleDB k6 extension.
- Step 3: Run k6 tests and send the k6 metrics to TimescaleDB.
- Step 4: Querying the TimescaleDB Database for k6 metrics.
- Step 5: Visualize k6 results with pre-built Grafana dashboards.
Ready to get started? Let's go.
Note that the instructions in this tutorial are tested on Ubuntu Linux. Commands may vary a little bit according to OS.
Run the k6 test and store results in TimescaleDB
Install self-hosted TimescaleDB from a pre-built Docker container
Docker is available for a variety of platforms Linux, MacOS and Windows. Find installation instructions for the preferred operating system here. You can verify the Docker installation with:
Open your Terminal/Command Prompt and run the TimescaleDB Docker image:
Run the docker commands as administrator or sudo if you get the error: permission denied while trying to connect to the Docker daemon socket.
Run the pulled image directly from the Docker container:
Verify whether the timescale container is up and running using the command below:
The response should be similar to the snippet below:
Building k6 with TimescaleDB support
xk6-output-timescaledb extends k6 to support sending k6 metrics in real-time to TimescaleDB. To built a k6 binary with this extension, first, ensure you have installed Go and Git. the following steps are:
Running the k6 test
For the purpose of this tutorial, we will prepare a simple k6 test. For example:
Now we can run the test using the k6 binary built previously. The format of the k6 run command is as follows:
Navigate to the folder of the k6 binary and run the following command:
After executing the test, k6 prints the test result summary in the terminal:
This section would provide some basic instructions about how to query the k6 metrics in TimescaleDB.
Connect to the k6 database through psql:
We can use the \d command to list all the tables in k6 database:
The samples table stores all the values of the k6 metrics. To get familiar with the schema of the samples table, let's list its columns:
To get the average value of each metric, we can query as follows:
You can now check these results with the results reported previously by the k6 output. For example:
- The k6 output showed: http_req_duration..............: avg=271.13ms
- The SQL query showed: http_req_duration | 271.01705154759924
The benefit of extracting k6 metrics from SQL queries is that you have complete flexibility to query and filter your testing results. To learn how k6 generates time-series data and what type of data, refer to the k6 metrics documentation.
Clone the repository to get started.
Put your k6 scripts in our case (the script.js file mentioned above) in the scripts directory.
Start the docker compose environment.
It starts the Grafana and TimescaleDB containers, and build the k6 binary.
Use the k6 docker image to run the k6 script and send the metrics to the TimescaleDB as follows:
The above command tags the metrics with a testid (the value can be whatever you want to use as a unique identifier for test runs like a date string, numeric ID etc.). This tag enables the Grafana dashboards to segment the result data into discrete test runs. It will allow to select and filter the results of a test run.
After running the test, you can check the results by visiting the Grafana at http://localhost:3000. Here is a sample output of a Grafana Dashboard in the browser.
In this tutorial, we have provided the instructions to start storing the results of your k6 tests in TimescaleDB. If you have any questions about this project or feature requests, follow the xk6-output-timescaledb and open a new issue.