No results for

Powered byAlgolia

Prometheus Remote Write

With the Prometheus remote-write integration, you can export metrics from k6 Cloud to a self-hosted or managed Prometheus instance.

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.

Configuration Parameters

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:

export const options = {
ext: {
loadimpact: {
apm: [
{
provider: 'prometheus',
remoteWriteURL: '<Remote Write URL>',
// optional parameters
credentials: {
token: '<token>',
},
includeDefaultMetrics: true,
metrics: ['http_req_sending', 'my_rate', 'my_gauge'], //...other options,
includeTestRunId: false,
resampleRate: 3,
},
],
},
},
};
NameDescription
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.
credentialsThe credentials to authenticate with the Prometheus remote write instance.
Read more on supported authentication mechanisms.
includeDefaultMetricsWhether it exports the default APM metrics: data_sent, data_received, http_req_duration, http_reqs, iterations, and vus. Default is true.
metricsList of metrics to export.
For details on how to specify metrics, see the subsequent section.
includeTestRunIdWhether 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.
resampleRateThe 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.

Metric configuration

Each entry in metrics parameter can be an object with following keys:

NameDescription
sourceMetric(required)Name of k6 builtin or custom metric to export, optionally with tag filters.
Tag filtering follows Prometheus selector syntax,
Example: http_reqs{name="http://example.com",status!="500"}
targetMetricName of resulting metric in Grafana/Prometheus. Default is the name of the source metric with a k6_ prefix
Example: k6_http_reqs
keepTagsList 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

export const options = {
ext: {
loadimpact: {
apm: [
{
// ...
includeDefaultMetrics: false,
includeTestRunId: true,
metrics: [
// keep vus metrics for whole test run
'vus',
// total byte count for data sent/received by k6
'data_sent',
'data_received',
// export checks metric, keeping 'check' (name of the check) tag
{
sourceMetric: 'checks',
keepTags: ['check'],
},
// export HTTP durations from 'default' scenario,
// keeping only successful response codes (2xx, 3xx), using regex selector syntax
{
sourceMetric: 'http_req_duration{scenario="default",status=~"[23][0-9][0-9]"}',
targetMetric: 'k6_http_request_duration', // name of metric as it appears in Prometheus
keepTags: ['name', 'method', 'status'],
},
// count HTTP responses with status 500
{
sourceMetric: 'http_reqs{status="500"}',
targetMetric: 'k6_http_server_errors_count',
keepTags: ['scenario', 'group', 'name', 'method'],
},
],
},
],
},
},
};

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

credentials: {
// The username in HTTP basic authentication
username: "<username>",
// The password in HTTP basic authentication
password: "<password>"
}

Bearer token authentication

credentials: {
// The bearer token without the prefix/type
token: "<token>"
}

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.

Read more