Goku

Goku

Goku 是一款高性能、可扩展的 HTTP 负载测试工具，专为 Web 服务的基准测试和性能分析而设计。Goku 从 Drill 和 Vegeta 等工具汲取灵感，为工程师提供现代化功能和简洁体验，以便高效模拟和分析流量。

功能

• 快速、可扩展的 HTTP 负载测试
• 长时间测试期间实时显示统计数据
• 使用 --rps 限制速率，生成恒定速率的负载曲线
• 多步骤顺序场景（每次测试包含多个端点）
• 在 URL 和请求体中使用变量模板（{{uuid}}、{{seq}}、{{random_int}}，……）
• 内置身份验证（Bearer 令牌、Basic 身份验证）
• 文本输出中的 ASCII 延迟直方图
• 使用 compare 子命令比较两次基准测试的差异
• 输出到文件（--output-file）和记录每个请求的日志（--results-log）
• 支持 HTTP/1.1、HTTP/2
• 支持多种输出格式：text、json、csv
• 用于集成大模型/Agent 的 MCP（模型上下文协议）服务
• 将结果发送到 Observability Insight，保存运行历史并进行比较

---

安装 CLI

自动下载（Linux、OSX、WSL）

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

使用 Cargo

cargo install goku-bench
goku --version

手动下载

前往 Goku 的 GitHub Releases 页面，下载适用于你系统的最新 .tar.gz 文件：

• Linux（x86_64、arm64）
• macOS（x86_64）
• Windows（x86_64）

从源代码构建

cargo build --release

---

Observability Insight 集成

Goku 可以将每次运行的最终结果发送到 Observability Insight 中的项目，在那里查看性能测试历史记录并比较不同运行结果，以发现性能回归。请先在项目中启用 Goku 连接器。

登录（本地计算机）

goku login

Goku 会打开浏览器，你登录并选择项目后，该项目的 Goku 连接器令牌将保存在 ~/.config/goku/credentials.json 中（权限为 0600；在 macOS/Windows 上使用操作系统配置目录）。使用 --no-browser 仅打印 URL，使用 --portal-url 指定其他门户。

发送结果

goku -c 50 -d 30 --target https://api.example.com/users --report --report-name "users list" --report-tag nightly

仅发送最终摘要（吞吐量、延迟百分位数、状态码和测试配置）。发送前会从目标 URL 中移除查询字符串和凭据。如果报告无法发送，Goku 将以非零状态退出。

CI

CI 环境中无法使用浏览器：请在项目的 Goku 连接器设置中创建令牌，并将其作为 GOKU_OI_TOKEN 提供（如果使用其他门户，也可以设置 GOKU_OI_URL）。环境变量的优先级高于凭据文件。GitHub Actions 和 GitLab CI 中会自动检测提交和分支。

- run: goku -c 20 -d 60 --target https://staging.example.com --report --report-name "staging smoke"
  env:
    GOKU_OI_TOKEN: ${{ secrets.GOKU_OI_TOKEN }}

状态和注销

goku status   # project, connector and token in use
goku logout   # removes the local credentials file

goku logout 只会删除本地文件：如需使令牌失效，请在门户的 Goku 连接器设置中撤销该令牌。

---

MCP（模型上下文协议）支持

Goku 集成了 模型上下文协议（MCP），可通过任何大模型 Agent 或支持 MCP 的客户端以编程方式使用 Goku。

可实现的功能

• 无需手动使用 CLI，即可通过大模型或 AI Agent 使用 Goku。
• 将负载测试与自动化工作流结合：触发测试、收集指标，并在 Agent 或脚本中分析结果。
• 轻松集成到更广泛的工具链和 Agent 工作流中。

使用大模型的示例

将 Goku 注册为 MCP 工具后，你可以向大模型提问：

“使用 HTTP/2 对 https://api.example.com/users 进行负载测试，并发客户端数为 50，持续 30 秒，然后给出 p95 和 p99 延迟。”

大模型将调用 run_benchmark MCP 工具，并返回完整的结构化报告。

安装 MCP 服务

# Automatic download
curl -sSL https://raw.githubusercontent.com/jcaromiq/goku/v3.0.0/scripts/install_mcp.sh | sh

# Or via Cargo
cargo install goku-mcp

MCP 工具：run_benchmark

MCP 服务提供一个统一工具，包含以下参数：

参数	类型	必填	说明
target	string	✅	可选带有方法前缀的 URL。例如，"POST http://api.example.com/users"
clients	number	✅	并发工作线程数
requests	number	—	请求总数（设置 duration_secs 时会忽略）
duration_secs	number	—	测试持续时间（秒）（可替代 requests）
body	string	—	POST/PUT/PATCH 请求体
headers	string[]	—	"Name:Value" 格式的标头
http2	boolean	—	使用 HTTP/2 先验知识
ramp_up	number	—	分散工作线程启动所用的秒数
timeout_ms	number	—	请求超时时间（毫秒，默认值：30000）
insecure	boolean	—	接受无效的 TLS 证书
rps	number	—	每秒最大请求数（速率限制）

返回包含所有延迟百分位数、吞吐量和状态码明细的完整 JSON 报告。

---

版本管理

CLI 使用 SemVer v2.0.0 进行版本管理。

贡献

请参阅 CONTRIBUTING.md。

---

使用手册

Usage: goku [OPTIONS] --target <TARGET>
       goku compare <BASELINE> <CANDIDATE>
       goku login | logout | status

Options:
  -v, --verbose                        Runs in verbose mode
  -t, --target <TARGET>                URL to request. Format: [METHOD] <url>  [default: GET]
                                       Example: "POST http://localhost:3000/api"
  -r, --request-body <REQUEST_BODY>    Path to file to use as request body
  -c, --clients <CLIENTS>              Number of concurrent workers [default: 1]
  -i, --iterations <ITERATIONS>        Total number of requests [default: 1]
  -d, --duration <DURATION>            Duration of the test in seconds (alternative to --iterations)
      --headers <HEADERS>              Headers in "Name:Value" format (repeatable)
      --scenario <SCENARIO>            Path to a YAML scenario file
      --timeout <timeout_ms>           Request timeout in ms [default: 30000]
      --http2                          Enable HTTP/2 prior knowledge
      --ramp-up <seconds>              Seconds to spread the start of workers
      --rps <RPS>                      Max requests per second across all clients
      --output <text|json|csv>         Output format [default: text]
      --output-file <PATH>             Write results to file instead of stdout
      --results-log <PATH>             Write per-request CSV log (timestamp, status, latency)
      --live-stats <seconds>           Print live stats every N seconds during the test
      --insecure                       Accept invalid/self-signed TLS certificates
      --auth-bearer <TOKEN>            Set Authorization: Bearer <TOKEN> header
      --auth-basic <USER:PASS>         Set Authorization: Basic <base64> header
      --pool-idle-timeout <seconds>    Connection pool idle timeout [default: 90]
      --disable-keepalive              Disable HTTP keep-alive / connection reuse
      --report                         Send the final results to Observability Insight
      --report-name <NAME>             Name of the run in Observability Insight (requires --report)
      --report-tag <TAG>               Tag for the run in Observability Insight (repeatable, requires --report)
  -h, --help                           Print help
  -V, --version                        Print version

Subcommands:
  compare <BASELINE> <CANDIDATE>       Compare two JSON result files and show a diff table
  login [--portal-url URL] [--no-browser]  Link this machine to an Observability Insight project
  logout                               Remove the stored Observability Insight credentials
  status                               Show the project this machine reports to

---

标志参考

--target -t

指定 HTTP 方法和 URL。如果未提供方法，则默认为 GET。

goku --target "GET http://localhost:3000/"
goku --target "POST http://localhost:3000/api"
goku --target http://localhost:3000          # implicit GET

--request-body -r 可选

请求体内容所在文件的路径。

--clients -c

并发工作线程数。默认值为 1。

--iterations -i

所有工作线程要执行的请求总数。默认值为 1。不能与 --duration 同时使用。

--duration -d

将测试运行固定秒数，而不是固定请求数。

--headers 可选

添加一个或多个请求标头。可重复指定。格式：Name:Value。

goku --headers Content-Type:application/json --headers X-Api-Key:secret ...

--http2 可选

强制使用 HTTP/2 先验知识（跳过 HTTP/1.1 升级协商）。

--ramp-up 可选

将工作线程的启动时间分散到 N 秒内，以模拟逐渐出现的流量峰值。

--rps 可选

限制所有客户端的每秒总请求数。适用于恒定速率负载配置文件（类似于 Vegeta）。

goku -c 10 -i 10000 --rps 200 --target http://localhost:3000

--output 可选

输出格式。有效值：text（默认）、json、csv。

--output-file 可选

将结果写入文件，而不是 stdout。适用于任何 --output 格式。

goku -c 50 -i 1000 --output json --output-file results.json --target http://localhost:3000

--results-log 可选

写入逐请求 CSV 日志，包含以下列：timestamp_ms,num_client,execution,status,latency_ms。

goku -c 50 -i 1000 --results-log requests.csv --target http://localhost:3000

--live-stats 可选

测试运行期间，每 N 秒向 stderr 输出部分指标（请求数、RPS、p50、p95）。

goku -c 50 --duration 60 --live-stats 5 --target http://localhost:3000
  [live] requests=1250 rps=250.0 p50=45ms p95=120ms

--insecure 可选

接受无效或自签名 TLS 证书。默认关闭。

--auth-bearer 可选

自动注入 Authorization: Bearer <TOKEN> 标头。

goku --auth-bearer "eyJhbGci..." --target http://api.example.com

--auth-basic 可选

根据 user:password 凭据注入 Authorization: Basic <base64> 标头。

goku --auth-basic "admin:secret" --target http://api.example.com

--pool-idle-timeout 可选

连接池中连接的空闲超时时间（秒）。默认值为 90。

--disable-keepalive 可选

完全禁用 HTTP keep-alive 和连接复用。

--scenario 可选

YAML 场景文件的路径。使用此选项时，将忽略所有其他标志（--output 除外），并从文件中读取设置。

compare 子命令

比较两个基准测试 JSON 结果文件，并显示带颜色的差异表：

goku compare before.json after.json

---

场景文件格式

target: POST http://localhost:3000/
clients: 50
requests: 1000
duration: 60          # alternative to requests
http2: true
ramp_up: 5
rps: 500              # optional rate limit
output: json
insecure: false
live_stats: 10        # print live stats every 10s
pool_idle_timeout: 30
disable_keepalive: false

headers:
  - key: "Content-Type"
    value: "application/json"
  - key: "X-Api-Key"
    value: "secret"

body: '{"firstName": "Terry", "lastName": "Medhurst", "age": 50}'

# Optional: built-in authentication
auth:
  type: bearer
  token: "my-token"

# Optional: write results to a file
output_file: results.json
results_log: requests.csv

多步骤场景

为每个工作线程按顺序运行多个端点：

clients: 20
duration: 60

steps:
  - target: "GET http://api.example.com/users"
  - target: "POST http://api.example.com/orders"
    body: '{"item": "widget", "qty": 1}'
    headers:
      - key: "Content-Type"
        value: "application/json"
  - target: "GET http://api.example.com/orders/latest"

每个工作线程都会按顺序执行所有步骤，并在测试期间重复这一序列。

变量模板

在 URL 和请求体中使用动态占位符：

变量	描述
{{seq}}	顺序请求编号
{{client}}	工作线程 ID
{{timestamp}}	Unix 时间戳（毫秒）
{{uuid}}	伪随机 UUID v4
{{random_int(min,max)}}	[min, max] 范围内的随机整数

goku -c 10 -i 100 \
  --target "GET http://api.example.com/users/{{random_int(1,500)}}"

goku -c 10 -i 100 \
  --target "POST http://api.example.com/events" \
  --request-body body.json
# body.json: {"id": "{{uuid}}", "seq": {{seq}}, "ts": {{timestamp}}}

---

示例

简单目标

goku --target "GET http://localhost:3000"
goku --target http://localhost:3000?foo=bar
goku -c 50 -i 1000 --target http://localhost:3000
goku -c 50 --duration 60 --target http://localhost:3000

使用自定义标头

goku --target "GET http://localhost:3000" \
     --headers Content-Type:application/json \
     --headers X-Api-Key:secret

使用请求体

goku -c 50 -i 1000 -r body.json --target "POST http://localhost:3000"

使用身份验证

goku --auth-bearer "my-token" -c 20 -i 500 --target "GET http://api.example.com/protected"
goku --auth-basic "admin:pass" -c 10 -i 100 --target "GET http://api.example.com/admin"

速率受限测试

goku -c 20 --duration 60 --rps 200 --target http://localhost:3000

使用渐进加压并将 JSON 输出到文件

goku -c 100 -i 5000 --ramp-up 10 --output json --output-file results.json --target http://localhost:3000

比较两次运行

goku -c 50 -i 1000 --output json --output-file before.json --target http://localhost:3000
# deploy new version...
goku -c 50 -i 1000 --output json --output-file after.json --target http://localhost:3000
goku compare before.json after.json

输出（文本）

Concurrency level    50
Time taken           4 seconds
Total requests       1000
Requests/sec         250.00 req/s
Mean                 169.90 ms
Min                  5 ms
Max                  415 ms
p50 (median)         155 ms
p95                  319 ms
p99                  360 ms
p99.9                367 ms

Status codes
  2xx  998
  5xx  2

Latency distribution
      10ms  ████████████████████████████████████████  450
      25ms  █████████████████████████                 280
      50ms  ████████████████                          150
     200ms  ████████                                   80
     415ms  ██                                         40

输出（JSON）

{
  "concurrency": 50,
  "duration_secs": 4.12,
  "total_requests": 1000,
  "requests_per_sec": 242.72,
  "mean_ms": 169.90,
  "min_ms": 5,
  "max_ms": 415,
  "p50_ms": 155,
  "p95_ms": 319,
  "p99_ms": 360,
  "p999_ms": 367,
  "status_2xx": 998,
  "status_4xx": 0,
  "status_5xx": 2,
  "status_other": 0,
  "network_errors": 0
}

---

许可证

请参阅 LICENSE。

捐赠

如果您认可本项目所做的全部工作，欢迎小额捐赠：