Installing surge
surge is one static binary with no runtime to install beside it. Pick whichever of these fits the machine; they all give the same program.
Go toolchain
go install gitlab.com/agentic-fx/surge/cmd/surge@latestGo 1.23 or newer. The binary lands in $(go env GOPATH)/bin; put that on your PATH if it is not already. Check it with:
surge versionAs a library
go get gitlab.com/agentic-fx/surgeThree dependencies: yaml.v3, gjson and coder/websocket. gRPC lives in a separate module (gitlab.com/agentic-fx/surge/grpcx) so an HTTP-only test does not pull its dependency tree.
From source
git clone https://gitlab.com/agentic-fx/surge
cd surge
go build -o surge ./cmd/surge
./surge versionmake test runs the whole suite, including the ones that build the binary and run it against a local server. It is go test -race ./..., and the -race is not optional advice: surge is a program whose whole job is doing many things at once, and a plain go test ./... has passed on this repository while the race detector had three findings waiting. make test-short is the same thing without the throughput measurement, which needs a quiet machine to mean anything, and is what the pipeline runs.
In a container
docker build -t surge -f deploy/docker/Dockerfile .
docker run --rm -v "$PWD:/work" -w /work surge run perf/checkout.yamlAbout 35MB on alpine, surge plus the demo target. deploy/docker/docker-compose.yml brings up a coordinator and three agents; deploy/docker/run-cluster.sh drives it.
In Kubernetes
deploy/kubernetes/ has four manifests, and its README says which to use when:
| File | For |
|---|---|
run-job.yaml | one Job, one scenario, the report to a volume |
parallel-job.yaml | an indexed Job: each pod takes its own -shard i/n, no coordinator |
agents.yaml | a Deployment of surge agent pods with a headless Service |
go-scenario.yaml | the same, for a scenario compiled as a Go binary |
In CI
Nothing to install if the job already has Go:
- run: go install gitlab.com/agentic-fx/surge/cmd/surge@latest
- run: surge preflight perf/checkout.yaml
- run: surge run perf/checkout.yaml -json current.json -html report.htmlPin the version (@v0.9.0) rather than @latest once the gate matters: a tool that changes under a regression gate makes every comparison suspect. Catching regressions has the rest.
What surge needs from the machine
- File descriptors. One connection per virtual user, plus the listener.
surge preflightchecks the limit against the plan's peak and says so before the run rather than after it. - CPU. surge watches its own: above 85%, or when its goroutine scheduling delay grows next to the measured p95, the report is marked untrustworthy. A container throttled by its cgroup quota reads low on CPU precisely because the kernel is holding it back, which is why the scheduling delay is watched too.
- Nothing else. No agent, no database, no service.