808/about executors

src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios.md

@@ -56,12 +56,13 @@ export const options = {
 
 For each k6 scenario, the VU workload is scheduled by an _executor_.
 For example, executors configure:
+- How long the test runs
 - Whether VU traffic stays constant or changes
 - Whether to model traffic by iteration number or by VU arrival rate.
 
 Your scenario object must define the `executor` property with one of the predefined executors names.
 Along with the generic scenario options, each executor object has additional options specific to its workload.
-For the list of the executors, refer to the [Executor guide](/using-k6/scenarios/executors/).
+For the list of the executors, refer [Executors](/using-k6/scenarios/executors/).
 
 ## Scenario options {#options}
 

src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios/00 About scenarios.md

@@ -0,0 +1,18 @@
+---
+title: "About scenarios"
+excerpt: High-level explanations about how your executor configuration can change the test execution and test results
+---
+
+These topics explain the essential concepts of how scenarios and their executors work.
+
+Different scenario configurations can affect many different aspects of your system,
+including the generated load, utilized resources, and emitted metrics.
+If you know a bit about how scenarios work, you'll both design better tests for resources and goals, and interpret test results with more understanding.
+
+| On this page                                                                  | Read about                                                                                                                            |
+|-------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------|
+| [Open and closed models](/using-k6/scenarios/about-scenarios/open-vs-closed/) | Different ways k6 can schedule VUs, their affects on test results, and how k6 implements the open model in its arrival-rate executors |
+| [VU allocation](/using-k6/scenarios/about-scenarios/vu-allocation/)           | How k6 allocates VUs in arrival-rate executors                                                                                        |
+| [Dropped iterations](/using-k6/scenarios/about-scenarios/dropped-iterations/) | Possible reasons k6 might drop a scheduled iteration                                                                                  |
+| [Graceful Stop](/using-k6/scenarios/about-scenarios/graceful-stop)            | A configurable period to let iterations finish or ramp down after the test has reached it's scheduled duration                        |
+

src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios/04 Arrival Rate.md → src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios/00 About scenarios/00 Open-vs-closed.md

@@ -1,10 +1,11 @@
 ---
-title: 'Arrival rate'
-excerpt: 'In k6, we have implemented this open model with our two arrival rate executors: constant-arrival-rate and ramping-arrival-rate.'
+title: 'Open and closed models'
+slug: '/using-k6/scenarios/about-scenarios/open-vs-closed/'
+excerpt: 'k6 has two ways to schedule VUs, which can affect test results. k6 implements the open model in its arrival-rate executors.'
 ---
 
 Different k6 executors have different ways of scheduling VUs.
-Some executors use the _closed model_, while the arrival rate executors use the _open model_.
+Some executors use the _closed model_, while the arrival-rate executors use the _open model_.
 
 In short, in the closed model, VU iterations start only when the last iteration finishes.
 In the open model, on the other hand, VUs arrive independently of iteration completion.
@@ -83,7 +84,7 @@ To fix this problem of coordination, you can use an open model,
 which decouples the start of new VU iterations from the iteration duration.
 This reduces the influence of the target system's response time.
 
-![Arrival rate closed/open models](../images/Scenarios/arrival-rate-open-closed-model.png)
+![Arrival rate closed/open models](../../images/Scenarios/arrival-rate-open-closed-model.png)
 
 k6 implements the open model with two _arrival rate_ executors:
 [constant-arrival-rate](/using-k6/scenarios/executors/constant-arrival-rate) and [ramping-arrival-rate](/using-k6/scenarios/executors/ramping-arrival-rate):

src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios/00 About scenarios/02 VU allocation.md

@@ -0,0 +1,89 @@
+---
+title: VU allocation
+excerpt: How k6 allocates VUs in the open-model, arrival-rate executors
+---
+
+This document explains how k6 allocates VUs in the arrival-rate executors.
+
+In arrival-rate executors, three properties determine the iterations per second:
+-  `rate`  determines how many iterations k6 starts.
+- `timeUnit` determines how frequently it starts the number of iterations.
+- `preAllocatedVUs` sets the number of VUs to use to reach the target iterations per second.
+
+In short, while `rate` and `timeUnit` set the target iterations per second, **you must allocate enough VUs to reach this target.**
+By pre-allocating VUs, k6 can initialize the VUs necessary for the test before the test runs,
+which ensures that the CPU cost of allocation doesn't interfere with test execution.
+
+```javascript
+export const options = {
+  scenarios: {
+    constant_load: {
+      executor: "constant-arrival-rate",
+      preAllocatedVUs: 4,
+      rate: 8,
+      timeUnit: "1m",
+    },
+  },
+};
+```
+
+
+<Blockquote mod="attention" title="">
+
+In cloud tests, **both `preAllocatedVUs` and `maxVUs` count against your subscription.**
+
+When planning a test, consider doing a trial initialization on a local machine to ensure you're allocating VUs efficiently.
+
+</Blockquote>
+
+## How k6 uses allocated VUs
+
+Before an arrival-rate scenario starts, k6 first initializes the number of `preAllocatedVUs`.
+When the test runs,
+the number of available `preAllocatedVUs` determines how many iterations k6 can start.
+k6 tries to reach the target iterations per second, and one of two things can happen.
+
+| If the executor       | Then..                                                                                                                                 |
+|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------|
+| Has enough VUs        | the extra VUs are "idle," ready to be used when needed.                                                                                |
+| Has insufficient VUs. | k6 emits a [`dropped_iterations` metric](/using-k6/scenarios/about-scenarios/dropped-iterations) for each iteration that it can't run. |
+
+## Iteration duration affects the necessary allocation
+
+Imagine that you have a goal of 50 iterations per second.
+The executor `rate` is `50`, and the `timeUnit` is `1s`.
+
+How many `preAllocatedVUs` do you need?
+This depends on your iteration duration.
+If you could be sure iterations all had a duration of `1s`, then 50 pre-allocated VUs would be enough VUs&mdash;this is likely only in a perfect world.
+
+In the real world, iteration durations fluctuate with load and random statistical variance.
+You could _approximate_ the number of VUs you need by multiplying the desired rate by the expected median iteration duration (perhaps determined by an early test).
+
+```
+preAllocatedVUs = median iteration duration * rate
+```
+
+In real load tests, the median iteration duration might be quite hard to predict.
+And even if you knew the median value, the variance could be so high that some periods may happen where the number of pre-allocated VUs was insufficient anyway.
+You should probably add a number of extra iterations.
+The amount necessary for your case may require some experimentation.
+
+## You probably don't need `maxVUs`
+
+The arrival-rate executors also have a `maxVUs` property.
+If you set it, k6 runs in this sequence:
+1. Pre-allocate the `preAllocatedVUs`.
+1. Run the test, trying to reach the target iteration rate.
+1. If the target exceeds the available VUs, allocate another VU.
+1. If the target still exceeds available VUs, continue allocating VUs until reaching the number set by `maxVUs`.
+
+Though it seems convenient, you should avoid using `maxVUs` in most cases.
+Allocating VUs has CPU and memory costs, and allocating VUs as the test runs **can overload the load generator and skew results**.
+If you're running in k6 Cloud, the `maxVUs` will count against your subscription.
+In almost all cases, the best thing to do is to pre-allocate the number of VUs you need beforehand.
+
+Some of the times it might make sense to use `maxVUs` include:
+- To determine necessary allocation in first-time tests
+- To add a little "cushion" to the pre-allocated VUs that you expect the test needs
+- In huge, highly distributed tests, in which you need to carefully scale load generators as you increment VUs.

src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios/00 About scenarios/03 Dropped iterations.md

@@ -0,0 +1,41 @@
+---
+title: Dropped iterations
+excerpt: Explanations about how your scenario configuration or SUT performance can lead to dropped iterations
+---
+
+Sometimes, a scenario can't run the expected number of iterations.
+k6 tracks this number in a counter metric, `dropped iterations`.
+The number of dropped iterations can be valuable data when you debug executors or analyze results.
+
+Dropped iterations usually happen for one of two reasons:
+- The executor configuration is insufficient.
+- The SUT can't handle the configured VU arrival rate.
+
+### Configuration-related iteration drops
+
+Dropped iterations happen for different reasons in different types of executors.
+
+With `shared-iterations` and `per-vu-iterations`, iterations drop if the scenario reaches its `maxDuration` before all iterations finish.
+To mitigate this, you likely need to increase the value of the duration.
+
+With `constant-arrival-rate` and `ramping-arrival-rate`, iterations drop if there are no free VUs.
+**If it happens at the beginning of the test, you likely just need to allocate more VUs.**
+If this happens later in the test, the dropped iterations might happen because of the SUT.
+
+### SUT-related iteration drops
+
+If iterations drop later in the test run, your test SUT might have become slow to respond to requests, process iterations, or both.
+
+At a certain point of high latency or longer iteration durations, k6 can no longer send VUs at the configured rate. 
+There could be a variety of causes for these dropped iterations:
+- The SUT response has become so long that k6 starts dropping scheduled VUs from the queue.
+- The SUT iteration duration has become so long that k6 needs to schedule more VUs to reach the target arrival rate, exceeding the number of scheduled iterations.
+- Some network errors between the generator and the SUT have caused iterations to drop.
+
+As the causes vary, dropped iterations might mean different things.
+A few dropped iterations might indicate a quick network error.
+Many dropped iterations might indicate that your SUT has completely stopped responding.
+
+When you design your test, consider what an acceptable rate of dropped iterations is (the _error budget_).
+To assert that the SUT responds within this error budget, you can use the `dropped_iterations` metric in a [Threshold](/using-k6/thresholds).
+