Load runs

Any client flow can run as load: many UEs, started at a rate. A stepped load run goes further: it raises the rate step by step and finds the rate where the core stops keeping up (the knee).

Shape a single run

Shell

Flag	Default	What it does
`-rate`	0	starts per second, the first at t=0. `0` starts everything at once
`-duration`		the spawn window. With `-rate` and no `-repetitions`, the run makes rate × duration starts
`-repetitions`	1	the number of starts. `0` is unbounded
`-timeout`	30s	the deadline for the whole run, not per UE. It must exceed the spawn window plus the flow's own timeouts, or UEs still in flight count as timed out
`-ramp`, `-ramp-from`		climb linearly from `-ramp-from` to `-rate` over `-ramp`
`-max-inflight`		cap the UEs in progress. A start due at the cap waits
`-catchup`	`drop`	what to do with starts that fall behind: `drop` makes them only within 10 ms of schedule, otherwise counts them as missed; `burst` makes late starts back to back
`-hold`		UEs that reach the flow's `hold_state` stay there this long after the last start, then are released (needs a flow with `hold_state`)
`-cpus`		pin `rk` to these CPUs (`taskset` syntax) and size its threads to them; Linux only

The licence caps the rate and the number of starts; see Licensing.

Stepped load runs

Give the steps on the command line, or in a load: block in the flow:

Shell

YAML

How it runs:

Command line vs block: each flag (-ues, -steps, -stop-when, -drain, -ramp, -ramp-from, -max-inflight, -catchup, -hold, -peer-metrics) overrides the block key of the same name.
Not with -rate, -duration or -repetitions: a load run refuses them.
Client flows only.
Step deadline: the spawn window, plus hold, plus releasing the held UEs, plus drain. -timeout, when given, bounds the whole run.
A step is clean when its verdict is pass, it didn't error, and no stop_when rule tripped.
The run stops at the first step that isn't clean.

`stop_when`: the knee rule

A key that isn't set never trips.

Key	Trips when
`success_below`	the step's success rate (%) is below this
`p99_above`	the p99 flow latency is above a duration (`250ms`) or a multiple of the first step's (`3x_first`); on a held run, the p99 time to reach the hold state
`spawn_missed_above`	missed starts are above this % of the planned starts
`spawn_lag_p99_above`	the p99 start lag is above this duration
`spawn_shift_above`	the schedule slipped by more than this duration in total
`uplane_loss_above`	user-plane loss (%) is above this
`uplane_tx_short_above`	the user-plane generator sent this % less than asked
`dn_tx_short_above`	`rk`'s data network sent this % less downlink than asked (YAML only)
`uplane_dn_unknown_ues_above`	the data network saw more unknown UEs than this (YAML only)

Outcome

Outcome	Verdict	Meaning
`completed`	pass	every step was clean
`knee`	pass	a step tripped after at least one clean step; the knee is the last clean step
`below_first_step`	fail	the first step tripped
`failed`	fail	a step failed without a `stop_when` trip
`error`	exit 4	a step errored, or the run was interrupted

The report is the last step's result, with the load verdict and a load section. load holds the knee, the stop, every step, and the host. While the run goes, rk prints one line per step to stderr.

Look at the other side

-peer-metrics <url> scrapes another rk's /metrics before and after each step, and records its CPU, memory and counters in the step. The verdict never reads it.
-profile-dir <dir> writes a CPU and heap profile of rk for each step. -profile-window <d> limits the CPU profile to the last part of the spawn window.

Compare runs

rk report summarize report.json tabulates the steps.
rk report compare before.json after.json puts two runs side by side.

See Reports.