Skip to content

Load-Test Tool: Getting Started ​

Updated: 11/10/26, 10:51:10 AM

Follow this order and you will have your first report running locally. Every write operation in the tool needs manual confirmation; nothing is automated.

Step 1: Build ​

bash
go build -o perfctl.exe .

The output is a single executable; the console frontend is already embedded, so there is no frontend build.

Step 2: Import Configuration ​

The tool reads its runtime configuration only from configs/_perf.yaml (not tracked in git). On first use, generate a candidate from the main project yml:

bash
./perfctl.exe config import --server-dir <main-project>/daxpay-start/src/main/resources
./perfctl.exe config diff     # review the differences
./perfctl.exe config apply    # merge: only empty fields are filled by default; manual values win

The main project yml is used for one-time import only, not as a runtime dependency. If the load generator host has no main project source, use the upload import on the console "Configuration" page: upload application.yml (required), application-<profile>.yml (optional), and the merchant private key PEM (optional), then fix the main app, mock, and database addresses in the "Addresses & Connections" card.

config show prints masked values (****(N chars)), safe to screenshot.

Step 3: Doctor Check Before a Run ​

bash
./perfctl.exe doctor --capacity --tps 200 --duration 60s

The doctor check verifies that the load-test database exists, that the database the app actually connects to matches the configuration, that mock capacity is sufficient, that the application log level is not too verbose, and that the target is on the intranet; it produces doctor.json and doctor.md.

  • FAIL: blocks immediately with a non-zero exit code;
  • WARN: must be confirmed item by item in the console, or via --accept-warn ID,... on the command line; the record is written into the run meta.

In the console you must click "Re-check" before a run; there is no way around it. Only for emergencies use --skip-doctor (which leaves a trace in the report).

Step 4: Start the Console ​

bash
./perfctl.exe serve

The console listens on localhost only by default; the startup log prints the actual URL. When the load generator host and the main app are on different machines, start with --addr 0.0.0.0:<port> and open the port in the firewall; non-loopback startups print a security notice.

Pages: Overview, Load Test, Live Tasks, Data Generation, Query Benchmarks, Ladder Experiments, Reports, Configuration, About.

Step 5: Prepare the Load-Test Database ​

The tool does not switch databases; the operator completes these steps:

  1. Create a dedicated load-test database (do not reuse a development or production database);
  2. Initialize the schema and seed data: table.sql → data.sql (use data-demo.sql for a quick trial), or have the DBA do it;
  3. Prepare load-test merchants in one step: perfctl db prepare --yes (rehearse first with --dry-run). The tool idempotently writes the load-test merchant, app, merchant RSA public key, mock_pay channel merchant, and scenario routing, then prints the generated identities for you to fill back into _perf.yaml;
  4. Point the main app at the load-test database and restart it;
  5. On the Mock Channel console, raise the order capacity (or set 0 for unlimited) and disable automatic callbacks;
  6. Run the doctor check again and confirm the database, capacity, and log items all PASS.

The tool never changes configuration on its own, and never creates records on the mock side for you.

Step 6: First Load Test ​

  1. Pick a scenario on the console "Load Test" page (use pay-barcode the first time);
  2. Set TPS and duration (respect the limits in the configuration: maxTps, maxDuration, maxInFlight);
  3. After starting, watch TPS, P99, and error classes on "Live Tasks";
  4. When it finishes, open the offline HTML on the "Reports" page.

To use the command line:

bash
./perfctl.exe run --scenario scenarios/pay-barcode.yaml --tps 200 --duration 60s

Next Steps ​

  • For how to choose scenarios and write parameters, see Scenarios and Reports;
  • To confirm the tool itself is configured correctly, perfctl scenario validate performs an offline self-check of scenario packs;
  • Each run's artifacts live in results/run-*/; only the latest 20 are kept by default (results.keepRuns).