K6

K6 is a command-line tool for API and system load testing. This integration uses K6's experimental-prometheus-rw output to write load-testing metrics to the DataKit Prometheus Remote Write endpoint, which then reports them to Guance. K6 does not require a persistent service; the load generator only needs network access to DataKit.

Configuration¶

Prerequisites¶

• Install K6 and verify that k6 version runs successfully.
• Install DataKit and ensure that the load generator can access DataKit on port 9529.
• Enable the prom_remote_write collector in DataKit.
• Assign a unique benchmark_id and testid to each load test to prevent data from different runs from being mixed.

Configure DataKit¶

Create prom_remote_write.conf under conf.d/prom in the DataKit installation directory, as shown below:

[[inputs.prom_remote_write]]
  path = "/prom_remote_write"
  methods = ["PUT", "POST"]

  # K6 metrics start with k6_. Write them to the k6 measurement and preserve their original names.
  job_as_measurement = false
  measurement_name = "k6"
  keep_exist_metric_name = true

After completing the configuration, restart DataKit for the changes to take effect.

Configure K6¶

Point the Remote Write URL to DataKit and use the experimental-prometheus-rw output:

export K6_PROMETHEUS_RW_SERVER_URL="http://<datakit-ip>:9529/prom_remote_write"
export K6_PROMETHEUS_RW_PUSH_INTERVAL="5s"
export K6_PROMETHEUS_RW_TREND_STATS="p(95),p(99),min,max"

k6 run \
  -o experimental-prometheus-rw \
  --tag benchmark_id="k6-demo-20260917" \
  --tag testid="baseline-r300-rep1" \
  script.js

If HTTP Basic Authentication is enabled on the DataKit endpoint, also set K6_PROMETHEUS_RW_USERNAME and K6_PROMETHEUS_RW_PASSWORD. Inject credentials through a secrets management system; never store real passwords in scripts or command history.

K6 Script Example¶

The following script runs at a constant arrival rate for 10 minutes. Replace the target URL with the actual test endpoint and adjust the number of VUs to match the service capacity:

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

export const options = {
  scenarios: {
    steady_load: {
      executor: 'constant-arrival-rate',
      rate: 300,
      timeUnit: '1s',
      duration: '10m',
      preAllocatedVUs: 100,
      maxVUs: 300,
    },
  },
};

export default function () {
  const response = http.get(`${__ENV.TARGET_URL}/health`);
  check(response, {
    'HTTP status is 200': (res) => res.status === 200,
  });
}

Verify Data¶

1. Check the K6 console and confirm that no HTTP errors or Remote Write output errors occurred during the test.
2. Open the metric query in Guance, select the k6 measurement, and filter by benchmark_id and testid.
3. Confirm that the following metrics are continuously reported throughout the test: total requests, failure rate, average duration, P95, P99, and maximum VUs.
4. Calculate the request rate from the cumulative request count; do not treat the cumulative total as RPS. The query window must be longer than K6_PROMETHEUS_RW_PUSH_INTERVAL, or the rate chart may contain gaps.

Metrics¶

The K6 measurement is named k6. The following table lists common K6 load-testing metrics, their units, and their meanings. Duration metrics are displayed in milliseconds. Ratio metrics have raw values from 0 to 1 and are multiplied by 100 when displayed as percentages.

All HTTP metrics include tags such as scenario, testid, and benchmark_id. Request-level metrics may also include method, url, name, status, error, and expected_response. Queries should filter by at least benchmark_id and testid; otherwise, data from different load-test runs will be aggregated.

Percentile metrics not configured in K6_PROMETHEUS_RW_TREND_STATS are not written. If you need P90, P95, or P99, configure them explicitly before starting K6, for example: K6_PROMETHEUS_RW_TREND_STATS="p(90),p(95),p(99),min,max".

References¶

• K6 Prometheus Remote Write
• Prometheus Remote Write