skip to content

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

level: juniorimportance: should knowfreq 44%

answer

  1. the whole run is one unit interval
  2. percent, decimal, fraction, or colon pair
  3. no colon means it starts at zero
  4. sequence takes points, not segments

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.

solid answer

~40 s

The flag names a half-open slice `(from, to]` of the whole run, which k6 treats as the interval `(0, 1]`. You can write an endpoint as a percentage (`25%`), a decimal (`0.25`) or a fraction (`1/4`), and you can join two of them with a colon to give both ends — `1/4:2/4`, or even a mixed `0.2:2/3`. Without a colon the value is only the end, and the start is assumed to be zero, so `25%`, `0.25` and `1/4` all mean `0:1/4`: the first quarter of the test. Omitting the flag entirely means `0:1`. The companion `--execution-segment-sequence` uses the same number forms but takes ascending boundary points instead, as in `0,1/4,2/4,3/4,1`.

code

bash · 5 lines
bash
k6 run --execution-segment "25%" script.js
k6 run --execution-segment "0.25" script.js
k6 run --execution-segment "1/4" script.js
k6 run --execution-segment "0:1/4" script.js
k6 run --execution-segment "0.2:2/3" script.js

go deeper

for a junior

Recall that the run is one interval from 0 to 1, that percent, decimal and fraction are interchangeable, and that a colon is what turns one endpoint into a full slice.

for a middle

Explain why the colon-less shorthand anchors at zero, and why that makes it a scale-down switch for a single box rather than a way to hand out slices to several.

for a senior

In a fleet, insist on the explicit interval form on every instance so that the set of arguments reads as a partition and a missing or duplicated slice is visible at a glance.

for a principal

Decide whether generated launch arguments should always emit canonical fractions, so that a partition can be diffed and reviewed rather than reconstructed from a mixture of percentages and decimals.

## The interval behind the value k6 v2 represents a whole test run as the interval `(0, 1]`. Every value you can pass to `--execution-segment` (or to the `executionSegment` script option) is just a way of naming a half-open sub-interval `(from, to]` of that range, with `0 <= from < to <= 1`. k6 stores the endpoints as exact rational numbers rather than floats, so thirds and sevenths survive without drift — which is what lets three instances split a test into exact thirds instead of two 0.333s and a rounding error. The interval is half-open on purpose: the end of one slice is the start of the next, so adjacent segments meet at a boundary without either claiming it twice. ## The four accepted forms - **Percentage** — `25%`, `10%`. The number before the `%` is divided by 100. - **Decimal** — `0.25`, `0.2`. - **Fraction** — `1/4`, `2/3`, `7/20`. - **Interval** — any two of the above joined by a colon: `1/4:2/4`, `0.5:0.75`, `50%:75%`. The two halves need not use the same form, so `0.2:2/3` is legal and means `(0.2, 2/3]`. The k6 flag's own help text advertises exactly this: *limit execution to the specified segment, e.g. 10%, 1/3, 0.2:2/3*. ## What a bare value means **A value with no colon is the END of a segment that starts at zero.** So: | you write | k6 reads | what it runs | |---|---|---| | `25%` | `0:1/4` | the first quarter | | `0.25` | `0:1/4` | the first quarter | | `1/4` | `0:1/4` | the first quarter | | `1/4:2/4` | `1/4:2/4` | the second quarter | | *(omitted)* | `0:1` | the whole test | That is deliberate: a bare `--execution-segment 25%` is the shorthand for *run a quarter-scale version of this test on one box*, which is a handy smoke test. It is **not** a way to say "give me some unspecified quarter", and it is not a sampling probability — two instances both passed `25%` would run the same first quarter twice and leave the other three quarters unrun. ## The sequence's value form is different `--execution-segment-sequence` does **not** take segments. It takes the **boundary points** of the whole partition as a comma-separated ascending list, using the same percentage, decimal and fraction forms: - `0,1/4,2/4,3/4,1` means the four segments `(0,1/4]`, `(1/4,2/4]`, `(2/4,3/4]`, `(3/4,1]`. - `n` points always describe `n - 1` segments, and k6 requires **at least two** points — a one-point value is rejected with *at least 2 points are needed for an execution segment sequence*. - Each point must equal the end of the one before it, so the segments join with no gaps and no overlaps; a list that jumps or goes backwards is rejected by name, naming the offending position. ## Values k6 rejects, and why Parsing happens before anything runs, so a bad value stops the process at configuration time rather than mid-test. The three rules a value has to satisfy: 1. **It must parse as a percentage, decimal or fraction.** `20 percent`, `a quarter` and `0.2-2/3` all fail, because none of them is one of the three number forms with an optional colon. 2. **The start must be strictly less than the end.** `3/4:1/4` is refused, reporting that the segment start must be less than its end. 3. **Both ends must lie inside the unit interval.** `0:2` is refused because the end may not exceed 1, and a negative start is refused for the mirror-image reason. A sequence adds two rules of its own: at least two boundary points, and each point equal to the previous segment's end. `0,1/4,1/4,1` repeats a point and so describes an empty segment, which is rejected; a list that goes backwards is rejected the same way, naming the position that broke the chain. ## Reading the values back k6 prints a segment in canonical `from:to` rational form regardless of how you typed it, so a segment entered as `25%` echoes back as `0:1/4`, and a sequence echoes as its boundary points. That canonical form is what appears in the JSON that `k6 inspect` prints, which makes it an easy way to confirm that what you typed is what k6 parsed. ## Splitting four ways in practice For a four-instance run you want the explicit interval form on each box, not the bare form, and the same point list everywhere: - box 1: `--execution-segment "0:1/4"` - box 2: `--execution-segment "1/4:2/4"` - box 3: `--execution-segment "2/4:3/4"` - box 4: `--execution-segment "3/4:1"` with `--execution-segment-sequence "0,1/4,2/4,3/4,1"` on all four. Writing `25%` on box 1 would happen to be equivalent to `0:1/4`, but the symmetric interval form is what makes the set readable as a partition.

  • What happens if you pass --execution-segment '3/4:1/4' to k6?
    It is rejected. k6 requires `0 <= from < to <= 1`, so a start that is greater than or equal to the end fails to parse, reporting that the segment start must be less than its end. An end above 1 is refused the same way.
  • How many segments does the sequence value '0,1/3,2/3,1' describe?
    Three: `(0,1/3]`, `(1/3,2/3]` and `(2/3,1]`. The value is a list of boundary points, so `n` points always yield `n - 1` segments, and k6 requires at least two points before it will accept the value at all.

saying these in an interview costs you the question

  • Reads a bare 25% as a random or unspecified quarter
  • Reads a bare 25% as a per-iteration sampling probability
  • Passes segments to the sequence flag instead of points
  • Thinks only fractions are accepted, not percentages
  • Assumes both ends of an interval must use the same form