The live dashboard and the control UI
Two different things, for two different moments.
-web — watching a run that is already going
surge run perf/checkout.yaml -web :8088A read-only page on :8088: throughput, latency, virtual users and every threshold, evaluated every second against the run so far. It is the same data the console prints, drawn as it arrives, and on a distributed run it is the fleet's — each node's contribution named, with the worst node's p95 rather than an average of percentiles, because averaging percentiles is wrong and surge will print nothing before it prints a number that is not true.
-hold D keeps the page up for D after the run ends, so a glance at the end does not race the process exiting.
It starts nothing. Closing it does not stop the run.
surge web — starting and stopping runs from a page
surge web -dir perf # http://127.0.0.1:8099
surge web -dir perf -open # and open a browserPick a scenario from the folder, set users and duration, press Start, watch it live, press Stop, open the report. For a team that will not live in a terminal.
| Flag | Default | What it is for |
|---|---|---|
-dir | . | the only folder whose scenarios may be run |
-listen | 127.0.0.1:8099 | anything but loopback requires -token |
-token | — | a shared secret on every API call |
-allow-exec | off | permit scenarios with setup, teardown or exec steps |
-out | -dir | where reports are written |
-open | off | open the page in a browser |
It refuses by default
An endpoint that starts load tests is a weapon if it is reachable, so:
- Loopback unless told otherwise. A bind to anything else without a token is refused at construction, not after the socket is open — the window between "listening" and "protected" is the problem, and there is no window.
- Only scenarios inside
-dir. The path is resolved and compared, not filtered:../is only the obvious way out. - A scenario that runs shell commands is refused unless
-allow-exec, and the picker marks it runs shell commands before anyone clicks. A scenario withsetup:is as powerful as a shell script; read one before you run it, as you would a script.
It is a local control panel, not a service. Do not put it on a shared host.
Each run is a child process
The page spawns surge run and shows the exact command above its output, so what the page runs is what you can re-run from a shell. Three reasons that is worth more than the code it saves:
- a run that panics does not take the UI with it;
- Stop is an interrupt, which the CLI already handles as a graceful stop, so in-flight iterations finish and the report is still written;
- there is nothing the page can do that you cannot.
Stopping a run that has only just started — in the few milliseconds between the process starting and surge installing its own signal handler — kills it before it can write anything, and the page says so rather than showing a bare exit code with no report beside it.