Tutorials 06 May 2019

How to send k6 metrics to Datadog


This article will show how you can use k6 to store the results of your load tests into Datadog.

Datadog is a monitoring and analytics platform that can help you to get full visibility of the performance of your applications. We ❤️ Datadog at LoadImpact and use it to monitor the different services of our Load Testing platform.

k6 is our open source load testing tool for testing the performance of your applications. One of the attractive features of k6 is that you can output the result of your load tests to different sources; for example:
  • stdout/console
  • JSON
  • InfluxDB
  • Kafka
  • LoadImpact

And now, you can send data from your k6 load test into Datadog for further analysis and correlation with Datadog analytics/metrics.


  • k6 v0.24.0 (or above) is installed. If you do not have this installed, please refer to the official k6 installation page. You can verify your current k6 version by command k6 version.
  • Docker is installed. If you do not have this installed, please refer to the official docker installation page.

Setup Datadog Agent

According to Datadog documentation: "The easiest way to get your custom application metrics into Datadog is to send them to DogStatsD, a metrics aggregation service bundled with the Datadog Agent". That means that we need to setup a Datadog Agent in order to utilise DogStatsD service. For the sake of simplicity we will run Datadog Agent v6 (latest at the moment) as a docker container. Here is official Datadog Docker Agent page.

To run a container execute next command in shell:

docker run -d \
    --name datadog \
    -v /var/run/docker.sock:/var/run/docker.sock:ro \
    -v /proc/:/host/proc/:ro \
    -v /sys/fs/cgroup/:/host/sys/fs/cgroup:ro \
    -e DD_SITE="datadoghq.com" \
    -p 8125:8125/udp \

Here we add environment variables -e DD\_SITE to indicate the destination site for the metrics (if your account is registered in Europe, use datadoghq.eu instead), -e DD\_DOGSTATSD\_NON\_LOCAL\_TRAFFIC=1 since it is required to send custom metrics and -e DD\_API\_KEY=<YOUR\_DATADOG\_API\_KEY> for authorization. Also by -p 8125:8125/udp we bind 8125 UDP port of a container to 8125 UDP port of our Host so that k6 will be able to send metrics to DogStatsD. The volume mounts are required for Datadog Agent functionality. That's it, from now Datadog Agent container will be listening on 8125/UDP port until we close it (by hitting Ctrl+C in the shell where we started a container).

Run k6 script

Next step is to send our k6 metrics to already running Datadog agent.

Lets create a simple k6 script.js:

import http from 'k6/http';
import { check, sleep } from 'k6';

export let options = {
  stages: [{ duration: '300s', target: 50 }],
  thresholds: {
    http_req_duration: ['p(95)<3']
export default function() {
  let res = http.get('https://test.loadimpact.com/');
  check(res, {
    'is welcome header present': r =>
      r.body.indexOf('Welcome to the LoadImpact') !== -1

Let's run this script locally, execute next command in shell:
k6 run script.js


To output k6 metrics to Datadog, we need to add --out datadog option and define some env variables (find env variables description below):
K6_DATADOG_ADDR=localhost:8125 \
K6_DATADOG_NAMESPACE=custom_metric. \
k6 run --out datadog script.js

Here we specify next environment variables to configure k6:
  • K6_DATADOG_ADDR=localhost:8125 configures at which address Datadog agent is listening. Default value is localhost:8125 too, so we can omit it in our case.
  • K6_DATADOG_NAMESPACE=custom_metric. configures a prefix before all the metric names. Default value is k6..
Other available environment variables:
  • K6_DATADOG_PUSH_INTEVAL configures how often data batches are sent. The default value is 1s.
  • K6_DATADOG_BUFFER_SIZE configures buffer size. The default value is 20.
  • K6_DATADOG_TAG_BLACKLIST configures tags that should NOT be sent to DataDog. Default is equal to '' (nothing). This is a comma separated list, example: K6_DATADOG_TAG_BLACKLIST="tag1, tag2".


View and analyze metrics in Datadog

While k6 is running, metrics should be already available in DataDog, we can verify that by looking at Datadog Metrics Explorer:

As seen from the picture above our metrics are available with prefix custom_metric., which we specified in k6 run command. Also we see that DataDog tags are assigned (in our case we picked method:get and status:200). k6 sends k6 tags as datadog metric tags. Since metrics are available in Datadog you can monitor or analyze them as usual Datadog metrics, creating monitors or dashboards.


The Datadog agent uses an extension of the StatsD daemon to capture the k6 metrics, aggregate and send them to the Datadog service. Because StatsD is a very popular open source project, we also took this project as an opportunity to support the k6 integration with StatsD.

Now, k6 can also push the metrics to StatsD and make the StatsD daemon to send your load test metrics to other backend services.

k6 run --out statsd script.js

Like the Datadog integration, there are also a few k6/StatsD options that can be configured.


If you followed along, you should now have a running Datadog agent and used the environment variables to define the output to Datadog from your k6 load test. We ❤️ Datadog here at LoadImpact and developing a new k6 feature to be able push metrics to Datadog easily was something we thought was important, this tutorial has shown how to do it in practice.

Many thanks to the contributors @ivoreis and @MStoykov for their work on DataDog output feature of k6 v0.24.0.

And finally, if you want to pull metrics from Datadog into your k6 test, we recommend you read our guide: "How to configure Datadog alerts to fail your load test"

As always, we are looking forward to hearing about your load testing experience; if you have any feedback, don’t hesitate to contact our support team or any k6 channel: community forum, k6 github repository or Slack.

< Back to all posts