P
perfscale

Overview

perfscale documentation

perfscale is a single CLI for running load tests with k6, locust, or perfscale's own native step engine — plus a tiny local dev server for collecting results.

Start here

CLI (perfscale binary)

  • Commands — run, serve, lint, and schema reference
  • Recipes — copy-paste examples for common workflows
  • Benchmarks — engine comparison methodology & CI runs
  • MCP server — drive perfscale from AI agents over the Model Context Protocol

Core (perfscale-core library)

  • Architecture — how the pieces fit together
  • Runners — k6, locust, JMeter, and the native engine
  • Actions — std/http, std/tcp, std/udp, std/ws* (WebSocket), std/graphql (GraphQL), std/grpc* (gRPC), std/db-* (SQL databases), std/check, std/sleep, std/log, std/file-*, std/child_process, std/kill_process, std/set_shared_variable, std/get_shared_variable, std/thresholds
  • Setup and teardown — before:/after: lifecycle, config.*/vars.* data flow, background processes
  • Imports — compose test/config documents from a shared base: local paths, HTTP URLs, git repos; merge semantics, caching, and the --allow-remote-import security gate
  • Metrics — http_req_*, [stats] lines, custom counters/histograms, --quiet, summary forwarding
  • WebSocket guide — sessions, live connections, message RTT, assertions
  • GraphQL guide — queries/mutations, introspection schema validation
  • gRPC guide — dynamic schemas (reflection / descriptor sets), unary calls, streams
  • Shared variables guide — cross-VU shared mutable state: counters, producer/consumer queues, barriers
  • GPU metrics guide — utilization/VRAM/temp/power during a run, nvidia-smi and dcgm-exporter sources
  • JMeter guide — run existing .jmx plans headless, translated k6-compatible summary, parameterization, limits
  • Docker — ready-to-run ghcr.io images (slim and k6-bundled flavors), mounting scenarios, CI and Kubernetes recipes

For contributors