What determines the timing of VU ramp‑down between stages in k6 load tests?

Answer to the exact question

k6 starts the VU ramp‑down immediately when the next stage begins. The target VU count for the new stage is applied linearly over the duration you specify. The only delay that can make the observed VU count lag behind the theoretical target is the time it takes a VU that is scheduled to be removed to finish its current iteration.

How the ramp works

• Ramp shape: linear gradient between the previous stage’s target and the next stage’s target.
• Start time: at the exact moment the stage boundary is reached, regardless of whether a VU is in the middle of an iteration.
• Termination of excess VUs: a VU that is slated for removal will be stopped only after it completes its current iteration. The ramp curve therefore can be slightly “stretched” by the length of a single iteration.
• Impact on VU‑minute usage: for a short high‑load stage followed by a low‑load stage, the total VU‑minutes will be a little higher than the perfect linear calculation because the VUs that are being removed may linger until their iteration ends.

Practical verification steps

1. Write a minimal script that logs the current __VU and the time stamp at the start of each iteration.

   export default function () {
     console.log(`VU ${__VU} start at ${Date.now()}`);
     sleep(1);
   }

2. Run k6 with two stages, e.g. 10 VUs for 10s, then 2 VUs for 10s.

   k6 run --vus 10 --duration 10s --stages '10,10s|2,10s' script.js

3. In the console, note when the VU count drops from 10 to 2. It should start at the 10‑second mark of the first stage.
4. Check the JSON summary (k6 run --summary-export out.json) and look at the vus metric over time. The graph should show a straight line from 10 to 2 during the second stage, with a slight horizontal lag if the iteration takes longer than the instant of removal.
5. If you want to quantify the lag, calculate the mean iteration time from the logs and compare it to the observed drop‑off.

Missing diagnostic detail

To refine the estimate of how much the VU‑minute count will be inflated, please provide the average duration of a VU iteration in your script. Knowing this will let you calculate the maximum extra VU‑minutes caused by the “finish‑iteration‑first” policy.