Skip to content
Back to search

goku

Goku is an HTTP load testing application written in Rust

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jcaromiq--goku/badge.svg)](/listings/jcaromiq--goku)

HTML

<a href="/listings/jcaromiq--goku"><img src="/api/listings/jcaromiq--goku/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Automatic download (Linux, OSX, WSL)

curl -sSL https://raw.githubusercontent.com/jcaromiq/goku/v3.0.0/scripts/install.sh | sh

Using Cargo

cargo install goku-bench
goku --version

Manual download

Go to the Goku's [GitHub Releases page](https://github.com/jcaromiq/goku/releases) and download the latest `.tar.gz` for your system:

* Linux (x86_64, arm64) * macOS (x86_64) * Windows (x86_64)

From source

cargo build --release

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 498 lines · 2 findings marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Goku
  2. [![Rust](https://github.com/jcaromiq/goku/actions/workflows/ci.yml/badge.svg)](https://github.com/jcaromiq/goku/actions/workflows/ci.yml)
  3. [![](https://img.shields.io/crates/v/goku-bench.svg?ts=2)](https://crates.io/crates/goku-bench)
  4. ![Goku](https://raw.githubusercontent.com/jcaromiq/goku/main/assets/goku.png)
  5. Goku is a high-performance, scalable HTTP load-testing tool designed for benchmarking and performance analysis of web services. Inspired by tools like [Drill](https://github.com/fcsonline/drill) and [Vegeta](https://github.com/tsenart/vegeta), Goku offers modern features and simplicity for engineers to simulate and analyze traffic efficiently.
  6. ## Features
  7. * Fast and scalable HTTP load testing
  8. * Real-time live stats during long tests
  9. * Rate limiting (`--rps`) for constant-rate load profiles
  10. * Multi-step sequential scenarios (multiple endpoints per test)
  11. * Variable templating in URLs and bodies (`{{uuid}}`, `{{seq}}`, `{{random_int}}`, …)
  12. * Built-in authentication (Bearer token, Basic auth)
  13. * ASCII latency histogram in text output
  14. * `compare` subcommand to diff two benchmark runs
  15. * Output to file (`--output-file`) and per-request log (`--results-log`)
  16. * HTTP/1.1, HTTP/2 support
  17. * Multiple output formats: `text`, `json`, `csv`
  18. * MCP (Model Context Protocol) server for LLM/agent integration
  19. * Send results to [Observability Insight](https://portal.observabilityinsight.com) to keep a history of runs and compare them
  20. ---
  21. ## Install CLI
  22. ### Automatic download (Linux, OSX, WSL)
  23. ```bash
  24. curl -sSL https://raw.githubusercontent.com/jcaromiq/goku/v3.0.0/scripts/install.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 32 on GitHub
  25. ```
  26. ### Using Cargo
  27. ```bash
  28. cargo install goku-bench
  29. goku --version
  30. ```
  31. ### Manual download
  32. Go to the Goku's [GitHub Releases page](https://github.com/jcaromiq/goku/releases) and download the latest `.tar.gz` for your system:
  33. * Linux (x86_64, arm64)
  34. * macOS (x86_64)
  35. * Windows (x86_64)
  36. ### From source
  37. ```shell
  38. cargo build --release
  39. ```
  40. ---
  41. ## Observability Insight integration
  42. Goku can send the final results of every run to a project in
  43. [Observability Insight](https://portal.observabilityinsight.com), where you get the history of your
  44. performance tests and can compare runs to spot regressions. Enable the **Goku** connector in your project first.
  45. ### Log in (local machine)
  46. ```shell
  47. goku login
  48. ```
  49. Goku opens the browser, you log in and choose the project, and a token for that project's Goku connector
  50. is stored in `~/.config/goku/credentials.json` (permissions `0600`; on macOS/Windows the OS config
  51. directory is used). Use `--no-browser` to only print the URL, and `--portal-url` to point to another portal.
  52. ### Send results
  53. ```shell
  54. goku -c 50 -d 30 --target https://api.example.com/users --report --report-name "users list" --report-tag nightly
  55. ```
  56. Only the final summary (throughput, latency percentiles, status codes and the test configuration) is sent.
  57. Query strings and credentials in target URLs are stripped before sending. If the report cannot be sent,
  58. Goku exits with a non-zero status.
  59. ### CI
  60. Browsers are not available in CI: create a token in the project's Goku connector settings and expose it as
  61. `GOKU_OI_TOKEN` (optionally `GOKU_OI_URL` for another portal). Environment variables take precedence over
  62. the credentials file. Commit and branch are detected on GitHub Actions and GitLab CI.
  63. ```yaml
  64. - run: goku -c 20 -d 60 --target https://staging.example.com --report --report-name "staging smoke"
  65. env:
  66. GOKU_OI_TOKEN: ${{ secrets.GOKU_OI_TOKEN }}
  67. ```
  68. ### Status and logout
  69. ```shell
  70. goku status # project, connector and token in use
  71. goku logout # removes the local credentials file
  72. ```
  73. `goku logout` only deletes the local file: revoke the token from the Goku connector settings in the portal
  74. to invalidate it.
  75. ---
  76. ## MCP (Model Context Protocol) Support
  77. Goku integrates with the **Model Context Protocol (MCP)** — use Goku programmatically from any LLM agent or MCP-aware client.
  78. ### What this enables
  79. - Use Goku from an LLM or AI agent — no manual CLI usage required.
  80. - Combine load testing with automated workflows: trigger a test, gather metrics, and analyze results from within an agent or script.
  81. - Seamless integration into broader toolchains and agentic pipelines.
  82. ### Example usage with an LLM
  83. Once Goku is registered as an MCP tool, you can ask your LLM:
  84. > **"Run a load test on https://api.example.com/users with 50 concurrent clients for 30 seconds using HTTP/2, and give me the p95 and p99 latency."**
  85. The LLM will call the `run_benchmark` MCP tool and return the full structured report.
  86. ### Install MCP server
  87. ```bash
  88. # Automatic download
  89. curl -sSL https://raw.githubusercontent.com/jcaromiq/goku/v3.0.0/scripts/install_mcp.sh | sh
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 130 on GitHub
  90. # Or via Cargo
  91. cargo install goku-mcp
  92. ```
  93. ### MCP tool: `run_benchmark`
  94. The MCP server exposes a single unified tool with the following parameters:
  95. | Parameter | Type | Required | Description |
  96. |---|---|---|---|
  97. | `target` | string | ✅ | URL with optional method prefix. E.g. `"POST http://api.example.com/users"` |
  98. | `clients` | number | ✅ | Number of concurrent workers |
  99. | `requests` | number | — | Total requests (ignored when `duration_secs` is set) |
  100. | `duration_secs` | number | — | Test duration in seconds (alternative to `requests`) |
  101. | `body` | string | — | Request body for POST/PUT/PATCH |
  102. | `headers` | string[] | — | Headers in `"Name:Value"` format |
  103. | `http2` | boolean | — | Use HTTP/2 prior knowledge |
  104. | `ramp_up` | number | — | Seconds to spread worker start |
  105. | `timeout_ms` | number | — | Request timeout in ms (default: 30000) |
  106. | `insecure` | boolean | — | Accept invalid TLS certificates |
  107. | `rps` | number | — | Max requests per second (rate limiting) |
  108. Returns a full JSON report with all latency percentiles, throughput, and status code breakdown.
  109. ---
  110. ## Versioning
  111. CLI is versioned with [SemVer v2.0.0](https://semver.org/spec/v2.0.0.html).
  112. ## Contributing
  113. See [CONTRIBUTING.md](.github/CONTRIBUTING.md).
  114. ---
  115. ## Usage manual
  116. ```console
  117. Usage: goku [OPTIONS] --target <TARGET>
  118. goku compare <BASELINE> <CANDIDATE>
  119. goku login | logout | status
  120. Options:
  121. -v, --verbose Runs in verbose mode
  122. -t, --target <TARGET> URL to request. Format: [METHOD] <url> [default: GET]
  123. Example: "POST http://localhost:3000/api"
  124. -r, --request-body <REQUEST_BODY> Path to file to use as request body
  125. -c, --clients <CLIENTS> Number of concurrent workers [default: 1]
  126. -i, --iterations <ITERATIONS> Total number of requests [default: 1]
  127. -d, --duration <DURATION> Duration of the test in seconds (alternative to --iterations)
  128. --headers <HEADERS> Headers in "Name:Value" format (repeatable)
  129. --scenario <SCENARIO> Path to a YAML scenario file
  130. --timeout <timeout_ms> Request timeout in ms [default: 30000]
  131. --http2 Enable HTTP/2 prior knowledge
  132. --ramp-up <seconds> Seconds to spread the start of workers
  133. --rps <RPS> Max requests per second across all clients
  134. --output <text|json|csv> Output format [default: text]
  135. --output-file <PATH> Write results to file instead of stdout
  136. --results-log <PATH> Write per-request CSV log (timestamp, status, latency)
  137. --live-stats <seconds> Print live stats every N seconds during the test
  138. --insecure Accept invalid/self-signed TLS certificates
  139. --auth-bearer <TOKEN> Set Authorization: Bearer <TOKEN> header
  140. --auth-basic <USER:PASS> Set Authorization: Basic <base64> header
  141. --pool-idle-timeout <seconds> Connection pool idle timeout [default: 90]
  142. --disable-keepalive Disable HTTP keep-alive / connection reuse
  143. --report Send the final results to Observability Insight
  144. --report-name <NAME> Name of the run in Observability Insight (requires --report)
  145. --report-tag <TAG> Tag for the run in Observability Insight (repeatable, requires --report)
  146. -h, --help Print help
  147. -V, --version Print version
  148. Subcommands:
  149. compare <BASELINE> <CANDIDATE> Compare two JSON result files and show a diff table
  150. login [--portal-url URL] [--no-browser] Link this machine to an Observability Insight project
  151. logout Remove the stored Observability Insight credentials
  152. status Show the project this machine reports to
  153. ```
  154. ---
  155. ### Flag reference
  156. #### `--target` `-t`
  157. Specifies the HTTP method and URL. Defaults to `GET` if no method is provided.
  158. ```
  159. goku --target "GET http://localhost:3000/"
  160. goku --target "POST http://localhost:3000/api"
  161. goku --target http://localhost:3000 # implicit GET
  162. ```
  163. #### `--request-body` `-r` Optional
  164. Path to a file whose contents will be sent as the request body.
  165. #### `--clients` `-c`
  166. Number of concurrent workers. Defaults to `1`.
  167. #### `--iterations` `-i`
  168. Total number of requests to perform across all workers. Defaults to `1`. Cannot be used together with `--duration`.
  169. #### `--duration` `-d`
  170. Run the test for a fixed number of seconds instead of a fixed request count.
  171. #### `--headers` Optional
  172. Add one or more request headers. Repeatable. Format: `Name:Value`.
  173. ```
  174. goku --headers Content-Type:application/json --headers X-Api-Key:secret ...
  175. ```
  176. #### `--http2` Optional
  177. Force HTTP/2 prior knowledge (skips HTTP/1.1 upgrade negotiation).
  178. #### `--ramp-up` Optional
  179. Spread the start of workers over N seconds to simulate a gradual traffic spike.
  180. #### `--rps` Optional
  181. Limit the total requests per second across all clients. Useful for constant-rate load profiles (similar to Vegeta).
  182. ```
  183. goku -c 10 -i 10000 --rps 200 --target http://localhost:3000
  184. ```
  185. #### `--output` Optional
  186. Output format. Valid values: `text` (default), `json`, `csv`.
  187. #### `--output-file` Optional
  188. Write results to a file instead of stdout. Works with any `--output` format.
  189. ```
  190. goku -c 50 -i 1000 --output json --output-file results.json --target http://localhost:3000
  191. ```
  192. #### `--results-log` Optional
  193. Write a per-request CSV log with columns `timestamp_ms,num_client,execution,status,latency_ms`.
  194. ```
  195. goku -c 50 -i 1000 --results-log requests.csv --target http://localhost:3000
  196. ```
  197. #### `--live-stats` Optional
  198. Print partial metrics (requests, RPS, p50, p95) to stderr every N seconds while the test runs.
  199. ```
  200. goku -c 50 --duration 60 --live-stats 5 --target http://localhost:3000
  201. [live] requests=1250 rps=250.0 p50=45ms p95=120ms
  202. ```
  203. #### `--insecure` Optional
  204. Accept invalid or self-signed TLS certificates. **Off by default.**
  205. #### `--auth-bearer` Optional
  206. Inject an `Authorization: Bearer <TOKEN>` header automatically.
  207. ```
  208. goku --auth-bearer "eyJhbGci..." --target http://api.example.com
  209. ```
  210. #### `--auth-basic` Optional
  211. Inject an `Authorization: Basic <base64>` header from `user:password` credentials.
  212. ```
  213. goku --auth-basic "admin:secret" --target http://api.example.com
  214. ```
  215. #### `--pool-idle-timeout` Optional
  216. Idle timeout for pooled connections in seconds. Defaults to `90`.
  217. #### `--disable-keepalive` Optional
  218. Disable HTTP keep-alive and connection reuse entirely.
  219. #### `--scenario` Optional
  220. Path to a YAML scenario file. When used, all other flags (except `--output`) are ignored and settings are read from the file.
  221. #### `compare` Subcommand
  222. Compare two benchmark JSON result files and show a colored diff table:
  223. ```
  224. goku compare before.json after.json
  225. ```
  226. ---
  227. ### Scenario file format
  228. ```yaml
  229. target: POST http://localhost:3000/
  230. clients: 50
  231. requests: 1000
  232. duration: 60 # alternative to requests
  233. http2: true
  234. ramp_up: 5
  235. rps: 500 # optional rate limit
  236. output: json
  237. insecure: false
  238. live_stats: 10 # print live stats every 10s
  239. pool_idle_timeout: 30
  240. disable_keepalive: false
  241. headers:
  242. - key: "Content-Type"
  243. value: "application/json"
  244. - key: "X-Api-Key"
  245. value: "secret"
  246. body: '{"firstName": "Terry", "lastName": "Medhurst", "age": 50}'
  247. # Optional: built-in authentication
  248. auth:
  249. type: bearer
  250. token: "my-token"
  251. # Optional: write results to a file
  252. output_file: results.json
  253. results_log: requests.csv
  254. ```
  255. #### Multi-step scenarios
  256. Run multiple endpoints sequentially per worker:
  257. ```yaml
  258. clients: 20
  259. duration: 60
  260. steps:
  261. - target: "GET http://api.example.com/users"
  262. - target: "POST http://api.example.com/orders"
  263. body: '{"item": "widget", "qty": 1}'
  264. headers:
  265. - key: "Content-Type"
  266. value: "application/json"
  267. - target: "GET http://api.example.com/orders/latest"
  268. ```
  269. Each worker executes all steps in order, repeating the sequence for the duration of the test.
  270. #### Variable templating
  271. Use dynamic placeholders in URLs and bodies:
  272. | Variable | Description |
  273. |---|---|
  274. | `{{seq}}` | Sequential request number |
  275. | `{{client}}` | Worker ID |
  276. | `{{timestamp}}` | Unix timestamp in ms |
  277. | `{{uuid}}` | Pseudo-random UUID v4 |
  278. | `{{random_int(min,max)}}` | Random integer in `[min, max]` |
  279. ```
  280. goku -c 10 -i 100 \
  281. --target "GET http://api.example.com/users/{{random_int(1,500)}}"
  282. goku -c 10 -i 100 \
  283. --target "POST http://api.example.com/events" \
  284. --request-body body.json
  285. # body.json: {"id": "{{uuid}}", "seq": {{seq}}, "ts": {{timestamp}}}
  286. ```
  287. ---
  288. ### Examples
  289. ###### Simple targets
  290. ```
  291. goku --target "GET http://localhost:3000"
  292. goku --target http://localhost:3000?foo=bar
  293. goku -c 50 -i 1000 --target http://localhost:3000
  294. goku -c 50 --duration 60 --target http://localhost:3000
  295. ```
  296. ###### With custom headers
  297. ```
  298. goku --target "GET http://localhost:3000" \
  299. --headers Content-Type:application/json \
  300. --headers X-Api-Key:secret
  301. ```
  302. ###### With request body
  303. ```
  304. goku -c 50 -i 1000 -r body.json --target "POST http://localhost:3000"
  305. ```
  306. ###### With authentication
  307. ```
  308. goku --auth-bearer "my-token" -c 20 -i 500 --target "GET http://api.example.com/protected"
  309. goku --auth-basic "admin:pass" -c 10 -i 100 --target "GET http://api.example.com/admin"
  310. ```
  311. ###### Rate-limited test
  312. ```
  313. goku -c 20 --duration 60 --rps 200 --target http://localhost:3000
  314. ```
  315. ###### With ramp-up and JSON output to file
  316. ```
  317. goku -c 100 -i 5000 --ramp-up 10 --output json --output-file results.json --target http://localhost:3000
  318. ```
  319. ###### Compare two runs
  320. ```
  321. goku -c 50 -i 1000 --output json --output-file before.json --target http://localhost:3000
  322. # deploy new version...
  323. goku -c 50 -i 1000 --output json --output-file after.json --target http://localhost:3000
  324. goku compare before.json after.json
  325. ```
  326. ###### Output (Text)
  327. ```
  328. Concurrency level 50
  329. Time taken 4 seconds
  330. Total requests 1000
  331. Requests/sec 250.00 req/s
  332. Mean 169.90 ms
  333. Min 5 ms
  334. Max 415 ms
  335. p50 (median) 155 ms
  336. p95 319 ms
  337. p99 360 ms
  338. p99.9 367 ms
  339. Status codes
  340. 2xx 998
  341. 5xx 2
  342. Latency distribution
  343. 10ms ████████████████████████████████████████ 450
  344. 25ms █████████████████████████ 280
  345. 50ms ████████████████ 150
  346. 200ms ████████ 80
  347. 415ms ██ 40
  348. ```
  349. ###### Output (JSON)
  350. ```json
  351. {
  352. "concurrency": 50,
  353. "duration_secs": 4.12,
  354. "total_requests": 1000,
  355. "requests_per_sec": 242.72,
  356. "mean_ms": 169.90,
  357. "min_ms": 5,
  358. "max_ms": 415,
  359. "p50_ms": 155,
  360. "p95_ms": 319,
  361. "p99_ms": 360,
  362. "p999_ms": 367,
  363. "status_2xx": 998,
  364. "status_4xx": 0,
  365. "status_5xx": 2,
  366. "status_other": 0,
  367. "network_errors": 0
  368. }
  369. ```
  370. ---
  371. ## License
  372. See [LICENSE](LICENSE).
  373. ## Donate
  374. If you appreciate all the job done in this project, a small donation is always welcome:
  375. [!["Buy Me A Coffee"](https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png)](https://www.buymeacoffee.com/jcaro)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.