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 to [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 design better tests 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,102 @@
+---
+title: VU allocation
+excerpt: How k6 allocates VUs in the open-model, arrival-rate executors
+---
+
+In arrival-rate executors, as long as k6 has VUs available, it starts iterations according to your target rate.
+The ability to set iteration rate comes with a bit more configuration complexity: you must pre-allocate a sufficient number of VUs.
+In other words, before the tests runs, you must both:
+- Configure load (as iteration per unit of time)
+- Ensure that you've scheduled enough VUs.
+
+Read on to learn about how k6 allocates VUs in the arrival-rate executors.
+
+## Pre-allocation in arrival-rate executors
+
+As [open-model](/using-k6/scenarios/about-scenarios/open-vs-closed/#open-model) scenarios, arrival-rate executors start iterations according to a configured rate.
+For example, you can configure arrival-rate executors to start 10 iterations each second, or minute, or hour.
+This behavior is opposed to the closed-model scenarios, in which VUs wait for one iteration to finish before starting another
+
+Each iteration need needs a VU to run it.
+Because k6 VUs are single threaded, like other JS runtimes, a VU can only run the event loop of a single iteration at a time.
+To ensure you have enough, you must pre-allocate a sufficient number.
+
+In your arrival-rate configuration, three properties determine the iteration rate:
+- `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 practice, determining the right number of iterations might take some trial and error,
+as the necessary VUs entirely depends on how quickly the SUT can process iterations.
+
+```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
+
+The necessary allocation depends on the iteration duration:
+Longer durations need more VUs.
+
+In a perfect world, you could estimate the number of pre-allocated VUs with this formula:
+
+```
+preAllocatedVUs = [median_iteration_duration * rate] + constant_for_variance
+```
+
+In the real world, if you know _exactly_ how long an iteration takes, you likely don't need to run a test.
+What's more, as the test goes on, iteration duration likely increases.
+If response times slow so much that k6 lacks the VUs to start iterations at the desired rate,
+the allocation might be insufficient and k6 will drop iterations.
+
+To determine your strategy, you can run tests locally and gradually add more pre-allocated VUs.
+As dropped iterations can also indicate that the system performance is degrading, this early experimentation can provide useful data on its own.
+
+## 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,40 @@
+---
+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 the number of unsent iterations 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 SUT performance is degrading and iterations are taking longer to finish.
+
+### SUT-related iteration drops
+
+At a certain point of high latency or longer iteration durations, k6 will no longer have free VUs to start iterations with at the configured rate.
+As a result, the executor will drop iterations.
+
+The reasons for these dropped iterations vary:
+- The SUT response has become so long that k6 starts dropping scheduled iterations 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.
+
+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).
+

src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios/01 Executors/05 constant-arrival-rate.md

@@ -15,6 +15,13 @@ useful for a more accurate representation of RPS, for example.
 
 See the [arrival rate](/using-k6/scenarios/arrival-rate) section for details.
 
+<Blockquote mod="Note" title="Iteration starts are spaced fractionally">
+
+Iterations **do not** start at exactly the same time.
+At a `rate` of `10` with a `timeUnit` of `1s`, each iteration starts about every tenth of a second (that is, each 100ms).
+
+</Blockquote>
+
 ## Options
 
 Besides the [common configuration options](/using-k6/scenarios#options),

src/data/markdown/translated-guides/en/02 Using k6/14 Scenarios/01 Executors/06 ramping-arrival-rate.md

@@ -11,6 +11,13 @@ k6 will attempt to dynamically change the number of VUs to achieve the configure
 
 See the [arrival rate](/using-k6/scenarios/arrival-rate) section for details.
 
+<Blockquote mod="Note" title="Iteration starts are spaced fractionally">
+
+Iterations **do not** start at exactly the same time.
+At a `rate` of `10` with a `timeUnit` of `1s`, each iteration starts about every tenth of a second (that is, each 100ms).
+
+</Blockquote>
+
 ## Options
 
 Besides the [common configuration options](/using-k6/scenarios#options),