Document how VUs are scheduled post-v0.27.0

[imiric]

As indicated by this forum comment, people might have a wrong expectation of how VUs are scheduled and used by the new executors. Since this changed considerably in v0.27.0, we should explain this in more detail in the documentation.

Instead of this being another page filled with text, I think a few simple animations in the style of the current PixelPoint ones that show some examples of how this works in practice would be very helpful. Showing how VUs are initialized, retrieved from and returned to the global VU pool would be good to have for each executor, although seeing how VUs are reused between executors in multi-scenario tests might be more informative.

[ppcano]

We need drawings or sketches to design the animations.

[imiric]

@ppcano Agreed, I'll see if I can come up with something.

The idea is that there's a global pool of pre-initialized VUs from which each executor "borrows" the VUs it needs during the run. Some executors like the ramping-arrival-rate may initialize VUs during the run, which could affect execution, so that's important to represent as well.

I think there should be 3 "stages" in the animation: test startup and pre-initialization of global VUs, test execution showing VU "borrowing" per executor and how the exec function is executed in each VU, and test wind down where VUs are returned, and maybe reused again by another executor (depending if we're showing single or multi-scenario tests).

[imiric]

Here's a mockup of what I had in mind:

Pardon the lack of artistic skill 😅

Each stage in the animation could be a separate part of the whole, maybe showing higher-level concepts first and then zooming in to show details. It would be great if this was interactive too, so we could have examples for all executor types on display and the user could click on each executor to see how it works internally. Of course, these inner-workings will be communicated and we can iterate on the details.

[ppcano]

@imiric I thought about this issue again. Some thoughts:

1 - The user on the forum comment is asking how each iteration of the scenario could be independent to use a different auth token per iteration.

It looks like a common use case. Is there a way to achieve this?

2 - Regarding the mockup/animation. I think the animation alone will not explain well enough how VU allocation works.

I think we should have articles - hidden from the sidebar - for these advanced concepts, but linked from other articles.

I will talk with @majavojnoska and the design team about animations and illustrations.

[imiric]

Hey @ppcano, sorry about the late response.

1. I don't see how that's relevant to this issue, but I think Ned's reply explains it. In any case, the animation would help them visualize that VUs are not tied to a specific scenario, but when each scenario (or executor, rather) is "done" with a VU, which varies depending on the executor implementation, the executor will return the VU to the global pool so that it can be reused by other scenarios/executors.

2. True, agreed. We could even link directly to articles from the animation, or show short descriptions on hover, and things like that. I'm sure our talented designers will think of something neat ;)

[simskij]

I've done some attempts at this, but shelved it for the time being. Will pick it up again at some point.