Telnet Controller

The telnet Controller listens on 127.0.0.1:5116 by default, so only this machine can reach it. It has no authentication: anyone who can reach its port can start, stop and reconfigure the load test. To reach it from another machine, either forward the port over ssh to the default bind (ssh -L 5116:127.0.0.1:5116 loadtest, then telnet localhost 5116), or start Goose with an explicit host such as --telnet-host 0.0.0.0, which prints a warning at startup that the Controller has no authentication.

The host and port that the telnet Controller listens on can be configured at start time with --telnet-host and --telnet-port. The telnet Controller can be completely disabled with the --no-telnet command line option. The defaults can be changed with GooseDefault::TelnetHost, GooseDefault::TelnetPort, and GooseDefault::NoTelnet.

Controller Commands

To learn about all available commands, telnet into the Controller thread and enter help (or ?). For example:

% telnet localhost 5116
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
goose> ?
goose 0.19.1 controller commands:
help               this help
exit               exit controller

start              start an idle load test
stop               stop a running load test and return to idle state
shutdown           shutdown load test and exit controller

host HOST          set host to load test, (ie https://web.site/)
increaserate FLOAT set per-second rate users increase (0.01 to 100000)
increase-time TIME set total time to take increasing users (0 clears)
decreaserate FLOAT set per-second rate users decrease (0.01 to 100000)
decrease-time TIME set total time to take decreasing users (0 clears)
users INT          set number of simulated users (1 to 100000)
runtime TIME       set how long to hold users after the ramp up, (ie 1h30m5s, 0 clears)
test-plan PLAN     define or replace test-plan, (ie 10,5m;10,1h;0,30s)

config             display load test configuration
config-json        display load test configuration in json format
metrics            display metrics for current load test
metrics-json       display metrics for current load test in json format
goose> q
goodbye!
goose> Connection closed by foreign host.

exit, quit and q end the session, and help and ? print this list. Commands and values are not case sensitive, and most commands take aliases: increase_rate and increase-rate for increaserate, increasetime for increase-time, run_time for runtime, testplan and plan for test-plan, stats for metrics, and the like. A command takes its value after one space.

config prints the configuration, and config-json prints it as JSON, with an option that is not set shown as null and an output flag given without a path shown as (the run's folder). Neither shows the dashboard auth token: one that is set reads (set). metrics prints the metrics tables, and metrics-json prints the metrics as JSON. In that JSON each request’s raw_data holds its response times in microsecond buckets, times_us, beside minimum_time_us, maximum_time_us and total_time_us, and the whole millisecond minimum_time, maximum_time, total_time and counter; each transaction and scenario holds the same as times_us, min_time_us, max_time_us and total_time_us, beside min_time, max_time, total_time and counter. Each request also holds status_code_counts, how many responses got each status code, and status_code_timings, each status code’s count, total_time_us, min_time_us and max_time_us.

A command whose value can’t be used is refused with what the value must be, and changes nothing:

goose> users 0
users must be an integer between 1 and 100000
goose> increaserate 0
increase_rate must be a number from 0.01 to 100000
goose> runtime 31d
run_time must be a time span such as 1h30m5s, from 1 second to 30 days, or 0 to clear

Telnet, WebSocket and the dashboard share these bounds:

host, increase-time and decrease-time are accepted only while the load test is idle, as they are read when it starts. runtime, users and test-plan also change a running load test. A runtime on a running users ramp moves the end of the hold in progress to its start plus the new run time, and starts the ramp down at once if that has passed. If the new run time puts the end of the hold earlier than the end of the ramp from a users change made during the hold, the run holds until stopped. Before the hold starts, a runtime replaces the hold ahead, and on a run holding until stopped it holds from now for the new run time, then ramps down. runtime 0 on a running test holds until stopped, and is refused while a ramp down is configured. runtime is refused during the ramp down, while stopping and while a test plan runs, as the plan sets how long it runs. See Run time on a running test. A users change on a running users ramp keeps its run time and ramp down: it ramps to the new count, holds, and ramps down from the new count. A change during the ramp up holds for the full run time; a change during the hold keeps the hold’s end. If the new ramp outlasts the hold, or the new count is the one the run already has, it holds that count until stopped. A users change during the ramp down abandons it and holds the new count until stopped. users is refused while a test plan runs, as the plan sets users. See Users on a running test.

The rates are accepted in Idle and on a running users ramp, and are refused during its ramp down, while stopping and while a test plan runs. On a running test, a rate is refused while its own time is set, since a time changes only in Idle; in Idle a rate clears its own time and a time clears its own rate. A decrease rate on a running users ramp regenerates the ramp down still ahead, or adds one where all users would stop at once when the hold ends; an increase rate is for the next users increase.

A test plan sets users, so a rate or a time is refused in Idle with set users first to switch to a users ramp, and, while the plan runs, with a test plan is running. While one is configured, users switches to a users ramp and clears the plan, and test-plan switches back and clears users, the rates and the times. The command line’s rules also apply: runtime, decreaserate, decrease-time and test-plan are refused under --iterations, test-plan under --no-reset-metrics, and in Idle increase-time or decrease-time with fewer than 2 users, or users 1 while either is set. users and test-plan are refused while a stop, shutdown or Ctrl-C is ramping the load test down. A command that gets no answer within 15 seconds is answered control timed out, it may still apply: check before retrying: check the configuration or metrics before sending it again.

Example

One possible use-case for the controller is to dynamically reconfigure the number of users being simulated by the load test. In the following example, the load test was launched with the following parameters:

% cargo run --release --example umami -- --no-autostart --telnet-host 0.0.0.0 --host https://umami.ddev.site/ --increase-rate 50 --report-file report.html --report-file report.md

The --telnet-host 0.0.0.0 lets the telnet Controller be reached from another machine, here one that reaches the load test as loadtest, and prints the warning that it has no authentication.

Then the telnet controller is invoked as follows:

% telnet loadtest 5116
Trying loadtest...
Connected to loadtest.
Escape character is '^]'.
goose> start 
load test started
goose> users 20
users configured
goose> users 40
users configured
goose> users 80
users configured
goose> users 40 
users configured
goose> users 20
users configured
goose> users 160
users configured
goose> users 20
users configured
goose> increase_rate 5
increase_rate configured
goose> users 80
users configured
goose> users 20
users configured
goose> shutdown
load test shut down
goose> Connection closed by foreign host.

Initially the load test is configured with an increase rate of 50, so goose increases and decreases the user count by 50 user threads per second: with no decrease rate set, Goose lowers the user count at the increase rate. Later we reconfigure the increase rate to 5, slowing down the rate that goose alters the number of user threads. This graph, from the end of that load test, shows the result:

The above commands are also summarized in the plan overview of the Markdown report, report.md, here from a run of the same commands against a local server (the HTML report has the same table):

## Plan Overview

| Action | Started | Stopped | Elapsed | Users |
| ------ | ------- | ------- | ------- | ----: |
| Increasing | 26-10-25 22:12:31 | 26-10-25 22:12:31 | 00:00:00 | 0 → 18 |
| Maintaining | 26-10-25 22:12:31 | 26-10-25 22:12:43 | 00:00:12 | 18 |
| Increasing | 26-10-25 22:12:43 | 26-10-25 22:12:43 | 00:00:00 | 18 → 20 |
| Maintaining | 26-10-25 22:12:43 | 26-10-25 22:12:55 | 00:00:12 | 20 |
| Increasing | 26-10-25 22:12:55 | 26-10-25 22:12:56 | 00:00:01 | 20 → 40 |
| Maintaining | 26-10-25 22:12:56 | 26-10-25 22:13:07 | 00:00:11 | 40 |
| Increasing | 26-10-25 22:13:07 | 26-10-25 22:13:08 | 00:00:01 | 40 → 80 |
| Maintaining | 26-10-25 22:13:08 | 26-10-25 22:13:22 | 00:00:14 | 80 |
| Decreasing | 26-10-25 22:13:22 | 26-10-25 22:13:23 | 00:00:01 | 40 ← 80 |
| Maintaining | 26-10-25 22:13:23 | 26-10-25 22:13:34 | 00:00:11 | 40 |
| Decreasing | 26-10-25 22:13:34 | 26-10-25 22:13:34 | 00:00:00 | 20 ← 40 |
| Maintaining | 26-10-25 22:13:34 | 26-10-25 22:13:46 | 00:00:12 | 20 |
| Increasing | 26-10-25 22:13:46 | 26-10-25 22:13:49 | 00:00:03 | 20 → 160 |
| Maintaining | 26-10-25 22:13:49 | 26-10-25 22:14:01 | 00:00:12 | 160 |
| Decreasing | 26-10-25 22:14:01 | 26-10-25 22:14:04 | 00:00:03 | 20 ← 160 |
| Maintaining | 26-10-25 22:14:04 | 26-10-25 22:14:17 | 00:00:13 | 20 |
| Increasing | 26-10-25 22:14:17 | 26-10-25 22:14:22 | 00:00:05 | 20 → 43 |
| Decreasing | 26-10-25 22:14:22 | 26-10-25 22:14:27 | 00:00:05 | 20 ← 43 |
| Maintaining | 26-10-25 22:14:27 | 26-10-25 22:14:47 | 00:00:20 | 20 |
| Canceling | 26-10-25 22:14:47 | 26-10-25 22:14:48 | 00:00:01 | 0 ← 20 |

The run starts with the default users, one per CPU core (18 here). At 5 users a second, the users 80 that follows increase_rate 5 had reached 43 users when users 20 arrived about 5 seconds later, so Goose turned back from 43.