skip to content

Multi-Instance Splitting

3 roadmaps5 questions

Cutting one workload into segments so several k6 processes each run a slice, and facing what core k6 then refuses to do: nothing merges their metrics or judges their rules together.

on this pageshow

explore

questions

5

What do k6's --execution-segment and --execution-segment-sequence flags do, and why pass both?

level: middleimportance: must knowfreq 68%

answer

  1. one names your slice, one names the cut
  2. the run is one unit interval
  3. sequence is boundary points, shared by all
  4. missing sequence gets filled in per instance
  5. segment must appear in the sequence

basics

~20 s

In k6, --execution-segment names the slice of total work one process runs, and --execution-segment-sequence names the full partition every process shares. Pass both, or each instance invents its own partition and the slices stop lining up.

solid answer

~40 s

`--execution-segment` takes a half-open slice of the whole test — `0:1/4`, `1/4:2/4` and so on — and k6 scales that instance's VU counts, iteration counts and arrival rates down to it. `--execution-segment-sequence` takes the whole partition as boundary points, `0,1/4,2/4,3/4,1`, and every instance in the fleet must get the same one. k6 uses the sequence to compute a striped, non-overlapping index assignment per segment. Omit it and k6 fills the gaps around your segment itself, so instance two of four plans against a three-part partition nobody else sees and the pieces no longer add back up to one test. The segment must appear in the sequence or config validation rejects the run. Defaults are `0:1` and `0,1`.

code

bash · 4 lines
bash
k6 run --execution-segment "0:1/4"   --execution-segment-sequence "0,1/4,2/4,3/4,1" script.js
k6 run --execution-segment "1/4:2/4" --execution-segment-sequence "0,1/4,2/4,3/4,1" script.js
k6 run --execution-segment "2/4:3/4" --execution-segment-sequence "0,1/4,2/4,3/4,1" script.js
k6 run --execution-segment "3/4:1"   --execution-segment-sequence "0,1/4,2/4,3/4,1" script.js

go deeper

for a junior

Remember the pair: one flag says which slice this process runs, the other spells out the whole cut. Both go on every instance, and only the first flag differs between them.

for a middle

Be able to explain that k6 fills in a missing sequence per instance, and that the division is a striped index assignment computed from the whole partition rather than a simple proportion.

for a senior

Show how you would ship one script to four boxes and still vary the segment per box, given that no environment variable carries it, and how you would catch a segment that is absent from the sequence before launch.

for a principal

Weigh keeping the cut in the script's options, where it is versioned but pins the script to one instance, against keeping it on the command line, where the script stays generic but the launcher owns correctness.

## What each flag names k6 treats one whole test run as the interval `(0, 1]` — every VU, every iteration, every request the script asks for. In k6 v2 two flags cut that interval into pieces so that several k6 processes can each run one piece of the same plan. - **`--execution-segment`** (script option `executionSegment`) is the half-open slice **this one process** owns, written `from:to`. `0:1/4` is the first quarter, `1/4:2/4` the second. Its default is `0:1` — the whole test. - **`--execution-segment-sequence`** (script option `executionSegmentSequence`) is the **entire partition**, written as its boundary points: `0,1/4,2/4,3/4,1` describes the four consecutive segments `(0,1/4]`, `(1/4,2/4]`, `(2/4,3/4]` and `(3/4,1]`. Its default is `0,1`. | | `--execution-segment` | `--execution-segment-sequence` | |---|---|---| | answers | "which slice am I?" | "what does the whole cut look like?" | | value form | one interval, `1/4:2/4` | boundary points, `0,1/4,2/4,3/4,1` | | differs per instance | yes | no — identical on every instance | | default | `0:1` | `0,1` | | script option | `executionSegment` | `executionSegmentSequence` | From the pair k6 builds an internal execution tuple and uses it to scale everything countable in the derived plan: VU counts, iteration counts, arrival rates, and the striped iteration indices this instance is allowed to take. ## Why the sequence is not optional Passing `--execution-segment` on its own is legal, and that is exactly the trap. When the sequence is missing, k6 **manufactures** one by filling the gaps on either side of whatever segment you gave it. Hand one box `1/4:2/4` alone and it plans against a three-part partition; hand the next box `2/4:3/4` alone and it plans against a different three-part partition. Four boxes, four different pictures of the same test. That matters because the division is **striped**, not merely proportional. k6 computes, per segment, a repeating pattern of indices that belong to it — index 0 to the first segment, 1 to the second, and so on for four equal quarters — so that the four instances between them cover every index exactly once. The pattern is a function of the whole partition, so a different partition means a different pattern. k6's own executor tests show this directly: the identical segment `0:1/3` produces one schedule with no sequence and a visibly different one when `0,1/3,2/3,1` is supplied. ## Wiring one plan onto four instances 1. Decide the cut and write it once: `0,1/4,2/4,3/4,1`. 2. Give **every** instance that same `--execution-segment-sequence`. 3. Give each instance a **different** `--execution-segment` drawn from that sequence: `0:1/4`, `1/4:2/4`, `2/4:3/4`, `3/4:1`. 4. Start all four against the same script. ## Where the segment value can come from Three configuration channels can carry it, and one obvious-looking channel cannot: - the CLI flags, on `k6 run`, `k6 cloud run`, `k6 cloud upload` and `k6 archive`; - the exported `options` object in the script itself; - a JSON config file passed with `-c`/`--config`. There is **no `K6_EXECUTION_SEGMENT` environment variable**. Both fields are explicitly excluded from k6's environment-variable binding, and the v2.2.x options reference prints `N/A` in the Env column for both. With one shared script and one shared image, the per-instance channel is therefore the command line (or a per-instance config file) — which is how the k6 Operator does it: a `TestRun` with `parallelism: 4` starts four runner jobs and hands each one its own segment arguments. ## What k6 rejects - The segment you pass **must be one of the sequence's segments**. `1/3:2/3` against the sequence `0,1/4,2/4,3/4,1` fails config validation with *provided segment ... can't be found in sequence ...*. - A sequence needs **at least two boundary points**, and consecutive points must join with no gap and no overlap — `0,1/4,2/4,3/4,1` is valid, `0,1/4,1/2,1/4,1` is not. - A segment must satisfy `0 <= from < to <= 1`; `3/4:1/4` and `0:2` are both rejected. ## What the split does not buy you Segmentation divides the plan; it does not join the results. Core k6 has no primary process, so the four instances never talk to each other — each evaluates its own `thresholds` against its own quarter of the samples and writes its own end-of-test summary. That is the deliberate design the segment type documents: an instance needs to know only its own segment and the sequence to compute its share reproducibly, with nothing scheduling it from a master node.

  • Can each instance get its segment from an environment variable instead of a flag?
    No. `executionSegment` and `executionSegmentSequence` are deliberately excluded from k6's environment-variable binding, and the v2.2.x options reference lists their Env column as N/A. The value has to arrive through the CLI flag, the script's exported `options`, or a JSON config file passed with `-c`.
  • Which k6 subcommands accept the two segmentation flags?
    `k6 run`, `k6 cloud run`, `k6 cloud upload` and `k6 archive` all register the shared option flag set that contains them. `k6 inspect` does not, so when you inspect a script the segment can only come from the script's own `options` or a `-c` config file.
  • What if I pass only --execution-segment-sequence and no --execution-segment?
    The run is treated as having the default full segment `0:1`, and validation then looks for `0:1` inside the sequence you supplied. Against `0,1/4,2/4,3/4,1` it is not there, so the run fails config validation. A sequence is only meaningful alongside a segment drawn from it.

The segment is your seat number; the sequence is the seating chart. Everyone needs the same chart, or two people confidently sit down in the same seat.

saying these in an interview costs you the question

  • Claims the sequence flag is optional decoration
  • Thinks each instance can pick its own sequence
  • Writes the sequence as a list of segments, not boundary points
  • Expects k6 to detect overlapping segments across processes
  • Believes K6_EXECUTION_SEGMENT sets the segment
open as a page

After four k6 instances each run one execution segment, what does core k6 not do for you?

level: seniorimportance: must knowfreq 62%

basics

~10 s

Core k6 divides the plan but never rejoins the results. There is no primary process, each instance evaluates its thresholds against only its own samples, and each writes its own output stream and summary.

open as a page

Which value forms does k6's --execution-segment flag accept, and what does a bare 25% mean?

level: juniorimportance: should knowfreq 44%

basics

~20 s

k6's --execution-segment accepts a percentage, a decimal, a fraction, or two of those joined by a colon. A value with no colon is the end of a segment starting at zero, so 25% means the first quarter, 0:1/4.

open as a page

When a k6 test is split into four execution segments, how are VU and iteration counts divided?

level: middleimportance: should knowfreq 56%

basics

~20 s

k6 gives each execution segment a striped, non-overlapping set of indices from the whole partition and scales every count against it, so the per-instance shares always add back up to the scripted total. Durations are never scaled.

open as a page

What does k6 inspect --execution-requirements report, and where does it read the execution segment from?

level: middleimportance: nice to knowfreq 32%

basics

~20 s

It prints the script's consolidated options JSON plus two extra fields, totalDuration and maxVUs, computed for the configured execution segment. k6 inspect has no segment flag, so the segment must come from the script's options or a -c config file.

open as a page