Concepts on Grafana Labs

Graceful stop

Mon, 21 Sep 2026 15:16:28 +0000

Graceful stop

The gracefulStop is a period at the end of the test in which k6 lets iterations in progress finish.

If a test has a set duration or ramp down, its possible that k6 could interrupt iterations in progress. These interruptions can lead to skewed metrics and unexpected test results. To deal with this, k6 scenarios have a gracefulStop. For the ramping-vus executor, a related option, gracefulRampDown, exists to let VUs finish as their number ramps down.

Graceful stop

The gracefulStop option is available for all executors. It specifies a duration that k6 will wait before forcefully interrupting an iteration. The default value is 30s.

Graceful stop example

import http from 'k6/http';

export const options = {
  discardResponseBodies: true,
  scenarios: {
    contacts: {
      executor: 'constant-vus',
      vus: 100,
      duration: '10s',
      gracefulStop: '3s',
    },
  },
};

export default function () {
  const delay = Math.floor(Math.random() * 5) + 1;
  http.get(`https://quickpizza.grafana.com/api/delay/${delay}`);
}

Running this script would result in something like:

running (13.0s), 000/100 VUs, 349 complete and 23 interrupted iterations
contacts ✓ [======================================] 100 VUs  10s

Notice that even though the total test duration is 10s, the actual execution time was 13s because of gracefulStop, giving the VUs a 3s additional time to complete iterations in progress. 23 of the iterations currently in progress did not complete within this window and was therefore interrupted.

The `gracefulRampDown`

In addition to gracefulStop, the ramping-vus executor also has a gracefulRampDown.

When the target value for a stage is lower than the target for the previous stage, k6 might need to stop some VUs that were started during the previous stages. The gracefulRampDown option controls how long these VUs have to finish currently before k6 interrupts them.

To get an idea of how gracefulRampDown works, you can run the following script with k6 run --verbose. In this script, the iteration sleep time exceeds the gracefulRampdown time. So, as k6 ramps down to reach the target of the second stage, it must forcibly interrupt VUs. The --verbose flag will log to your console when VUs start, enter the grace period, and are forcibly interrupted.

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

export const options = {
  discardresponsebodies: true,
  scenarios: {
    contacts: {
      executor: 'ramping-vus',
      startvus: 0,
      stages: [
        { duration: '10s', target: 10 },
        { duration: '10s', target: 0 },
      ],
      gracefulRampDown: '1s',
    },
  },
};

export default function () {
  http.get('https://test.k6.io/contacts.php');
  // adding sleep beyond so that iterations are longer than rampdown
  sleep(5);
}

Arrival-rate VU allocation

Mon, 21 Sep 2026 15:16:28 +0000

Arrival-rate VU allocation

In arrival-rate executors, as long as k6 has VUs available, it starts iterations according to your target rate. The ability to set iteration rate comes with a bit more configuration complexity: you must pre-allocate a sufficient number of VUs. In other words, before the tests runs, you must both:

Configure load (as new iterations per unit of time)
Ensure that you’ve allocated enough VUs.

Read on to learn about how k6 allocates VUs in the arrival-rate executors.

Caution
In cloud tests, preAllocatedVUs count against your subscription.

When planning a test, consider doing a trial initialization on a local machine to ensure you’re allocating VUs efficiently.

Pre-allocation in arrival-rate executors

As open-model scenarios, arrival-rate executors start iterations according to a configured rate. For example, you can configure arrival-rate executors to start 10 iterations each second, or minute, or hour. This behavior is opposed to the closed-model scenarios, in which VUs wait for one iteration to finish before starting another

Each iteration needs a VU to run it. Because k6 VUs are single threaded, like other JavaScript runtimes, a VU can only run a single iteration (and its event loop) at a time. To ensure you have enough, you must pre-allocate a sufficient number.

In your arrival-rate configuration, three properties determine the iteration rate:

k6 starts rate number of iterations evenly across the timeUnit (default 1s).
preAllocatedVUs sets the number of VUs to initialize to meet the target iteration rate.

For example, with a constant-arrival-rate executor and rate: 10, k6 tries to start a new iteration every 100 milliseconds. If the scenario has rate: 10, timeUnit: '1m', k6 tries to start a new iteration every 6 seconds. Whether it can start the target iteration rate depends on whether the number of allocated VUs is sufficient.

export const options = {
  scenarios: {
    constant_load: {
      executor: 'constant-arrival-rate',
      preAllocatedVUs: 10,
      rate: 10,
      timeUnit: '1m',
    },
  },
};

In practice, determining the right number of VUs to be able to reach the target iteration rate might take some trial and error, as the necessary VUs entirely depends on what your iteration code looks like and how quickly the system under test can process requests.

How k6 uses allocated VUs

Before an arrival-rate scenario starts, k6 first initializes the number of preAllocatedVUs. When the test runs, the number of available preAllocatedVUs determines how many iterations k6 can start. k6 tries to reach the target iterations per second, and one of two things can happen:

If the executor	Then..
Has enough VUs	the extra VUs are “idle,” ready to be used when needed.
Has insufficient VUs.	k6 emits a `dropped_iterations` metric for each iteration that it can’t run.

Iteration duration affects the necessary allocation

The necessary allocation depends on the iteration duration: longer durations need more VUs.

In a perfect world, you could estimate the number of pre-allocated VUs with this formula:

preAllocatedVUs = [median_iteration_duration * rate] + constant_for_variance

In the real world, if you know exactly how long an iteration takes, you likely don’t need to run a test. What’s more, as the test goes on, iteration duration likely increases. If response times slow so much that k6 lacks the VUs to start iterations at the desired rate, the allocation might be insufficient and k6 will drop iterations.

To determine your strategy, you can run tests locally and gradually add more pre-allocated VUs. As dropped iterations can also indicate that the system performance is degrading, this early experimentation can provide useful data on its own.

You probably don’t need `maxVUs`

Caution
In cloud tests, the number of maxVUs counts against your subscription, overriding the number set by preAllocatedVUs.

The arrival-rate executors also have a maxVUs property. If you set it, k6 runs in this sequence:

Pre-allocate the preAllocatedVUs.
Run the test, trying to reach the target iteration rate.
If the target exceeds the available VUs, allocate another VU.
If the target still exceeds available VUs, continue allocating VUs until reaching the number set by maxVUs.

Though it seems convenient, you should avoid using maxVUs in most cases. Allocating VUs has CPU and memory costs, and allocating VUs as the test runs can overload the load generator and skew results. In Cloud tests, the number of maxVUs count against your subscription. This is because k6 must allocate sufficient resources for maxVUs to be initialized, even if they never are. In almost all cases, the best thing to do is to pre-allocate the number of VUs you need beforehand.

Some of the times it might make sense to use maxVUs include:

To determine necessary allocation in first-time tests
To add a little “cushion” to the pre-allocated VUs that you expect the test needs
In huge, highly distributed tests, in which you need to carefully scale load generators as you increment VUs.

You can’t guarantee which VU runs an iteration

As with all executors, you can’t predict the specific VU that an arrival-rate executor uses for a specific iteration. As the test runs on, the executor might use some or all of the allocated VUs, even if it never needs the entire allocated number to reach the iteration rate.

Dropped iterations

Mon, 21 Sep 2026 15:16:28 +0000

Dropped iterations

Sometimes, a scenario can’t run the expected number of iterations. k6 tracks the number of unsent iterations in a counter metric, dropped_iterations. The number of dropped iterations can be valuable data when you debug executors or analyze results.

Dropped iterations usually happen for one of two reasons:

The executor configuration is insufficient.
The SUT can’t handle the configured VU arrival rate.

Dropped iterations happen for different reasons in different types of executors.

With shared-iterations and per-vu-iterations, iterations drop if the scenario reaches its maxDuration before all iterations finish. To mitigate this, you likely need to increase the value of the duration.

With constant-arrival-rate and ramping-arrival-rate, iterations drop if there are no free VUs. If it happens at the beginning of the test, you likely just need to allocate more VUs. If this happens later in the test, the dropped iterations might happen because SUT performance is degrading and iterations are taking longer to finish.

At a certain point of high latency or longer iteration durations, k6 will no longer have free VUs to start iterations with at the configured rate. As a result, the executor will drop iterations.

The reasons for these dropped iterations vary:

The SUT response has become so long that k6 starts dropping scheduled iterations from the queue.
The SUT iteration duration has become so long that k6 needs to schedule more VUs to reach the target arrival rate, exceeding the number of scheduled iterations.

As the causes vary, dropped iterations might mean different things. A few dropped iterations might indicate a quick network error. Many dropped iterations might indicate that your SUT has completely stopped responding.

When you design your test, consider what an acceptable rate of dropped iterations is (the error budget). To assert that the SUT responds within this error budget, you can use the dropped_iterations metric in a Threshold.

Open and closed models

Mon, 21 Sep 2026 15:16:28 +0000

Open and closed models

Different k6 executors have different ways of scheduling VUs. Some executors use the closed model, while the arrival-rate executors use the open model.

In short, in the closed model, VU iterations start only when the last iteration finishes. In the open model, on the other hand, VUs arrive independently of iteration completion. Different models suit different test aims.

Closed Model

In a closed model, the execution time of each iteration dictates the number of iterations executed in your test. The next iteration doesn’t start until the previous one finishes.

Thus, in a closed model, the start or arrival rate of new VU iterations is tightly coupled with the iteration duration (that is, time from start to finish of the VU’s exec function, by default the export default function):

import http from 'k6/http';

export const options = {
  scenarios: {
    closed_model: {
      executor: 'constant-vus',
      vus: 1,
      duration: '1m',
    },
  },
};

export default function () {
  // The following request will take roughly 6s to complete,
  // resulting in an iteration duration of 6s.

  // As a result, New VU iterations will start at a rate of 1 per 6s,
  // and we can expect to get 10 iterations completed in total for the
  // full 1m test duration.

  http.get('https://quickpizza.grafana.com/api/delay/6');
}

Running this script would result in something like:


running (1m01.5s), 0/1 VUs, 10 complete and 0 interrupted iterations
closed_model ✓ [======================================] 1 VUs  1m0s

Drawbacks of using the closed model

When the duration of the VU iteration is tightly coupled to the start of new VU iterations, the target system’s response time can influence the throughput of the test. Slower response times means longer iterations and a lower arrival rate of new iterations―and vice versa for faster response times. In some testing literature, this problem is known as coordinated omission.

In other words, when the target system is stressed and starts to respond more slowly, a closed model load test will wait, resulting in increased iteration durations and a tapering off of the arrival rate of new VU iterations.

This effect is not ideal when the goal is to simulate a certain arrival rate of new VUs, or more generally throughput (e.g. requests per second).

Open model

Compared to the closed model, the open model decouples VU iterations from the iteration duration. The response times of the target system no longer influence the load on the target system.

To fix this problem of coordination, you can use an open model, which decouples the start of new VU iterations from the iteration duration. This reduces the influence of the target system’s response time.

k6 implements the open model with two arrival rate executors: constant-arrival-rate and ramping-arrival-rate:

import http from 'k6/http';

export const options = {
  scenarios: {
    open_model: {
      executor: 'constant-arrival-rate',
      rate: 1,
      timeUnit: '1s',
      duration: '1m',
      preAllocatedVUs: 20,
    },
  },
};

export default function () {
  // With the open model arrival rate executor config above,
  // new VU iterations will start at a rate of 1 every second,
  // and we can thus expect to get 60 iterations completed
  // for the full 1m test duration.
  http.get('https://quickpizza.grafana.com/api/delay/6');
}

Running this script would result in something like:

running (1m09.3s), 000/011 VUs, 60 complete and 0 interrupted iterations
open_model ✓ [======================================] 011/011 VUs  1m0s  1 iters/s

Concepts on Grafana Labs

Graceful stop

Graceful stop

Graceful stop

Graceful stop example

The gracefulRampDown

Arrival-rate VU allocation

Arrival-rate VU allocation

Pre-allocation in arrival-rate executors

How k6 uses allocated VUs

Iteration duration affects the necessary allocation

You probably don’t need maxVUs

You can’t guarantee which VU runs an iteration

Dropped iterations

Dropped iterations

Configuration-related iteration drops

SUT-related iteration drops

Open and closed models

Open and closed models

Closed Model

Drawbacks of using the closed model

Open model

The `gracefulRampDown`

You probably don’t need `maxVUs`