Upgrading From 0.18

Change the dependency to goose = "^0.19". The changes below can break a load test written for Goose 0.18, or change what it does.

Removed options

The new --decrease-rate and --decrease-time control the ramp down; without them Goose stops all users at once, as 0.18 did. See the ramp down rate. Neither is allowed with --iterations: the run fails at startup with `configuration.decrease_rate` can not be set with `configuration.iterations`., or the same for decrease_time. Drop the decrease option, as each user stops after its iterations anyway.

API changes

• API change: the command line is parsed with clap. Remove use gumdrop::Options;: GooseConfiguration::parse_args_default() is now a method of its own, and GooseConfiguration implements clap::Parser. See Custom options.
• API change: every GooseConfiguration field for an option that takes a single value, such as host, run_time, increase_time or iterations, is an Option, None when not given; set one with Some, as in configuration.run_time = Some("30s".to_string()). The help field is gone. See Custom options.
• API change: session data must implement Clone; add #[derive(Clone)] to the struct. See the Session example.
• API change: GooseConfiguration::parse_args_default() returns GooseError::InvalidOption for -h and --help, with the flag as option and the detail help was requested, where 0.18 returned the configuration with its help field set to true. See Building the configuration yourself.
• API change: TransactionError::RequestFailed { raw_request } holds a Box<GooseRequestMetric>, TransactionError::LoggerFailed { source } a boxed SendError, and the new TransactionError::Custom(String) lets a transaction return Err("reason".into()). See Transaction error types.
• API change: a match without a wildcard arm needs new arms for TransactionError::Custom (see Transaction error types), GooseError::ThresholdsFailed (see The end of the run), GooseMethod::Custom (see The API) and the new GooseDefault variants (see Defaults).
• API change: scenario and transaction names are Arc<str> in place of String: Scenario.name, Scenario.machine_name, the name of ScenarioMetric, TransactionMetric and ScenarioMetricAggregate, TransactionMetricAggregate.scenario_name, GooseRequestMetric.name and GooseRequestMetric.scenario_name, and the scenario_name argument of GooseUser::new(). Reading one as &str works unchanged. See the API documentation.
• API change: Transaction.name and the transaction_name of GooseRequestMetric and TransactionMetricAggregate are a goose::goose::TransactionName in place of a String: TransactionOnly(Arc<str>) for a name set with set_name(), or InheritNameByRequests(Arc<str>) for one set with set_name_for_transaction_and_requests(). Read the name with name_for_transaction(). GooseRequestMetric.transaction_index is a usize in place of a String. See Naming Transactions and the API documentation.
• API change: times are kept in microseconds. GooseRequestMetricTimingData has times_us, minimum_time_us, maximum_time_us and total_time_us in place of the millisecond times, minimum_time, maximum_time and total_time; TransactionMetricAggregate and ScenarioMetricAggregate keep their times in run_times; a struct literal of GooseRequestMetric, TransactionMetric or ScenarioMetric must set the new response_time_fraction_us or run_time_fraction_us. See Response times and the API documentation of GooseRequestMetricTimingData, TransactionMetricAggregate and ScenarioMetricAggregate.
• goose-eggs 0.6 is built for Goose 0.18. A load test that uses goose-eggs moves to Goose 0.19 with goose-eggs 0.7: set goose-eggs = "0.7". See Goose Eggs.
• API change: the default crate features are now cookies, so default-features = false turns off cookie support, where in 0.18 it turned off TLS, and the rustls-tls feature no longer changes the TLS that load test requests use.
• API change: controller::ControllerCommand carries each command’s parsed value, and util::parse_timespan() returns Option<usize>. See Controller commands and the API documentation of ControllerCommand and parse_timespan().
• API change: TestPlan::total_users() stops at usize::MAX in place of overflowing, and GooseError::InvalidControllerCommand is no longer returned, though the variant is kept. See the API documentation of TestPlan.
• API change: TransactionDetail has no lifetime parameter: its scenario_name is an Arc<str>, its transaction_index an Option<usize> and its transaction_name a TransactionName, where 0.18 held &strs. GooseRequestMetric.transaction_index is usize::MAX for a request made outside a transaction. See the API documentation of TransactionDetail.
• API change: a transaction error is recorded. GooseMetrics has the new public field transaction_errors, a GooseTransactionErrorMetrics of GooseTransactionErrorMetricAggregates, and GooseTransactionErrorMetric is an error log entry. GooseMetric has the new variants All, Batch and TransactionError, and GooseLog the new variants TransactionError and FailedTransaction, so a match on either without a wildcard arm needs new arms. See Error log.
• API change: GooseMetrics has the new public field thresholds, each rule’s ThresholdResult, and the new goose::threshold module holds Threshold and ThresholdResult. See Thresholds.
• API change: GooseConfiguration has new public fields: threshold, no_threshold_abort, threshold_abort_delay, output_dir, compress, notes, report_graph_data, render_report and websocket, among others, and, with the pdf-reports feature, pdf_scale and pdf_timeout, an Option<f64> and an Option<u64> set in code with GooseDefault::PdfScale and GooseDefault::PdfTimeout. See Custom options and Output files.
• API change: config::RUN_FOLDER and reset_killswitch() are public. See Output files and Killswitch.

Behavior changes

• behavior change: Transaction::set_name() names only the transaction; its requests keep their own names. Use set_name_for_transaction_and_requests() for the 0.18 behavior. See Naming transactions.
• behavior change: --scenarios matches machine names exactly, where 0.18 matched any part of the name; use * as a wildcard, as in --scenarios "anon*". See Limiting scenarios.
• behavior change: HTTPS uses rustls in place of the system’s native TLS library. Certificates are still checked by the operating system’s verifier, so a CA the system trusts is trusted, and --accept-invalid-certs skips the check in every build. See TLS.
• behavior change: an option value that begins with a hyphen goes after =, as in --goose-log=-run.log. Given as its own argument it is read as options, so --goose-log -run.log reads as --goose-log and -r un.log, and fails because un.log is not a number. When the command line itself does not parse, as with --goose-log -x.log, the error ends with a tip to use =. A negative number is still read as a value: --timeout -5 reaches the timeout check and is refused there, and --users -1 is refused with a tip that --users takes no negative number. An output option followed by another option, as in --goose-log --quiet, is given without a path and writes goose.log into the run’s folder. See Output files.
• behavior change: a report or log file whose name ends in .gz is written gzipped. See Compression.
• behavior change: --report-file reports are written even with --no-print-metrics. See Output files.
• behavior change: -h prints a short summary and --help the full reference, both to stdout. See Run-time options.
• behavior change: --run-time 0, --increase-time 0, --decrease-time 0 and --throttle-requests 0 undo the matching GooseDefault, and an empty log path, as in --request-log "", turns off a log a GooseDefault sets; GooseDefault::Iterations and GooseDefault::NoGranularData now take effect. See Defaults.
• behavior change: values that started no users or broke Goose are refused before the load test starts: a test plan with no users, a time span too large to hold, an increase or decrease rate below one user a day, a rate or --timeout that is not a finite number, and a --timeout that rounds to less than 1 ms, including a negative one. A fractional --timeout is rounded to the nearest millisecond, so 0.0005 runs as 1 ms and anything below it is refused. See Test plan and Run-time options.
• behavior change: a time span, as given to --run-time, --increase-time, --decrease-time, --threshold-abort-delay, a test plan step or a Controller command, is only hours, minutes and seconds written as h, m and s, as in 1h30m or 45s, in either case. 0.18 read 15mins, 5hours and 2h3min by their leading part, as 15 minutes, 5 hours and 2 hours 3 minutes; 0.19 refuses them, so write 15m, 5h and 2h3m. See Run-time options.
• behavior change: times under 10 ms are shown to the hundredth of a millisecond, and percentiles are never more than 1% off, so figures differ from the whole milliseconds 0.18 printed. See Response times.
• behavior change: the JSON report’s timing data holds times_us in place of times, its averages are means of the microseconds, it includes the test plan history, and each transaction’s transaction_name is an object such as {"TransactionOnly":"login"}, where 0.18 wrote a string. See JSON report.
• behavior change: the CSV request log ends with a response_time_us column, the scenario log with run_time_us, and the transaction log with run_time_us and then error; the JSON, raw and pretty formats add response_time_fraction_us or run_time_fraction_us. In JSON logs the keys follow the order of the fields instead of being sorted, transaction_name is an object such as {"TransactionOnly":"login"}, where 0.18 wrote a string (the error log’s new transaction error entries write it as a string); the CSV request log’s transaction_name column is empty unless the name was set with set_name_for_transaction_and_requests(); and the request, debug and error logs write transaction_index as a number, such as 0, where 0.18 wrote the string "0". See Logging and Request log.
• behavior change: elapsed in the request, error, transaction and scenario logs counts milliseconds since the load test started, where 0.18 counted from when each user was built; GooseUser.started is likewise the time the load test started, the same for every user, and the HTML report’s active users graph shows the increase ramp. See Logging, Request log and Users.
• behavior change: GooseRawRequest.headers, as read through goose.request.raw.headers or a TransactionError::RequestFailed, is empty unless the request log, debug log or error log is enabled. See Request log.
• behavior change: Controller users takes 1 to 100000, and on a running load test keeps its run time and ramp down; runtime changes a running users ramp; a value that can’t be used is answered with what it must be; config-json (and the WebSocket Controller’s config) shows an unset option as null and has no help key, and telnet config shows None for an unset option and Some(...) around a set one. See Controller commands.
• behavior change: the telnet Controller’s metrics-json and the WebSocket Controller’s metrics replies hold times_us in place of times and write each transaction’s transaction_name as an object, as the JSON report does, and a WebSocket message over 131,072 bytes closes the connection. See WebSocket Controller.
• behavior change: the killswitch keeps the first reason it is given, and is cleared when a run starts. See Killswitch.
• behavior change: users start and stop on time at any rate. 0.18 rounded the time between two users up to the next half second when it was over 500 ms, so --increase-rate 1.5 started 1 user a second and a test plan step of 500 users in 5 minutes took 8 minutes 20 seconds. In 0.19 --increase-rate 1.5 starts a user every 667 ms, and that step takes 5 minutes. This applies to --increase-rate, --decrease-rate, test plan steps and users changed by a Controller. See Specifying the increase rate.
• behavior change: GooseScheduler::Random shuffles transactions. 0.18 ran them in Serial order. 0.19 shuffles each scenario’s whole list once, so every user of a scenario runs the same random order; sequenced transactions are shuffled only within their sequence, and on_start and on_stop transactions run as before. See Random Scheduler.
• behavior change: a transaction’s error is recorded. Each line of the transaction log, in every format, ends with an error field, empty for a transaction that succeeded. The error log gets an entry for each transaction error, and its CSV header gains the columns scenario_index, scenario_name, transaction_index, transaction_name and run_time after error; a request error row leaves them empty. The console summary and the HTML, Markdown, PDF and JSON reports add a Transaction Errors table when there are any, which --no-error-summary leaves out. See Transaction log and Error log.
• behavior change: the JSON report keeps each request’s times by status code in status_code_timings, under raw_metrics.requests, and holds transaction errors in transaction_errors. Its raw_request_metrics rows are each request and the Aggregated row. See JSON report.
• behavior change: with --co-mitigation, the Aggregated # reqs is the “Actual requests” plus the “Synthetic requests” of the coordinated omission summary, and those counts start again when the metrics are reset after the ramp up. See Coordinated omission metrics.
• behavior change: the errors and transaction errors tables start again when the metrics are reset after the ramp up, as the other tables do, where 0.18 kept the ramp up’s errors in them. --no-reset-metrics keeps them, and the error log still records every error. See Metrics.
• behavior change: a scenario counts every user that ran it in the measured time, including users that had not completed an iteration, and the HTML, Markdown and JSON reports’ Aggregated scenario Iterations is all runs divided by all users, as on the console, where 0.18’s reports added up each scenario’s iterations. See Scenarios.
• behavior change: an average with no times to average, such as a scenario no user ran, is 0, where it was NaN (null in the JSON report). See Metrics.
• behavior change: --scenarios accepts _, so name_1 selects a second scenario registered as name, and a pattern that matches no scenario logs a warning. See Limiting scenarios.
• behavior change: a telnet or WebSocket Controller that can’t listen on its port logs an error, and the load test runs without it; --no-autostart is then refused when no Controller listens and dashboard control is off, as nothing could start the run. See Controlling a running load test and Printer-friendly HTML report example.
• behavior change: a load test that a Controller starts again after it stopped counts its requests from zero. See Controlling a running load test.
• behavior change: the first column of the Markdown report’s scenario table is headed Scenario, where 0.18 headed it Transaction. See Markdown report.
• behavior change: --telnet-port 0 and --websocket-port 0 are refused, where 0.18 read them as the default ports 5116 and 5117. Leave the option out for the default. See Controlling a running load test.
• behavior change: the WebSocket Controller is off by default, as it takes no authentication and any web page a browser opens could reach it. A load test that used it adds --websocket or GooseDefault::WebSocket; --no-websocket and GooseDefault::NoWebSocket still run, with a warning, and are refused with --websocket. --no-autostart --no-telnet now needs --websocket or --dashboard-control. See WebSocket Controller.
• behavior change: the telnet and WebSocket Controllers listen on 127.0.0.1 by default, where 0.18 listened on 0.0.0.0, as neither has authentication. A load test controlled over telnet or WebSocket from another machine, or from outside its container, now needs --telnet-host 0.0.0.0 or --websocket-host 0.0.0.0 (or GooseDefault::TelnetHost or GooseDefault::WebSocketHost), or an ssh tunnel to 127.0.0.1:5116; a Controller listening on any address that is not loopback prints a warning at startup. See Controlling a running load test.
• behavior change: a Controller’s config and config-json show a dashboard auth token that is set as (set), never the token, as does {:?} of a GooseConfiguration. See Controller commands.