With the Prometheus remote write integration, you can export metrics from k6 Cloud to a self-hosted or managed Prometheus instance. If you want to export local results over the remote write protocol, refer to Prometheus remote write.
With the Prometheus integration, you can do the following:
- Store k6 metrics on your Prometheus instances.
- Run PromQL queries on k6 metrics.
- Correlate testing results with other system metrics collected with Prometheus.
k6 currently offers similar integrations with Cloud APM solutions: Azure Monitor, Datadog, Grafana Cloud, and New Relic. If you use any of these solutions, we recommend integrating your APM solution first.
⭐️ Prometheus remote write and Cloud APM integrations are available on Pro and Enterprise plans, as well as the annual Team plan and Trial.
You can enable this integration only with the apm option in the k6 script.
The apm option configures how to export k6 Cloud metrics to the supported monitoring solutions. You can use multiple configuration blocks to export simultaneously to different monitoring providers.
The parameters for sending metrics to a Prometheus Remote Write instance are as follows:
|provider(required)||For this integration, the value must be prometheus.|
|remoteWriteURL(required)||URL of the Prometheus remote write endpoint. |
For example: http://monitoring.example.com:9090/api/v1/write.
|credentials||The credentials to authenticate with the Prometheus remote write instance. |
Read more on supported authentication mechanisms.
|includeDefaultMetrics||Whether it exports the default APM metrics: data_sent, data_received, http_req_duration, http_reqs, iterations, and vus. Default is true.|
|metrics||List of metrics to export. |
For details on how to specify metrics, see the subsequent section.
|includeTestRunId||Whether all the exported metrics include a test_run_id tag whose value is the k6 Cloud test run id. Default is false. |
Be aware that enabling this setting might increase the cost of your APM provider.
|resampleRate||The rate by which the metrics are resampled and sent to the APM provider in seconds. Default is 3 and acceptable values are integers between 1 and 10.|
Each entry in metrics parameter can be an object with following keys:
|sourceMetric(required)||Name of k6 builtin or custom metric to export, optionally with tag filters. |
Tag filtering follows Prometheus selector syntax,
|targetMetric||Name of resulting metric in Grafana/Prometheus. Default is the name of the source metric with a k6_ prefix |
|keepTags||List of tags to preserve when exporting time series.|
keepTags can have a high cost
Most cloud platforms charge clients based on the number of time series stored.
When exporting a metric, every combination of kept-tag values becomes a distinct time series in Prometheus. While this granularity can help test analysis, it will incur high costs with thousands of time series.
For example, if you add keepTags: ["name"] on http_* metrics, and your load test calls many dynamic URLs, the number of produced time series can build up very quickly. Refer to URL Grouping for how to reduce the value count for a name tag.
k6 recommends exporting only tags that are necessary and don't have many distinct values.
Metric configuration detailed example
Supported authentication mechanisms
Currently, the integration supports only bearer token and HTTP basic authentication mechanisms. To configure one of the supported auhentication methods, set the credentials option as follows.
HTTP basic authentication
Bearer token authentication
Run the cloud test
Once you have configured the apm settings in the k6 script, you can launch the cloud test from the CLI or Script Editor as usual.
When running the cloud test, k6 Cloud will export the metrics to the Prometheus endpoint with a slight delay.