Executors on Grafana Labs

Shared iterations

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

Shared iterations

The shared-iterations executor shares iterations between the number of VUs. The test ends once k6 executes all iterations.

For a shortcut to this executor, use the vus and iterations options.

Note
Iterations are not guaranteed to be evenly distributed with this executor. VU that executes faster will complete more iterations than slower VUs.

To guarantee that every VU completes a specific, fixed number of iterations, use the per-VU iterations executor.

Options

Besides the common configuration options, this executor has the following options:

Option	Type	Description	Default
vus	integer	Number of VUs to run concurrently.	`1`
iterations	integer	Total number of script iterations to execute across all VUs.	`1`
maxDuration	string	Maximum scenario duration before it’s forcibly stopped (excluding `gracefulStop`).	`"10m"`

When to use

This executor is suitable when you want a specific number of VUs to complete a fixed number of total iterations, and the amount of iterations per VU is unimportant. If the time to complete a number of test iterations is your concern, this executor should perform best.

An example use case is for quick performance tests in the developement build cycle. As developers make changes, they might run the test against the local code to test for performance regressions. Thus the executor works well with a shift-left policy, where emphasizes testing performance early in the development cycle, when the cost of a fix is lowest.

Example

The following example schedules 200 total iterations shared by 10 VUs with a maximum test duration of 30 seconds.

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

export const options = {
  discardResponseBodies: true,
  scenarios: {
    contacts: {
      executor: 'shared-iterations',
      vus: 10,
      iterations: 200,
      maxDuration: '30s',
    },
  },
};

export default function () {
  http.get('https://test.k6.io/contacts.php');
  // Injecting sleep
  // Sleep time is 500ms. Total iteration time is sleep + time to finish request.
  sleep(0.5);
}

Observations

The following graph depicts the performance of the example script:

Based upon our test scenario inputs and results:

Test is limited to a fixed number of 200 iterations of the default function;
The number of VUs is fixed to 10, and are initialized before the test begins;
Each iteration of the default function is expected to be roughly 515ms, or ~2/s;
Maximum throughput (highest efficiency) is therefore expected to be ~20 iters/s, 2 iters/s * 10 VUs;
The maximum throughput is maintained for a larger portion of the test;
The distribution of iterations may be skewed: one VU may have performed 50 iterations, another only 10.

Per VU iterations

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

Per VU iterations

With the per-vu-iterations executor, each VU executes an exact number of iterations. The total number of completed iterations equals vus * iterations.

Options

Besides the common configuration options, this executor has the following options:

Option	Type	Description	Default
vus	integer	Number of VUs to run concurrently.	`1`
iterations	integer	Number of `exec` function iterations to be executed by each VU.	`1`
maxDuration	string	Maximum scenario duration before it’s forcibly stopped (excluding `gracefulStop`).	`"10m"`

When to use

Use this executor if you need a specific number of VUs to complete the same number of iterations. This can be useful when you have fixed sets of test data that you want to partition between VUs.

Example

The following example schedules 10 VUs to execute 20 iterations each. The test runs 200 total iterations and has a maximum duration of 30 seconds.

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

export const options = {
  discardResponseBodies: true,
  scenarios: {
    contacts: {
      executor: 'per-vu-iterations',
      vus: 10,
      iterations: 20,
      maxDuration: '30s',
    },
  },
};

export default function () {
  http.get('https://test.k6.io/contacts.php');
  // Injecting sleep
  // Sleep time is 500ms. Total iteration time is sleep + time to finish request.
  sleep(0.5);
}

Observations

The following graph depicts the performance of the example script:

Based upon our test scenario inputs and results:

The number of VUs is fixed at 10, and are initialized before the test begins;
Total iterations are fixed at 20 iterations per VU, i.e. 200 iterations, 10 VUs * 20 iters each;
Each iteration of the default function is expected to be roughly 515ms, or ~2/s;
Maximum throughput (highest efficiency) is therefore expected to be ~20 iters/s, 2 iters/s * 10 VUs;
The maximum throughput is reached, but not maintained;
Because the distribution of iterations is even among VUs, a fast VU may finish early and be idle for the remainder of the test, thereby lowering efficiency;
Total duration of 9 seconds is slightly longer than shared iterations due to lower efficiency;
Overall test duration lasts as long as the slowest VU takes to complete 20 requests.

Constant VUs

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

Constant VUs

With the constant-vus executor, a fixed number of VUs execute as many iterations as possible for a specified amount of time.

For a shortcut to this executor, use the VUs and duration options.

Options

Besides the common configuration options, this executor has the following options:

Option	Type	Description	Default
duration^(required)	string	Total scenario duration (excluding `gracefulStop`).	-
vus	integer	Number of VUs to run concurrently.	`1`

When to use

Use this executor if you need a specific number of VUs to run for a certain amount of time.

Example

This examples schedules 10 VUs to run constantly for a duration 30 seconds.

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

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

export default function () {
  http.get('https://test.k6.io/contacts.php');
  // Injecting sleep
  // Total iteration time is sleep + time to finish request.
  sleep(0.5);
}

Observations

The following graph depicts the performance of the example script:

Based upon our test scenario inputs and results:

The number of VUs is fixed at 10, and are initialized before the test begins;
Overall test duration is fixed at the configured 30 second duration;
Each iteration of the default function is expected to be roughly 515ms, or ~2/s;
Maximum throughput (highest efficiency) is therefore expected to be ~20 iters/s, 2 iters/s * 10 VUs;
We see that the maximum throughput is reached and maintained for the majority of the test;
Approximately 600 iterations are therefore performed in total, 30 seconds * 20 iters/s.

Ramping VUs

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

Ramping VUs

With the ramping-vus executor, a variable number of VUs executes as many iterations as possible for a specified amount of time.

For a shortcut to this executor, use the stages option.

Options

Besides the common configuration options, this executor has the following options:

Option	Type	Description	Default
stages^(required)	array	Array of objects that specify the target number of VUs to ramp up or down to.	`[]`
startVUs	integer	Number of VUs to run at test start.	`1`
gracefulRampDown	string	Time to wait for an already started iteration to finish before stopping it during a ramp down.	`"30s"`

When to use

This executor is a good fit if you need VUs to ramp up or down during specific periods of time.

Example

This example schedules a two-stage test, ramping up from 0 to 10 VUs over 20 seconds, then down to 0 VUs over 10 seconds.

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

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

export default function () {
  http.get('https://test.k6.io/contacts.php');
  // Injecting sleep
  // Sleep time is 500ms. Total iteration time is sleep + time to finish request.
  sleep(0.5);
}

Note
With gracefulRampDown set to 0 seconds, some iterations might be interrupted during the ramp down stage.

Observations

The following graph depicts the performance of the example script:

Based upon our test scenario inputs and results:

The configuration defines 2 stages for a total test duration of 30 seconds;
Stage 1 ramps up VUs linearly from the startVUs of 0 to the target of 10 over a 20 second duration;
From the 10 VUs at the end of stage 1, stage 2 then ramps down VUs linearly to the target of 0 over a 10 second duration;
Each iteration of the default function is expected to be roughly 515ms, or ~2/s;
As the number of VUs changes, the iteration rate directly correlates; each addition of a VU increases the rate by about 2 iters/s, whereas each subtraction of a VU reduces by about 2 iters/s;
The example performed ~300 iterations over the course of the test.

Get the stage index

To get the current running stage index, use the getCurrentStageIndex helper function from the k6-jslib-utils library. It returns a zero-based number equal to the position in the shortcut stages array or in the executor’s stages array.

import { getCurrentStageIndex } from 'https://jslib.k6.io/k6-utils/1.3.0/index.js';

export const options = {
  stages: [
    { target: 10, duration: '30s' },
    { target: 50, duration: '1m' },
    { target: 10, duration: '30s' },
  ],
};

export default function () {
  if (getCurrentStageIndex() === 1) {
    console.log('Running the second stage where the expected target is 50');
  }
}

Using this feature, it is possible to automatically tag using the current running stage. Check the Tagging stages section for more details.

Constant arrival rate

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

Constant arrival rate

With the constant-arrival-rate executor, k6 starts a fixed number of iterations over a specified period of time. It is an open-model executor, meaning iterations start independently of system response (for details, read Open and Closed models).

This executor continues to start iterations at the given rate as long as VUs are available. The time to execute an iteration can vary with test logic or the system-under-test response time. To compensate for this, the executor starts a varied number of VUs to meet the configured iteration rate. For explanations of how allocation works, read Arrival-rate VU allocation.

Note
Iteration starts are spaced fractionally. Iterations do not start at exactly the same time. At a rate of 10 with a timeUnit of 1s, each iteration starts about every tenth of a second (that is, each 100ms).

Options

Besides the common configuration options, this executor has the following options:

Option	Type	Description	Default
duration^(required)	string	Total scenario duration (excluding `gracefulStop`).	-
rate^(required)	integer	Number of iterations to start during each `timeUnit` period.	-
preAllocatedVUs^(required)	integer	Number of VUs to pre-allocate before test start to preserve runtime resources.	-
timeUnit	string	Period of time to apply the `rate` value.	`"1s"`
maxVUs	integer	Maximum number of VUs to allow during the test run.	If unset, same as `preAllocatedVUs`

When to use

When you want iterations to remain constant, independent of the performance of the system under test. This approach is useful for a more accurate representation of RPS, for example.

Note
Don’t put sleep at the end of an iteration.

The arrival-rate executors already pace the iteration rate through the rate and timeUnit properties. So it’s unnecessary to use a sleep() function at the end of the VU code.

Example

This example schedules a constant rate of 30 iterations per second for 30 seconds. It pre-allocates 2 VUs, and allows k6 to dynamically schedule up to 50 VUs as needed.

import http from 'k6/http';

export const options = {
  discardResponseBodies: true,
  scenarios: {
    contacts: {
      executor: 'constant-arrival-rate',

      // How long the test lasts
      duration: '30s',

      // How many iterations per timeUnit
      rate: 30,

      // Start `rate` iterations per second
      timeUnit: '1s',

      // Pre-allocate 2 VUs before starting the test
      preAllocatedVUs: 2,

      // Spin up a maximum of 50 VUs to sustain the defined
      // constant arrival rate.
      maxVUs: 50,
    },
  },
};

export default function () {
  http.get('https://test.k6.io/contacts.php');
}

Observations

The following graph depicts the performance of the example script:

Based upon our test scenario inputs and results:

The desired rate of 30 iterations started every 1 second is achieved and maintained for the majority of the test.
The test scenario runs for the specified 30 second duration.
Having started with 2 VUs (as specified by the preAllocatedVUs option), k6 automatically adjusts the number of VUs to achieve the desired rate, up to the maxVUs. For this test, this ended up as 17 VUs.
The number of VUs to achieve the desired rate varies depending on how long each iteration takes to execute. For this test definition, if it would take exactly 1 second, then 30 VUs would be needed. However, as it takes less than 1 second, then less VUs are needed.

Using too low of a preAllocatedVUs setting will reduce the test duration at the desired rate, as resources need to continually be allocated to achieve the rate.

Ramping arrival rate

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

Ramping arrival rate

With the ramping-arrival-rate executor, k6 starts iterations at a variable rate. It is an open-model executor, meaning iterations start independently of system response (for details, read Open and Closed models).

This executor has stages that configure target number of iterations and the time k6 takes to reach or stay at this target. Unlike the ramping VUs executor, which configures VUs, this executor dynamically changes the number of iterations to start, and starts these iterations as long as the test has enough allocated VUs. To learn how allocation works, read Arrival-rate VU allocation.

Note
Iteration starts are spaced fractionally. Iterations do not start at exactly the same time. At a rate of 10 with a timeUnit of 1s, each iteration starts about every tenth of a second (that is, each 100ms).

Options

Besides the common configuration options, this executor has the following options:

Option	Type	Description	Default
stages^(required)	array	Array of objects that specify the target number of iterations to ramp up or down to.	`[]`
preAllocatedVUs^(required)	integer	Number of VUs to pre-allocate before test start to preserve runtime resources.	-
startRate	integer	Number of iterations to execute each `timeUnit` period at test start.	`0`
timeUnit	string	Period of time to apply the `startRate` to the `stages`’ `target` value. Its value is constant for the whole duration of the scenario, it is not possible to change it for a specific stage.	`"1s"`
maxVUs	integer	Maximum number of VUs to allow during the test run.	If unset, same as `preAllocatedVUs`

When to use

If you need start iterations independent of system-under-test performance, and want to ramp the number of iterations up or down during specific periods of time.

Note
Don’t put sleep at the end of an iteration. The arrival-rate executors already pace the iteration rate through the rate and timeUnit properties. It’s unnecessary to use a sleep() function at the end of the VU code.

Example

This is an example of a four-stage test.

It starts at the defined startRate, 300 iterations per minute over a one minute period. After one minute, the iteration rate ramps to 600 iterations started per minute over the next two minutes, and stays at this rate for four more minutes. In the last two minutes, it ramps down to a target of 60 iterations per minute.

import http from 'k6/http';

export const options = {
  discardResponseBodies: true,

  scenarios: {
    contacts: {
      executor: 'ramping-arrival-rate',

      // Start iterations per `timeUnit`
      startRate: 300,

      // Start `startRate` iterations per minute
      timeUnit: '1m',

      // Pre-allocate necessary VUs.
      preAllocatedVUs: 50,

      stages: [
        // Start 300 iterations per `timeUnit` for the first minute.
        { target: 300, duration: '1m' },

        // Linearly ramp-up to starting 600 iterations per `timeUnit` over the following two minutes.
        { target: 600, duration: '2m' },

        // Continue starting 600 iterations per `timeUnit` for the following four minutes.
        { target: 600, duration: '4m' },

        // Linearly ramp-down to starting 60 iterations per `timeUnit` over the last two minutes.
        { target: 60, duration: '2m' },
      ],
    },
  },
};

export default function () {
  http.get('https://test.k6.io/contacts.php');
}

Observations

The following graph depicts the performance of the example script:

Based upon our test scenario inputs and results:

The configuration defines 4 stages for a total test duration of 9 minutes.
Stage 1 maintains the startRate iteration rate at 300 iterations started per minute for 1 minute.
Stage 2 ramps up the iteration rate linearly from the stage 1 of 300 iterations started per minute, to the target of 600 iterations started per minute over a 2-minute duration.
Stage 3 maintains the stage 2 iteration rate at 600 iterations started per minute over a 4-minute duration.
Stage 4 ramps down the iteration rate linearly to the target rate of 60 iterations started per minute over the last two minutes duration.
Changes to the iteration rate are performed by k6, adjusting the number of VUs
The script waits for a period of time (defined by the gracefulStop option) for iterations to finish. It doesn’t start new iterations during the gracefulStop period.
Our example performed, 4020 iterations over the course of the test.

Get the stage index

import { getCurrentStageIndex } from 'https://jslib.k6.io/k6-utils/1.3.0/index.js';

export const options = {
  stages: [
    { target: 10, duration: '30s' },
    { target: 50, duration: '1m' },
    { target: 10, duration: '30s' },
  ],
};

export default function () {
  if (getCurrentStageIndex() === 1) {
    console.log('Running the second stage where the expected target is 50');
  }
}

Using this feature, it is possible to automatically tag using the current running stage. Check the Tagging stages section for more details.