Minor changes on constant-arrival-rate docs

[joanlopez]

What?

It slightly modifies constant-arrival-rate executor docs page, to make it a bit more clear and correct a typo.

Checklist

Please fill in this template:

• I have used a meaningful title for the PR.
• I have described the changes I've made in the "What?" section above.
• I have performed a self-review of my changes.
• I have run the make docs command locally and verified that the changes look good.

Select one of these and delete the others:

If updating the documentation for the most recent release of k6:

• I have made my changes in the docs/sources/next folder of the documentation.
• I have reflected my changes in the docs/sources/v{most_recent_release} folder of the documentation.
• I have reflected my changes in the relevant (e.g. when correcting a documentation error) folders of the previous k6 versions of the documentation.

Related PR(s)/Issue(s)

[joanlopez]

It kinda looks like a typo (because the script above has preAllocatedVUs: 50), but seems to correspond to the image (see here), so I'm wondering if we should update the image accordingly 🤔

[mstoykov]

I think this example got a bit mangled (probably by accident, or due to a misundersanding of the parameters) when some language was updated.

See 7943760 where this was last changed (this was way more difficult to find due to all the moves around in the last few months ... long live -G ).

In this case the example used to ... and still should probably start with less VUs then it needs to hit the arrival-rate. THis is mostly to showcase that it can add more VUs up to the maximum.

I am not certain we have many examples of this to begin with so removing those doesn't seem like a good idea.

[joanlopez]

I'm not sure if I fully get you. I don't suggest to remove it, just to make it sure the explanation matches the script.
I'm also fine with setting preAllocatedVUs equals to 2. Or does preAllocatedVUs serve as a maximum amount and k6 starts from zero to whatever that's enough to satisfy the desired rate? 🤔

[mstoykov]

preAllocatedVUs is what it starts at - the amount it has preallocated.

And then there is a maximum settings fo maxVUs that is equal to the preallocated ones if missing.

The commit I linked removes the max and uses only the preallocated one.

Whcih means that

1. the second sentecne of 'For this test, this ended up as 17 VUs." meanss nothing - k6 started with 50 and ended with 50, instead of starting with 2 and going up to 17.
2. Doesn't showcase this behaviour of k6 allocating more VUs if hte max hasn't been hit and needs them.

[joanlopez]

k6 started with 50 and ended with 50 but the reader cannot guess that from the test definition, right? I guess it really depends on how long each iteration takes to execute, doesn't it?

instead of starting with 2 and going up to 17, but that's what the image displays, so I guess we'll need to re-generate it, right?

In any case, what would you suggest as fix for this? I'm happy to correct this example and add another one, if it does worth it.

[mstoykov]

but the reader cannot guess that from the test definition

No - the definition says k6 will preallocate 50 Vus and there is no otehr maximum - so it will always will be with 50.

but that's what the image displays, so I guess we'll need to re-generate it, right?

I would argue that we should edit the script.

In any case, what would you suggest as fix for this? I'm happy to correct this example and add another one, if it does worth it.

My suggestion is to revert the example to start with 2 preallocatedVus and have a maximum of 50 (or w/e above 17). Touch the remaining of the text.

This keeps the example useful - showcasing that k6 can allocate Vus up to the maximum and how that looks. Instead of the current example - which doesn't showcase that.

The whole edit in the linked commit (on this example specifically) seems questionable. As it changed what the example is about from an example of how preallocated and max VUs work and how that looks, to just showcasing a "happy path" example of constant-arrival-rate and having some comments that are not illustrated IMO.

• Exactly 900 iterations are started in total, 30s * 30 iters/s.

This line is also not true - or at least wasn't in the original example as k6 will not have enough VUs to hit that. So it will be some lower number.

[heitortsergent]

Another issue or PR, I can't remember right now, had the same confusion around this script and the image.

But your explanation makes a lot of sense @mstoykov (and thanks for digging out the last changes). So it seems like we need to:

• Update the script to have the following lines:

...
      // Pre-allocate 2 VUs before starting the test
      preAllocatedVUs: 2,

      // Spin up a maximum of 50 VUs to sustain the defined
      // constant arrival rate.
      maxVUs: 50,

• Change the paragraph after "Example" to:

  "This example schedules a constant rate of 30 iterations per second for 30 seconds.
  It pre-allocates 2 VUs, and allows k6 to dynamically schedule up to 50 VUs as needed."

• Change this line back to mention maxVUs:

  "Having started with 2 VUs (as specified by the preAllocatedVUs option), k6 automatically adjusts the number of VUs to achieve the desired rate, up to the maxVUs. For this test, this ended up as 17 VUs."

• Remove the last list item, "Exactly 900 iterations are started in total, 30s * 30 iters/s.".

[mstoykov]

Sorry for the slow reply :(

Yes I think all of this will be great @heitortsergent

[joanlopez]

Thank you both @mstoykov, @heitortsergent! 🙌🏻 That makes lot of sense to me!
So, I have updated the changes accordingly.