Open source

Create custom metrics

Besides the built-in metrics, you can create custom metrics. For example, you can compute a metric for your business logic, or use the Response.timings object to create a metric for a specific set of endpoints.

Each metric type has a constructor to create a custom metric. The constructor creates a metric object of the declared type. Each type has an add method to take metric measurements.

If you need help constructing a custom metric, read the following sections of this document. They document the procedure and provide examples. If you’re comfortable with these already, you might prefer to read the reference documentation for each metric constructor. Each topic has examples to make a custom metric and create thresholds from it.

Create a custom metric


Custom metrics must be created in init context. This limits memory and ensures that k6 can validate that all thresholds are evaluating defined metrics.

The generic procedure to create a custom metric is as follows:

  1. Import the k6/metrics module. Optionally, specify the type of metrics you want to create with a named import:

    import { Trend } from 'k6/metrics';
  2. In init context, construct a new custom-metric object.

    For example, the following creates a custom trend. The object in the script is called myTrend, and its metric appears in the results output as waiting_time.

    const myTrend = new Trend('waiting_time');
  3. In the VU iteration code, use the add method to take a measurement.

Example: create a trend metric for waiting time

This VU code makes a request then adds the timing value of the request to the myTrend object.

import http from 'k6/http';
import { Trend } from 'k6/metrics';

const myTrend = new Trend('waiting_time');

export default function () {
  const r = http.get('');
  console.log(; // waiting_time

View custom metric results

Custom metrics appear in Results output in both the end-of-test summary and in the granular data points. Each metric type has specific aggregation methods. You can also optionally tag any value for a custom metric. You can use these tags to filter test results.

Here’s how the output of the preceding script might look in the end-of-test summary. Since the metric is a trend, k6 calculates various trends based on the number of values and their summation.

$ k6 run script.js

  INFO[0001] waiting_time                                  source=console

  iteration_duration.............: avg=1.15s    min=1.15s    med=1.15s    max=1.15s    p(90)=1.15s    p(95)=1.15s
  iterations.....................: 1     0.864973/s
  waiting_time...................: avg=265.245396 min=265.245396 med=265.245396 max=265.245396 p(90)=265.245396 p(95)=265.245396


Custom metrics are collected from VU threads only at the end of a VU iteration. For long-running scripts, custom metrics might appear only after the test runs a while.

Read more

The k6/metrics has examples for defining each type of custom metric, and for defining a threshold on the metric.