skip to content

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

level: middleimportance: nice to knowfreq 32%

answer

  1. a pre-flight check, nothing is requested
  2. two fields appended to the options JSON
  3. how long, and how many at peak
  4. the numbers are for your slice only
  5. no segment flag on this subcommand

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.

solid answer

~40 s

Plain `k6 inspect script.js` prints the options k6 parsed. With `--execution-requirements` it goes further: it consolidates the config, derives the `scenarios` from any shorthand keys, builds the execution tuple from `executionSegment` and `executionSegmentSequence`, and walks the full execution plan. The output is the same options JSON plus `totalDuration` — the offset of the plan's last step, graceful stops included — and `maxVUs`, the highest VU count the plan can need at once. Both are segment-local, so on a four-way split they describe one slice. `k6 inspect` registers only the runtime flags, not `--execution-segment`, so the segment has to arrive through the script's exported `options` or a JSON config file passed with `-c`.

code

bash · 2 lines
bash
k6 inspect --execution-requirements script.js
k6 inspect -c quarter-two.json --execution-requirements script.js

go deeper

for a junior

Know that k6 inspect prints what k6 made of your options, and that adding the execution-requirements flag also tells you how long the plan runs and how many VUs it peaks at.

for a middle

Explain that the flag makes k6 derive the scenarios and walk the whole plan, and that the two extra numbers are computed through the segment, so they describe one instance.

for a senior

Use it as the pre-flight step before starting a fleet: confirm each slice's peak VUs and plan length, and remember it validates configuration only, never the target system.

for a principal

Decide whether a fleet launcher should gate on these numbers automatically — refusing to start when a slice reports zero work or a peak beyond what one box can sustain — rather than leaving it to whoever runs the command.

## Two shapes of k6 inspect output `k6 inspect script.js` loads the script, runs its init context, and prints the resulting options object as indented JSON — essentially "what did k6 understand my `options` to be". It is a parse-and-config check, not a run. Adding **`--execution-requirements`** switches it to the extended shape. k6 then does more work before printing: 1. consolidates the configuration layers into one config; 2. **derives the `scenarios`** — the shorthand `vus`/`duration`/`iterations`/`stages` keys are expanded into the scenario they imply; 3. builds the execution tuple from `executionSegment` and `executionSegmentSequence`; 4. walks every scenario's execution requirements to produce the full step-by-step plan. ## The two extra fields The extended output is the ordinary options JSON plus exactly two keys: | field | what it is | |---|---| | `totalDuration` | the time offset of the last step of the execution plan — how long this instance's run is scheduled to take, including graceful stops and ramp-downs | | `maxVUs` | the highest number of VUs the plan can need at any single moment, counting both planned and unplanned VUs | Both are computed **through the execution tuple**, so on a segmented configuration they are that **segment's** numbers, not the whole test's. That is what makes the flag interesting on this topic: it is the cheapest way to see what one slice of a four-way split will actually try to do before anything is launched. ## Where inspect reads the segment from `k6 inspect` registers the runtime flags — `-e`, `--type`, `--compatibility-mode`, `--include-system-env-vars` and friends — but **not** the option flag set that carries `--execution-segment` and `--execution-segment-sequence`. Those live on `k6 run`, `k6 cloud run`, `k6 cloud upload` and `k6 archive` only. So for inspect the segment has to arrive by another route: - the exported `options` object in the script (`executionSegment`, `executionSegmentSequence`); or - a JSON config file passed with `-c` / `--config`, which is a root-level flag and therefore available on `inspect`. There is no environment-variable route: both fields are excluded from k6's environment binding, and the v2.2.x options reference prints `N/A` in their Env column. Passing `--execution-segment` to `k6 inspect` is an unknown-flag error, not a silent no-op. ## Why deriving the scenarios matters here The derivation step is easy to skip past, and it is the reason the extended output is worth reading. Most scripts never write a `scenarios` block: they set `vus` and `duration`, or `vus` and `iterations`, or a `stages` list. Those shorthands are not what k6 executes — k6 expands them into a scenario first, and only that derived form has an execution plan with steps, VU requirements and an end offset. `--execution-requirements` prints the options *after* that expansion, so it answers three questions the script alone does not: - **Which scenario did my shorthand actually become?** The derived `scenarios` block appears in the output. - **How long will this instance be busy?** `totalDuration` is the plan's end offset, not the `duration` you typed, so it includes the tail added by graceful stops and ramp-downs. - **How big does this box need to be?** `maxVUs` is the peak across every scenario at once, already scaled to the segment. ## Using it on a four-way split - **Sanity-check one slice.** Put the segment in the script or a config file, inspect it, and read `maxVUs` — that is the ceiling one box must be able to sustain. - **Check the arithmetic of the whole cut.** Inspect each of the four segments in turn; the four `maxVUs` should be consistent with the scripted total, and none should come back as zero. - **Confirm the plan's length.** `totalDuration` includes the tail that graceful stops and ramp-downs add, so it is the number to compare against any timeout wrapped around the process. k6's own operator troubleshooting guide leans on exactly this: it describes `k6 inspect --execution-requirements script.js` as a shortened version of what the initializer runs before a distributed test, and tells you that if that command errors the problem is in the script, not the fleet. ## What it deliberately does not do Inspect never executes the default function and never issues a request, so it cannot tell you anything about the target system, and it validates configuration only. A script that inspects cleanly can still fail at run time. It is a pre-flight check on the *plan*, which is precisely what you want before starting four processes at once.

  • Why can't you just pass --execution-segment to k6 inspect?
    The subcommand only registers k6's runtime flag set, which covers things like `-e` and `--compatibility-mode`. The option flag set holding `--execution-segment` is registered by `run`, `cloud run`, `cloud upload` and `archive`. Passing it to `inspect` is an unknown-flag error, so use the script's `options` or a `-c` config file.
  • What does maxVUs count that a scripted vus number does not?
    It is the peak of the derived plan, taken over every moment of the run and every scenario at once, and it includes VUs a scenario may need beyond the ones it pre-allocated. On a segmented configuration it is also already scaled down to that instance's slice.

saying these in an interview costs you the question

  • Thinks inspect executes the default function
  • Expects --execution-segment to work on inspect
  • Reads maxVUs as the whole test's peak, not the segment's
  • Assumes totalDuration excludes graceful stops
  • Treats a clean inspect as proof the run will pass