Skip to content

Elements

Vayu's collection run is at parity with a JMeter test plan the way JMeter delivers it: as elements a user attaches to a request or a folder - extract this field, assert that, wait here, loop these, record this - added and removed independently, inherited down the tree, and run by the engine at fixed phases of a step (issue #1512). This page is the kind catalogue and the shape both sides of the wire agree on; it is generated from, or checked against, the registry GET /elements/kinds serves.

Status: issue #1513 landed the storage, the registry and the catalogue. Issue #1514 lands the pipeline that runs a kind in the design send and the sequential collection run, and the phase-0 kinds below. elements is the only script source now - pre_request_script / post_request_script are gone, cut over by a one-shot migration (see db-schema.md); no transitional alias, per the owner's decision. Issue #1495 lands the pipeline on a scenario load run's producer/completion hooks (below); issue #1594 lands it on a single-request load run's own submission too, through requestElements - see that section. Issue #1499 lands the first kinds to run at a run's own boundary rather than at a step's - script.setup / script.teardown, dispatched at Phase::RunStart / Phase::RunEnd outside the step pipeline entirely, in both run modes a collection can run in.

Shape

An element is {"id", "kind", "enabled", "name"?, "config"} in an ordered array, stored as the elements column on requests and collections:

{
  "id": "el_3f2b1c9a",
  "kind": "assert.status",
  "enabled": true,
  "name": "optional label",
  "config": { "in": [200, 201] }
}

id and kind are required; kind must be one GET /elements/kinds lists, and config must validate against that kind's JSON Schema - both checked by vayu::core::Registry::validate (engine/include/vayu/core/elements.hpp), which every write route runs before storing and POST /execute runs on its inline list before sending (400 naming the index, the kind and the field on a violation; /execute judges a collection-origin entry as a collection's own, see its elements). A rule the schema cannot express (a JSONPath that parses, a pattern RE2 compiles, an assertion having something to compare against) is the kind's optional validate_config hook, run after the schema accepts the config and worded the same way. A setting the kind does not declare is refused with the keys it does ('expected' is not a setting this element has. Settings: in, range, #2774), listed in the schema's key order (alphabetical) from the object the key sits in, so a nested object names its own; a schema node the message cannot resolve (a $ref) keeps the bare sentence. A request disables an element it would otherwise inherit from an ancestor collection with an inherit.disable entry naming the ancestor's id in its own list, rather than by deleting it.

Phases

A kind's registration names which of a step's seven points it runs at - run.start, iteration.start, step.before (after compose, before the residual-token pass), step.after (response in hand), step.between, iteration.end, run.end. Phase is derived from the kind, never stored on the element instance itself.

The registry, and how a kind is added

Registry::instance() (engine/src/core/elements/registry.cpp) holds the one, explicit list a kind name maps to code - the extensibility contract's rule: adding a capability is one new file under engine/src/core/elements/ plus one line in the registry's own call list, with nothing else in the engine, the app or MCP touched to make the kind exist and validate. GET /elements/kinds serves the same list; the app and MCP render a kind's editor from its schema, with a bespoke form only where one is worth writing by hand.

A kind that writes a variable scope sets ElementKind::writes_variables (every script.* and extract.* kind today). A collection run's plan reads it through the registry: when any step carries such a kind at a phase before some send, every step is composed with its {{names}} left for the send, so a value an earlier step writes reaches a later one (#2521, see Scenario runs). A new kind that writes a variable sets the flag or a plan resolves the value it writes too early.

Schema annotations

Every property in a kind's configSchema carries two standard JSON Schema keywords (issue

1607) - title (a short label) and description (one plain sentence) - so a generated form

renders words instead of the raw property key. Both are annotation keywords Registry::validate's valijson pass never consults; adding them changes nothing about what a config validates against.

Two vendor keywords, both optional: x-vayu-group: "advanced" folds a property under a disclosure instead of the form's main rows (timer.pacing.perUser, extract.json.matchNo); x-vayu-unit renders a numeric suffix beside a property's value and is only ever "ms", "%" or "B" - timer.pacing.everyMs and assert.duration.maxMs carry "ms", control.throughput.percent carries "%", assert.size.bytes carries "B". A new kind's schema ships title and description on every property from the day it registers; ElementsRegistryTest.EveryPropertyOfEveryKindCarriesATitleAndDescription (engine/tests/elements_registry_test.cpp) fails the build on one that does not.

An enum or boolean property whose absence the engine reads as a value also carries the standard default keyword (issue #3045; a numeric or free-text fallback such as matchNo or template does not yet): assert.size.op is lte, every extract.* scope is collection, timer.pacing.perUser and control.throughput.perUser are true, timer.throughput.perUser is false, and a boolean flag that is simply off (negate, an extractor's required, a script's inline, control.transaction's includeTimers) says false. The value is not retyped in the schema: it is a named constant in engine/include/vayu/core/element_defaults.hpp that the kind reads (config.value (key, DEFAULT)) and the schema serves, so what a form shows for an unset key is what the engine runs. An absent key means the default, and a client renders it that way without ever writing the key: the stored config is exactly what the user set. A property with no default has no value of its own for its absence - a required one cannot be absent, and assert.jsonpath.exists, control.throughput's percent / everyN and assert.status's in / range mean "not asserting that" or "no budget" when left out. Note default is also a property name in the extract.* schemas (the fallback value written on a miss); the annotation sits one level deeper, in the property's own schema, so the two never meet. ElementsRegistryTest.TheCatalogueDeclaresTheDefaultEachKindRuns pins the values, EveryPropertyOfEveryKindCarriesATitleAndDescription holds each default to its property's type and enum, and element_kinds_test.cpp runs each kind with the key absent.

Kinds

inherit.disable has no compile: it is consumed at compose time (compose_elements), never constructed into a running Element. Every other kind below has one, registered in engine/src/core/elements/registry.cpp. The test binary also registers a test.echo kind, proving the registration path itself - never in a production build. The table below is the single reference for every kind that exists once the rest of the epic lands, generated from or checked against the registry so a kind added on one side and forgotten on another fails a test rather than shipping silently mismatched.

Kind Category Phases Runs since
inherit.disable inherit (consumed at compose time, not a phase) #1513
extract.json extract step.after #1514
extract.regex extract step.after #1514
extract.header extract step.after #1514
extract.boundary extract step.after #1518
assert.status assert step.after #1514
assert.jsonpath assert step.after #1514
assert.contains assert step.after #1514
assert.duration assert step.after #1514
assert.size assert step.after #1514
timer.think timer step.between #1514 (fixed/uniform), #1498 (gaussian)
timer.pacing timer step.before #1498
timer.throughput timer step.before #1571
script.pre script step.before #1513 (validate-only), #1514 (runs)
script.post script step.after #1513 (validate-only), #1514 (runs)
script.setup script run.start #1499
script.teardown script run.end #1499
control.if controller step.before #1515
control.once controller step.before #1515
control.switch controller step.before #1515
control.throughput controller step.before #1515
control.loop controller step.between #1515
control.transaction transaction step.after #1515
metric.record metric step.after #1500

extract.json, assert.jsonpath and metric.record's jsonpath source share one JSONPath subset: $.a.b (any member name up to the next . or [, so $.data.user-id works), $['a.b'] or $["a.b"] for a name that holds a ., [ or ] (the name runs to the next matching quote and has no escape for it; an empty name or an unterminated quote is refused), [n] (negative counts from the end), [*] and ..name. A path outside it, a filter ([?...]) included, is refused at validate through the one parser, not a pattern per kind. [*] over an object and ..name return their matches in the body's own member order (issue #2459), so which one matchNo: 1 picks is the member the server wrote first; before #2459 they came back sorted by key. An object match written to a variable, or quoted in a failure message, keeps that order too, while assert.jsonpath's expected and a metric.record condition's eq / ne still compare an object member by member, in any order. A key the body repeats keeps the position of its first occurrence and the value of its last, so $.b on {"b": 1, "a": 3, "b": 2} is 2 and $[*] is 2, 3. extract.regex compiles its pattern once, when the element is compiled (once per run plan, or once per design send), and writes a $1$-style template of the match's groups for every non-overlapping match, leftmost first ($N$ past the pattern's last group writes nothing). extract.boundary (issue #1518, JMeter's Boundary Extractor) takes everything between the first occurrence of leftBoundary and the next occurrence of rightBoundary on the response body - no field selector, unlike extract.regex's four, because JMeter's own Boundary Extractor has none either. All four extractors share variable, scope (env | collection | globals), default and required. A variable no {{name}} could read back is refused when it is written (#3055): one containing { or }, one starting or ending in whitespace ({{ name }} trims the name it reads), one inside the reserved data. namespace (data.id addresses a data-set column, never a variable) and the two identity names $vu and $iteration. A name with an inner space (1 bad) is fine: the token grammar is any run of non-brace characters, trimmed. extract.json, extract.regex and extract.boundary also share the JMeter matchNo convention: 1-based picks a match, 0 picks one at random, -1 writes every match as <variable>_1 .. <variable>_N plus a <variable>_matchNr count, numbered in the order the matches were found (document order for extract.json, leftmost first for the two text extractors). extract.header has no matchNo: it reads the header's one value, and a header the response repeats is already folded into one comma-joined value by the transport, so two Set-Cookie lines extract as a=1, b=2 with no way to pick one. A miss writes default when the config gives one. Without one it unsets the variable in its scope (#3053), so a later {{name}} stays unresolved (and is counted as unresolved on a load run) rather than sending what an earlier iteration or a stored row held: the name is removed from the stored environment, collection or globals row too when the run persists, and an ancestor collection's value of the same name answers again, because an extractor writes the leaf collection only. With matchNo: -1 a miss also unsets <variable>_matchNr and every <variable>_<k>, whatever the default (it names <variable> alone), and a hit unsets the numbered names past its own count, so a shorter list never inherits a longer one's tail. A miss with no default reports "missing", and only when required: true also fails the step - through the same tests list a pm.test assertion writes to, which is why the SSE frame's tests tally and describe_failed_tests count a declarative assertion exactly as they count a scripted one. Every miss is counted per step as extractorMisses (#3053, is_extractor_miss), required or not: an extract.* outcome of missing, plus an optional extract.json's skipped over a body it could not read, because that unsets the variable too. A miss a default answered reports ok and is not counted, nor is a disabled extractor or a metric.record reporting missing. A collection run writes the count on the step's stored trace and its step frame, a load run on scenario.steps[i]; both omit the key at 0. A passing step's stored row can be dropped past the step-store cap, so the stored count covers the rows kept; the frame carries every step. A step whose request failed in transport (a refused port, a reset, a timeout) runs its extractors against the status-0 response on both run kinds, so it unsets and counts like any other miss (#3089). A single-request load run's summary.elements has no such count.

Every pattern a user writes - extract.regex's pattern, assert.jsonpath's regex, assert.contains's text in matches mode and control.if's matches /re/ - is compiled once by compile_user_regex (core/elements/user_regex.hpp, issue #1874) and run by RE2, never std::regex. A match is a search (the pattern may match anywhere in the text) and takes time linear in the text, so a greedy group over a multi-megabyte body cannot exhaust the stack or stall the run. The dialect is RE2's Perl-like one: no backreferences (\1) and no lookaround ((?=, (?!, (?<=, (?<!); inline flags such as (?i) (case-insensitive), (?s) (. matches a newline) and (?m) (^/$ at line breaks) are available. Text is matched as bytes, as it was before RE2: a body need not be UTF-8, a UTF-8 literal in the pattern matches the same bytes in the text, and . matches one byte rather than one character. A pattern RE2 refuses is refused when it is written (#3043): 'pattern' is not a valid regular expression - <reason> for extract.regex, 'regex' for assert.jsonpath (checked whenever it is written, even beside an expected that would win when it runs) and 'text' for assert.contains in matches mode: a 400 from every write route and from POST /execute, and an importer drops what holds it and counts the drop (elements_invalid for an x-vayu-elements array; a JMeter plan's Java pattern with lookaround or a backreference is tallied <kind>_unmappable). A pattern is never template-resolved, so a {{name}} in one is judged as the text RE2 reads (a{{n}} compiles: a { that opens no repetition is a literal). One stored before that check still reaches a run, where it is the element's "error" outcome, invalid regular expression: <reason>, and for an assert.* also a failed assertion (see the step trace); control.if instead treats it as a false condition and skips, with the same reason in the message. After an empty match the search resumes one byte later, so -1 over a pattern that can match nothing still ends.

assert.status takes a non-empty in list or a range; assert.jsonpath takes a path with one of expected, regex (searched in the first match's text) or exists, plus negate (a body that cannot be read fails it either way, see below). exists is a boolean: true passes when the path has at least one match and false when it has none, and negate flips whichever it states, so {"exists": false, "negate": true} means the path must be there (#3049). exists is refused beside expected or regex, since it asserts presence and they assert the value; a negated expected or regex failure reads "to not equal" / "to not match". expected (and a metric.record condition's value) is compared as JSON, so the number 7 and the string "7" are different values; the app's field for either reads what is typed as JSON (7, true, null, {"a":1}), stores the text as a string when it is not JSON, and takes a quoted value ("7") to force a string (#3046). assert.contains compares a field (body | headers | url | status) against text in contains | equals | matches (an RE2 search, above) mode. An empty text is refused in contains mode (the default), which finds it in every response so the verdict never depends on one (#3055); equals against "" and matches with an empty pattern stay valid; assert.duration takes maxMs; assert.size compares the body's byte length against bytes with an op. timer.think takes ms, minMs/maxMs for a uniform random wait, or gaussian: {meanMs, deviationMs} (both required, issue #1498) for a normally-distributed one, drawn from std::normal_distribution and clamped to zero (a draw below it would be a negative wait, which means nothing) then rounded to the nearest millisecond. A config must name a wait (#3055): ms, or both minMs and maxMs, or gaussian; an empty config, or one bound alone, is a 400. gaussian is checked first, then minMs/maxMs, then ms, so the three are mutually exclusive in practice even though validation does not refuse a combination. It runs in step.between, after this step's own outcome is decided and before the next step begins, so the wait never counts against either step's latency, and it polls the run's stop signal every 50ms so a Stop mid-wait lands promptly rather than at the end of a multi-second think. A run's elements.seed (below) makes the random draw reproducible. It holds back the next request on a sequential collection run, a scenario load run and every closed-loop single-request mode. A constant_rps run sends on a schedule instead, so it skips the timer, tallies it skipped and reports a think_timer_skipped_open_loop warning (#3541).

timer.pacing (issue #1498) holds a request, a folder or the whole collection to a steady start-to-start cadence across iterations - everyMs (required) between one pass's entry into that scope and the next, whatever the node's own duration was - and runs in step.before, not step.between, because the wait belongs to the next pass and must land before that entry step is sent. The same element is inherited into every request under its scope, so scenario_plan.cpp's mark_scope_entries stamps config._scopeEntry on only the first occurrence of that element's id in the iteration's step order; every later occurrence is a no-op, reported skipped. perUser (default true) gives each virtual user its own cadence; perUser: false (one cadence shared by every VU, JMeter's "All threads" pacing) works on the sequential run, where a single VU makes the two indistinguishable, and, since issue #1570, on a scenario load run too: SharedPacingClocks (elements.hpp) holds one atomic deadline per shared-pacing element id, advanced by a compare-exchange retry rather than a mutex, so every VU's entry into the scope claims the next slot of the same clock without blocking the producer thread for a lock.

timer.throughput (issue #1571) is the rate-based sibling of timer.pacing: it holds a request, a folder or the whole collection to a target rate - targetPerMinute (required, exclusive minimum 0) "N per minute" - rather than to a fixed gap between passes, and shares timer.pacing's tracks_scope_occurrence inheritance rule (config._scopeEntry, step.before phase and everything else pacing_math.hpp factors out for both kinds). perUser defaults the opposite way from timer.pacing: false, because a throughput target is a property of the system under test rather than of one user's journey - "50 checkouts per minute across all users" is the case this kind exists for. perUser: true divides the rate into a per-user interval (60000 / targetPerMinute, rounded to whole milliseconds and floored at 1ms) and runs the identical per-VU pacing arithmetic timer.pacing uses, so N users produce N times the rate. perUser: false (the default) shares one token-bucket budget across every virtual user of a scenario load run instead, through SharedThroughputBudgets (elements.hpp), carrying the fractional remainder between claims so the rate holds exactly over a long run, and banking at most one slot during an idle stretch rather than letting a run catch up in a burst. Unlike SharedPacingClocks, this budget is mutex-guarded rather than lock-free: its state is a fractional balance beside a timestamp, which no single compare-exchange can swap as a unit. Under a sequential (non-load) run there is only one implicit user, so perUser: true and perUser: false behave identically, same as timer.pacing.

The JSON-reading kinds (extract.json, assert.jsonpath) share one parse of the response body per step, through ElementContext's lazily filled slot, which keeps every object's members in the order the body wrote them (nlohmann::ordered_json, issue #2459) and costs time linear in the body however wide its objects are - a body over the maxElementBodyBytes config entry (default 1 MiB, restart-free) is not parsed, and so is a body that nests deeper than 100 levels (the kinds that read the tree recurse over it, and a hostile server chooses its shape). A body that cannot be read, whether it is not JSON, empty, too deep or too big, is not a pass: the reason is response body is not JSON, nests too deeply, or exceeds maxElementBodyBytes, and assert.jsonpath fails with it, whatever negate says (a body nothing can be read from satisfies neither "exists" nor "does not exist"), and so does an extract.json with required: true, which reports missing and fails the step like any other required miss, even when it has a default (that stands in for a path that did not match, not for a body that was never read). A load run counts both as failed assertions (the per-step tally still files the extractor's missing under skipped, below) and keeps no message per failure. An extract.json without required reports skipped with the same reason and writes nothing; required or not, it unsets what an earlier response left, as a miss does. metric.record's jsonpath source reads the same shared parse, so it reports missing there. The text-reading kinds (extract.regex, assert.contains, extract.boundary) are not bounded by it: they read the body in place, and RE2's linear-time search is what keeps a large one safe.

metric.record (issue #1500) reads a value off the response and records it as a custom trend (a distribution, reported as count/p50/p95/p99/max), counter (a running total value beside a count of how many times it was recorded, #1937) or rate (share of occurrences a condition matched, as a percentage). A counter only grows: a source that reads a negative or non-finite number reports error (the message names the source) and records nothing, where a trend records the same value. A trend or counter's source is one of {jsonpath}, {header}, {latency}, {status} or {size}; a rate's is {condition: {field, operator, value}} - a small, self-contained comparison rather than the full control.if grammar #1515 defines, which is not yet part of this registry and would be a needless dependency for what a rate condition actually needs. metric.record writes through ElementContext::record_metric, a callback bound only when a run's MetricsCollector is reachable (the sequential run, a scenario load run, design mode's script.pre/script.post); a bare design send has none, and the element reports skipped there rather than recording nowhere silently. pm.metrics.trend/.counter/.rate (docs/engine/scripting.md) write through the same callback from a script, so both surfaces share one collector-side implementation (MetricsCollector::record_custom_metric). Every run is capped at constants::metrics_collector::MAX_CUSTOM_METRIC_NAMES (32) distinct names, refused at Registry::validate time for a declared metric.record - see api-reference.md's customMetrics and thresholds sections for how a recorded value reaches the report and a custom.<name>.<stat> budget.

script.pre / script.post's apply never touches ScriptEngine itself: it calls back into ElementContext::run_pre_script / run_post_script, which the caller (execute_exchange, and the streaming send's own inline pipeline calls) binds to the exact execute_script call design mode has always made. The element's own outcome is whether the script ran without throwing; the script's own pm.test assertions travel inside the step's vayu::ScriptResult, folded beside every other level's (see The step trace).

A blank script.pre / .post / .setup / .teardown (its own script empty or whitespace-only, is_blank_script_element) is inert everywhere but storage (issue #1609): POST /compose does not emit it, compile_elements compiles it to no runnable behaviour the same way an unknown kind does, so ElementPipeline::run reports no outcome for it at all - not even skipped - and scenario_plan.cpp's step_has_script and step_has_deferred_script (the pre-request-script-under-load warning, a step's preRequestScript breakdown field) do not count it as carrying one. The stored row is untouched, so it still lists and edits in its own request's or collection's Elements tab.

script.setup / script.teardown are collection_only - refused (a 400 naming the index and kind) on a request's own elements, both at write time and in GET /elements/kinds' collectionOnly flag, because a once-per-run element attached to one request in the tree has no answer to "once per run, or once per request that happens to carry it". Their apply follows the same callback shape as script.pre / script.post, through the new ElementContext::run_setup_script / run_teardown_script pair, dispatched against Phase::RunStart / Phase::RunEnd directly, outside the step pipeline entirely (never a step's inherited copy). Which collections' elements a collection run dispatches is its lifecycle set (#3456), resolved once at run start by resolve_lifecycle_collections (scenario_plan.cpp): the ancestor chain root first (collection_chain, ending at the run collection), then, on a recursive run, every live folder beneath it depth-first in sidebar order (each parent's sub-folders in get_collections order, sibling_order.hpp's rule among folders), a visited set ending a parent_id cycle. A collection declaring neither kind is left out, and each kept element is compiled with collection_element_origin's stamp, the one compose_elements gives a step's inherited elements, so a lifecycle row's origin names its collection. Both run modes dispatch it through the same run_scenario_setup / run_scenario_teardown (scenario_runner.cpp): each collection's setups run with RunVariableScopes bound to that collection, the pass stops after the first collection whose setup refuses, and teardown walks the same held list in reverse. A load run resolves the set once in execute_load_test and holds it on RunContext::lifecycle for teardown; its scopes (scenario_load_scopes, every lifecycle and step collection's chain) are what LoadScopeBases binds each step's base from after setup, and what ScenarioLoadState::lifecycle_scopes keeps for teardown. A single-request load run has no collection row to compile that array from - it compiles POST /runs's own top-level lifecycleElements array instead (issue #1573), the same two kinds only, checked the same ElementOwner::Collection way; validate_lifecycle_elements_run_override refuses it outright beside a scenario block, whose collection already has a real elements column for this. run.start runs before the sequential run's iteration loop, and before execute_load_test captures the load run's own test_start - so a setup script's own time is never folded into either mode's duration figures, and a load run's live elapsedSeconds reads 0 until setup ends (issue #2395) - and writes through the same ScriptVariableScopes (scopes / scope_bases) every other script of the run shares, so its writes are visible from the very first step or submission (a scenario load run's folder bases are built from what it left, #3248). A throwing setup fails the run - Failed, nothing sent - before either mode's strategy starts, and the failed run's stored summary still carries lifecycle.setup (the sequential runner's catch, the load path's failed_run_summary_inputs, #3455); a throwing teardown is recorded under the report's lifecycle.teardown and never changes the run's terminal status, since ElementPipeline::run already turns a throw into that element's own "error" outcome rather than propagating one. Either kind reads its script's result as script.post does (record_script_outcome): a throw is "error", a script that only failed pm.tests is "failed" with the first failing test as its message, and its console lines and tests are kept on the outcome and serialised by build_lifecycle_node (not by ElementOutcome::to_json) as the row's console and messages lists, the shape and cap of an inline element's (#3455). A design (sequential) run writes its variable scopes back after teardown, so a teardown's pm.environment.set / pm.globals.set is saved with the steps' (#3249); a load run persists none. Teardown's script sees pm.info.run (requestsSent, errorRate - on a load run the report's, by the one error definition - assertionsPassed, assertionsFailed) - the one context that can report a run summary, because it is the one that runs after there is one. Neither kind gets a per-element allowRequests toggle: pm.sendRequest inside either script is gated by the run's own allowScriptRequests (ScriptConfig::allow_send_request, baked into the ScriptEngine instance every script of the run already shares) and capped at the same 10 calls per script every other script gets - a second, per-element gate would be dead configuration next to a run-wide one that already decides the question. What such a fetch sends under is the run's too, resolved once before setup runs and applied as one vayu::runtime::ScriptSendInputs (issue

2841): the run's timeout, else defaultTimeout, when the call names no timeout of its own; the

run's response byte bound, maxDesignResponseBodyBytes on a sequential collection run (a design-mode path) and maxResponseBodyBytes on a load run; and the transport policy and default headers the run's own transfers carry.

Controllers

JMeter's logic controllers, as element kinds rather than a nested sub-flow (issue #1515): control.if skips this step (or, inherited onto a folder, every member) when a condition against a resolved {{variable}} is false - {{v}} == x, !=, matches /re/ (an RE2 search, compiled once with the element; see the pattern paragraph above), or {{v}} exists, refused at validate outside that grammar. control.once runs on this user's first iteration only. control.throughput runs a share of occurrences by percent (an exact integer-carry accumulator, not a random draw) or everyN, on the producer's own counter - no lock, no body parse. Exactly one of the two is required (#3055): everyN is read first, so a config naming both would have percent ignored, and one naming neither would never skip. perUser (default true) keeps that counter per virtual user; perUser: false (issue #1569, JMeter's "All threads" throughput mode) shares one atomic counter pair across every VU of a scenario load run instead, allocated up front from a plan scan (SharedThroughputCounters, ElementKind::supports_shared_state read through the registry rather than a kind == comparison) - the sequential run's single implicit user already makes its own counter the "shared" instance, so perUser changes nothing there. All three write the same ScriptControl::Skip decision pm.execution.skipRequest() always has, so a skip is one mechanism end to end: execute_exchange's pre-send check, decide_next_step, and classify_step's StepOutcome::Skipped all read it exactly as they read a script's.

control.switch (variable, cases, default?) routes to a named member by a resolved variable's value, through the same ScriptControl::Next / resolve_next_step a script's own setNextRequest uses - so a switch's dispatch is an ordinary jump to every reader of the step list, not a second flow-control channel. A value that matches no cases entry and has no default does not end the folder: this occurrence proceeds unrouted, as an ordinary "ok" outcome with no jump at all, falling through to whatever the plan's own order would have sent next. The element carries no folder boundary of its own to end at - only a needs_span kind does, and control.switch is not one - so there is nothing here to decide where "the folder" ends.

control.loop (count) and control.transaction (name, includeTimers?) both sit on a folder and are inherited into every member beneath it, compiling once per member - so each member's own instance has to recognise its folder's first or last position independently rather than being told it. compute_element_spans (scenario_plan.cpp) answers that once per run, from a single pass over the resolved plan: a scope-spanning kind's id maps to the {first, last} position it occupies, read through the registry's needs_span flag. control.loop fires only at its folder's last member, on step.between; while its own per-iteration pass count (kept in ElementContext::controller_state, keyed by the element id and the iteration) is under count, it sets ScriptControl::Next back to the folder's first member - an ordinary loop-back, resolved the same way control.switch's jump is. control.transaction sums every member's own response latency into a per-iteration accumulator (same keying) at microsecond precision, each member rounded to the nearest microsecond (#2387; whole milliseconds per member reported three 0.9 ms members as 0 ms). The element only accumulates; the close is the runners' (#3054). Once a step's outcome and the iteration's next position are known, both run modes call settle_transactions (core/elements), which closes the pass when the iteration leaves the folder: after the folder's last member however that member ended - sent, skipped by a controller, or failed before step.after (a row that would not bind, a load transfer with no response) - and after any member from which the iteration jumps outside the folder or ends (a control.switch target past it, a null jump, an errored step under stopOnError, an abandoned load iteration). A pass in which no member was attempted, every one skipped, records nothing; a pass a Stop or the end of a load run interrupts is not recorded either. A jump back inside the folder keeps the pass open, except from its last member: control.loop's repeat starts a new pass each time round. The close writes the sum onto that step's own control.transaction outcome (appended for a step that never reached step.after) as ElementOutcome::duration_us, with the transaction's name in message - the two fields the runner (scenario_runner.cpp / scenario_load.cpp) reads to record the value into TransactionHistograms, one HdrHistogram per declared name allocated up front from a plan scan, so recording it takes no lock either. Only the close carries duration_us, and no timer sets it, which is what tells a close from an accumulating pass. The close also sets waited_ms (waitedMs in the step trace's JSON) to the sum rounded to whole milliseconds; duration_us itself is not serialised. A pass is "failed", and counts in errors, when an attempted member is an error by the run report's own definition (transaction_member_errored): no response (a transport failure, or a request that could not be built), a status outside 2xx/3xx (vayu::is_success_status, so a 404 counts), or a failed assertion (an assert.* element or a pm.test). A script that threw is none of these. A design send has no pass to fold into: its one response is the whole transaction, judged on the response alone because its assertions may run after the element. includeTimers: true (issue #1569) also folds a between-member timer.* wait (whole milliseconds, added as microseconds) into the same running sum - the runner's own step.between dispatch does this fold generically (fold_between_wait_into_open_transactions, shared by both run modes, found through the registry's category field rather than a kind == comparison) - but only into an open pass, one a member has already run in, and never for a wait after the folder's last member, which is outside the transaction's span. The report gains scenario.transactions[] = { name, count, errors, latency: { min, p50, p90, p95, p99, max } }, omitted for a transaction the run never closed.

control.switch and control.loop under a scenario load run (issue #1569). A scenario load run's virtual users used to advance through the plan strictly forward (VirtualUser::step), with no jump the way a repeat or a dispatch needs. They now do: ScenarioLoadState::step_index (the load path's own ScenarioStepIndex, built once per run) resolves a control.switch target or a control.loop's folder-start name through the same resolve_next_step the sequential run's setNextRequest uses, and finish_step applies the result to the VU's own step, guarded against a cycle that never closes by VirtualUser::steps_this_iteration and the same maxStepsPerIteration config entry the sequential run reads. A step that errored has its jump dropped, and a jump the run cannot honour errors the step that set it, both as on the sequential run (#2974). Neither kind sets the registry's jumps_or_repeats flag any more, so POST /runs' own refusal (vayu::core::find_load_incompatible_controller, still there for a future kind that jumps in a way the load path cannot support yet) no longer applies to either.

The step trace

A design send's and a sequential run step's stored trace gains an elements array beside the existing scripts node - one entry per compiled element that ran at step.before or step.after (step.between too, for the sequential run), each { id, kind, name?, origin, required?, outcome, message?, waitedMs? }, name being the element's own label when it has one. outcome is one of ok | failed | missing | skipped | error; a disabled element is reported skipped without its apply ever running. An extractor's missing carries what found nothing as its message (no match for '$.token', no 'X-Request-Id' response header), required or not (#3051). required is present, as true, only for an element whose config.required is boolean true: on an extractor's missing it is what says the miss failed the step. An assert.* whose own config leaves it nothing to judge (no operand, a JSONPath or pattern that does not compile: all refused when written, so only a row stored before that check reaches this) reports error with the reason and also records a failed assertion under the same reason, so the step fails and the failure counts wherever assertions are counted: the step's tests, scenario.assertions and the population maxAssertionFailureRatePct judges. no response stays error alone, because a step without a response has already errored. A script.pre / script.post element reports error with the thrown message when its script threw (or timed out), failed with the first failed assertion as its message (Test failed - <name>: <message>, or N tests failed - <first name>: <first message>) when the script ran and only its pm.test assertions did not hold, and ok otherwise (#2663). The message is about that one script; the step's own verdict is read from the folded result below, unchanged. origin.scope (collection | folder | request, #2522) is the level the element was declared at; compile_elements reads it into CompiledElement::scope (falling back to origin.kind), and ElementPipeline::run sets ElementContext::element_scope from it before each apply. A sequential run step's trace also carries extractorMisses beside the array, the count of its extractor misses (Kinds), absent at 0; a design send's does not.

Every level's script.pre / script.post runs, and each folds its result into the step's pre_script_result / post_script_result rather than assigning over it (#2522): tests and console lines are appended in run order, each stamped with the element's scope; success is false once any level's is; the first level that threw is kept as error_message, with error_scope naming it; and control is replaced only by an instruction, so a level that asked for nothing does not cancel an earlier controller's skip. An assert.* or extract.* result is stamped with its element's scope too. POST /execute's live response body carries the same array under the same key - one object, two homes, on the scripts node's own precedent.

assert.* outcomes count, with the pm.test calls of inline scripts, in the exact assertion population the run's maxAssertionFailureRatePct threshold reads beside the sampled one (a deferred script's replay), judging the worse of the two rates (#2892); a failed budget flips the run's terminal status to Failed when the run also asks for thresholds.failRun: true (api-reference.md's thresholds section, #1497).

Load paths

A scenario load run's submit_one (the producer, one virtual user at a time) runs step.before before binding and submitting a request; its completion runs step.after once the response is in hand, before the virtual user (VU) is released back to the pool. A declarative kind (extract.*, assert.*, metric.record) always runs at both points, read off the kind's registered hotPath, never a kind == comparison (the extensibility contract's rule 1). A script kind (script.pre, script.post) runs there only when its own config.inline is true or the run's elements.scripts override forces it one way or the other; otherwise the step keeps its pre-#1495 behaviour, deferred to the post-run tests replay (which reads a copy of the scopes every script.setup left, #3460, and not a virtual user's own writes), which now skips a step whose script already ran inline (RunContext::script_element_runs_inline is the one place that decision is made, read by both sides). The app sets config.inline from the Run inline switch under a script.pre / script.post editor (the kind's schema declares it x-vayu-group: "advanced", so it sits in the card's Advanced disclosure, #3457); script.setup / script.teardown have no such property and their form renders none.

Per-VU isolation. A load run's VUs share one event loop, so what an element writes (extract.*'s target variable, an inline script.*'s pm.environment.set) cannot land in the run's shared scopes the way a design send's or the sequential run's does - two VUs writing the same name would be reading and overwriting each other's state. Each VirtualUser instead carries a small ScopeOverlay: a handful of names this VU has written. What it saves to the environment, collection or globals scope lives as long as the VU (#3044), so a control.once login's extracted token still answers every later iteration's {{token}}; only the run-local scope (pm.variables.set) is emptied at the iteration boundary, beside cookies. The run's shared scopes are flattened once at setup (flatten_variable_scopes); the residual-token pass (resolve_residual_tokens, see architecture.md) reads a copy of that flattened map with the VU's overlay merged on top - proportional to what the VU actually wrote, not to the run's whole variable set. An inline script needs the full, mutable scopes pm.environment.set writes through, so it runs against a materialized copy (base scopes plus the VU's prior overlay) and whatever comes out replaces the VU's overlay wholesale - equivalent to a diff, since the copy already started as "base plus every override this VU has made so far." An extractor's miss cannot erase a shared base value, so the overlay keeps a tombstone for it (#3053): that scope's base value of the name reads as absent for this VU alone - in the residual pass, a controller's template and a materialized copy - until the VU sets the name again. It lasts as long as the VU's saved writes, through the iteration boundary and an inline script's replace. A script's own pm.environment.unset, pm.collectionVariables.unset or pm.globals.unset (or clear) of a base name is kept the same way (#3088): the replace tombstones every base name of a scope the script's copy no longer holds. The shared scopes are one base per collection a step sits in (LoadScopeBases, #3248), so a step in a sub-folder of a recursive run reads that folder's chain, and the overlay keeps its collection writes per collection id: a folder's write answers the VU's later steps in that folder and below it, never a sibling folder's.

One ScriptEngine per thread, not a shared pool. Every load run's worker threads - the strategy thread and each event-loop worker - are spawned fresh for that run and joined before it retains, so vayu::http::routes::script_engine_for_this_thread constructs one lazily on first use and is never stale, never shared across runs, and never a caller-visible lock.

elements.includeScriptTime. A step's recorded latency is its transfer alone by default - an inline element runs after Client::send's own timing already stopped and before StepHistograms::record - so opting a script in does not, by itself, change what the latency figures measure. Setting the run's elements.includeScriptTime folds the pipeline's own elapsed time back in for anyone who wants the scripted cost in the figures. It moves the step's histogram and the run's together (#2792): the scenario executor decides the figure once per completion and hands it to StepHistograms and, as ResultAnnotations::script_ms, to the run's latency histogram, so the run's max is never below a step's. What stays on the transfer is the stored trace's totalMs (it stays consistent with the phase breakdown beside it), the per-phase histograms and the slow_threshold_ms decision.

Per-step tallies. scenario.steps[i].elements[] = { id, kind, name?, origin?, required?, passed, failed, missing, error, skipped, deferred } beside the existing tests node, one row per element that ran at least once this run - StepElementTallies, sized once from the plan's compiled elements so recording a count on the completion path is a lookup, never a lock or an allocation. An inline script.* row adds messages and console (#3127), what the script threw, failed and logged: script.pre / script.post copy them onto the outcome (ElementOutcome::messages, never serialised on a trace), and each list (DistinctMessageSample) keeps the first 10 distinct entries, each with how many times it was offered, and counts what it turned away. Its slots are written once and published through an atomic size, and each slot's count is an atomic beside it, so a repeat or a full list is a few lock-free compares and one relaxed increment; only keeping a new entry takes the list's mutex. The wire shape is in api-reference.md. Ids are unique within one level's list, not across the chain (a duplicated collection keeps its elements' ids), so a step's composed list can hold one id twice; each still gets its own row, counts and label, told apart by its origin kind, scope and id (ElementSlotIndex). A single-request run's summary.elements is RequestElementTallies, classifying by the same rule (ElementOutcomeCounts) and matching an outcome to its row the same way, so a requestElements id two levels share (#3101) is two rows there too. Each count is one outcome word (#3051): ok is passed, and failed, missing and error count under their own names, so a miss never reads as a skip nor an error as a failed check. The row names its element: name (its label) and origin (the level it was composed from) when it has them, and required: true for an extractor whose miss fails the step. deferred (issue #2144) is an un-inlined script.post left to the replay: the load path's skip_reason hook answers it with ElementSkip::deferred set, which the pipeline copies onto the outcome. skipped is every other skipped outcome, including the two that never run at all: a disabled element and an un-inlined script.pre (no pre-request replay exists), and an inline script.* the run's Stop cut short, its pm.sendRequest cancelled (#3371) or the script itself ended (#3460), which run_step_script keeps out of the step's result. An extractor's miss is a missing (or, for an optional extract.json that could not read the body, a skipped), and is counted again, per step, in scenario.steps[i].extractorMisses (above).

A controller's skip, under load too (issue #1515). control.if / control.once / control.throughput write the same ScriptControl::Skip a script's own skipRequest() would - before #1515 the load path had nothing to read that decision at all (pm.execution.* is refused there outright). submit_one now checks it right after step.before runs: a skip never reaches EventLoop::submit, the VU still advances exactly as a sent step would, and the run's steps_skipped counter (ScenarioLoadState) feeds the summary's skipped key, which every scenario load run reported as a hardcoded 0 before this. The same claim walks the VU on to its next step, up to one whole iteration, and a refill pass in which every claimed VU skipped a whole iteration waits one controller tick before the next (#3540, docs/engine/architecture.md, Closed-loop controller).

Timers, wired end to end (issue #1498). elements.timers ("asConfigured" (default) | "off" | {fixedMs: N} | {minMs, maxMs}) is validated on POST /runs, parsed into RunContext::timers_override (a vayu::core::TimersOverride), and applied through the one function every timer.* kind's apply calls, vayu::core::apply_timers_override (elements/pipeline.cpp) - "off" silences the wait entirely (waitedMs: 0, no sleep), fixedMs/{minMs,maxMs} replace a kind's own computed wait with the run-wide one, whatever that kind's own config says. This also fixed a pre-existing dead-code bug: RunContext::timers_disabled was parsed from "off" since #1495 but nothing read it, because timer.think's step.between phase was never dispatched on the load path at all. It is now: ScenarioLoadDriver::run_step_between (scenario_load.cpp) dispatches Phase::StepBetween on the step that just completed, non-blocking, and sums the outcomes' waited_ms into VirtualUser::ready_at_ms. elements.seed (a non-negative integer) seeds the run's own std::mt19937_64 (RunContext::rng); a scenario load run derives one independent generator per virtual user off it (vayu::core::derive_vu_rng) rather than sharing one across worker threads, so a seeded run's random waits are reproducible. "off" also reaches timer.pacing and timer.throughput under load (below), whose own scheduling seam runs before apply_timers_override's call site ever exists for that step.

Non-blocking waits: scheduled_ready_delay_ms. Element::scheduled_ready_delay_ms (issue

1498) is how a kind that needs to wait tells a scenario load run to hold its VU back without

blocking a worker thread: timer.think (whose wait already lands through step.between's own dispatch above) needs no override, but timer.pacing and timer.throughput do, since their phase (step.before) fires only once a VU has already been selected as ready - too late to defer non-blockingly. ScenarioLoadDriver::finish_step calls the override on the VU's upcoming step, right after deciding which step comes next and before the VU can be selected again, and applies the returned delay to VirtualUser::ready_at_ms, which already gated VU selection but, before #1498, had nothing writing to it. Per-node "last started" timestamps live in VirtualUser::pacing_state (one map per VU, so VUs pacing the same folder run independent cadences) for perUser: true and for the sequential run; a perUser: false element instead advances its own entry in ScenarioLoadState::shared_pacing (a SharedPacingClocks, issue #1570), one atomic per shared-pacing element id in the plan, so two VUs' concurrent completions claim distinct slots of the same clock rather than racing onto the same one. SharedScheduleState::timers_override (a const TimersOverride* alongside pacing and throughput, filled in from RunContext at the same call site) is finish_step's own copy of the override for this seam: both kinds call the same apply_timers_override every other timer.* kind's apply calls, through shared.timers_override and a shared.rng (issue #1620, the VU's own generator, so a Range draw stays reproducible with seed) - "off" returns std::nullopt before either kind touches its pacing state or shared clock at all, and "fixedMs" / {"minMs", "maxMs"} replace the element's own everyMs / targetPerMinute with the override's value before either branch advances anything from it (timer.throughput's shared token bucket converts the overridden interval into the equivalent rate per second). A run that silences or overrides timers no longer defers a scenario load run's pacing or throughput element by its own configured interval first and only reports that truthfully after the fact.

Step-level elements on the single-request load path, wired (issue #1594). A single-request POST /runs payload's own request now has an elements attachment point - requestElements, a distinct key from this endpoint's own run-level elements override (above) - compiled once at run start into RunContext::step_elements. load_strategy.cpp's submit_one_request runs Phase::StepBefore immediately before the transfer and handle_result runs Phase::StepAfter once the response is in, the same phases a design send uses; extract.* / assert.* always run there, and a script.pre / script.post element runs inline only when its own config.inline is true (the app's Run inline switch on the script's card, #3457) or the run's elements.scripts override forces it - RunContext::script_element_runs_inline deciding exactly as it does for a scenario step. An unmarked script.post defers to this run's own completion replay (RunContext::test_scripts, one entry per un-inlined element taken at compile time so the replay does not need to know elements exist, each replayed as its own script, #3125, against a copy of the scopes script.setup left and each sample's request as sent, #3460); an unmarked script.pre simply never runs, since there is no pre-request replay on this path to defer it to.

There is no persistent virtual-user object on this path to carry a ScopeOverlay across submissions the way a scenario's does, so each submission gets its own, built fresh from the run's flattened base scopes (RunContext::step_base_vars) and discarded once that submission settles - proportional to one request's writes, never shared with a concurrent submission. An inline script.pre's edits and any pm.environment.set it makes reach the residual-token pass (resolve_residual_tokens) run against that same overlay before the transfer, so a value one script writes resolves a {{token}} later in the same request. timer.think's wait costs no new thread: RunContext::reserve_think_wait / purge_expired_think_reservations hold a mutex-guarded multiset of release deadlines folded into RunContext::in_flight(), so the existing maintain_concurrency closed-loop poll throttles a reserved-but-not-yet-released submission the same way it already throttles an in-flight one - no new thread, no change to any load strategy's own polling loop. An open-loop (constant_rps) run reserves nothing: its step.between dispatch skips a timer.* kind through the pipeline's skip hook (RunContext::open_loop_timer_skip_reason, read through the registry's category), because its pacer's maxInFlight headroom reads the same in_flight() and would drop arrivals for slots no request holds (#3541). What issue #1573 wires for this run shape stays separate: lifecycleElements (previous paragraph) is a run's own boundary, not a step's. validate_request_elements_run_override refuses a control.* kind, timer.pacing and timer.throughput outright (a 400 naming the element's label and where it was declared, #3050; a disabled entry is not refused, the pipeline skips it) rather than accepting one that would silently no-op or misbehave - a lone request has no sequence for a jump, a per-VU controller state, or a shared pacing clock for apply to read, and admitting the kind without running it correctly would report "ok" for behaviour that never happened. The controller and pacing family stays a scenario-only concern; only extract.*, assert.*, timer.think and script.pre/script.post - the same phase-0 set #1514 gave the design send - are accepted here.

  • 1513 - this page's storage, registry and catalogue.

  • 1514 - the pipeline in the design send and the sequential run, the phase-0 behaviour kinds

    (extract.*, assert.*, timer.think, script.*), per-element outcomes in the step trace, and the script-to-elements cut-over (this page's Status callout).
  • 1495 - the pipeline on a scenario load run's producer/completion hooks (this page's Load

    paths section).
  • 1497 - the maxAssertionFailureRatePct run threshold and thresholds.failRun, over the

    combined assert.* element and pm.test tally (see api-reference.md's thresholds section).
  • 1564 - the same thresholds block, evaluated for a collection (sequential) run too, not

    only a load run.
  • 1498 - timer.think's gaussian option, the timer.pacing kind, a per-run seeded RNG

    (elements.seed) and the elements.timers override wired end to end (this page's Timers paragraphs and Load paths section). timer.pacing's perUser: false under load and timer.throughput were deliberately deferred to follow-up issues.
  • 1570 - timer.pacing's perUser: false under a scenario load run (this page's timer.pacing

    and Non-blocking waits paragraphs).
  • 1571 - the timer.throughput kind (this page's timer.throughput paragraph): a target-rate

    timer sharing timer.pacing's step.before inheritance machinery but defaulting perUser to false, backed under load by the new SharedThroughputBudgets primitive rather than SharedPacingClocks.
  • 1499 - script.setup / script.teardown, the run.start / run.end dispatch this page's

    Kinds section describes, in both collection-backed run modes. Deliberately did not wire a single-request load run's POST /runs to declare either kind - that shape has no collection to declare them on; the wire-shape gap it left is #1573.
  • 1573 - lifecycleElements, a single-request POST /runs payload's own ephemeral place to

    declare script.setup / script.teardown (this page's Kinds section and Load paths section). Left step-level elements (extract.*, assert.*, timer.*, script.pre/.post) unwired on the single-request load path - that gap is #1594's.
  • 1594 - requestElements, wiring step-level elements into the single-request load path (this

    page's Load paths section): the run pipeline's per-submission Phase::StepBefore / Phase::StepAfter dispatch, inline-vs-deferred script.* dispatch shared with the scenario path, a per-submission ScopeOverlay, and non-blocking timer.think backpressure via RunContext::reserve_think_wait. preRequestScript(s) / postRequestScript(s) / tests are refused on POST /runs now too, the same as every other route since #1514.
  • 1515 - the controller family (control.if, .once, .switch, .throughput, .loop,

    .transaction), the load path's own steps_skipped counter, and scenario.transactions[] (this page's Controllers section).
  • 1569 - the follow-up disclosed by #1515, landed: a scenario load run's own jump/repeat

    mechanism for control.switch / control.loop, control.throughput's shared perUser: false budget, and control.transaction's includeTimers.
  • 1500 - metric.record and the pm.metrics script binding: custom trends, counters and

    rates, reported beside the built-in phases and usable as a custom.<name>.<stat> threshold.
  • 1501 - load-time cookies that round out the kind table.

  • 1516 - the app's ElementList primitive and editor.

  • 1517 - MCP's elements fields and the vayu://elements/kinds resource.

  • 1518 - OpenAPI round-trip (x-vayu-elements), Postman import, and a JMeter .jmx importer.

  • 2459 - the JSONPath kinds read the body in its own member order (the shared subset's

    paragraph and the shared-parse paragraph).