Document actor system

[pquentin]

You can see this live at https://github.com/pquentin/rally/blob/document-actor-system/docs/architecture/actor_system.md.

[inqueue]

Thank you for this. I left some minor suggestions.

[gbanasiak]

Many thanks! This helps in building the Rally mental map.

I went through PrepareBenchmark so far. A few remarks, a wish list for later mostly:

• For consistency, TrackPreparator should be renamed to TrackPreparationActor in the charts as that's the name of the class I think.
• It would be great to include 10k feet description of what each component is doing, e.g. 1) TrackPreparationActor loads a track and track plugins (custom extensions such as parameter sources and runners), gets a list of track processors (TrackProcessor interface) from TrackProcessorRegistry and stores them in a queue. Then it sends each processor for execution to TaskExecutionActor. 2) TackExecutionActor executes each processor in a background task and verifies its status periodically. Once task completes, it reports its readiness with WorkComplete. Not sure what level of details makes sense here - too much is just a repetition of code, too little forces us to go through the flow again if we revisit this after enough time.
• It would be nice to explain how individual components grow as the scale of the system increases, e.g. TrackPreparationActor set grows with the number of load driver hosts, while TaskExecutionActor set can grow with the number of cores declared per load driver.

[dliappis]

Another reason (the first one, IIRC) is that distributing Rally also provides an easy way to handle multiple target hosts and ensure that they all build/install/start the required ES version via the race subcommand (this is for example the mode used on the Hetzner nightly benchmarks).
Later on we got the dedicated/decoupled esrally build/install/start/stop subcommands (which we use e.g. with cloud based benchmarks) and these are decoupled from the actor system.

[pquentin]

The current formulation isn't correct then, however my understanding is that this is achievable without a full-fledged actor system, while we could easily end up re-implementing Thespian badly to support multiple load drivers.

[dliappis]

however my understanding is that this is achievable without a full-fledged actor system, while we could easily end up re-implementing Thespian badly to support multiple load drivers.

I mostly agree. I don't think the risk of supporting >1 load drivers without the actor system would necessarily result in re-implementing Thespian, but as always, the devil is in the details.

[gbanasiak]

I've changed the wording slightly in ac1aec8.

[pquentin]

I went through PrepareBenchmark so far. A few remarks, a wish list for later mostly:

I fixed TrackPreparationActor, would you like contributing your other fixes to this branch or in another pull request?

[gbanasiak]

@dliappis @inqueue I've adjusted description based on the previous discussion and also updated diagrams for StartBenchmark section while I was reviewing the code myself. I will continue with extra additions in this doc in other PRs, if needed. PTAL.

[dliappis]

This LGTM -- so great to see these internal aspects of Rally documented.

One thing I wanted to ask is how come this isn't living under the official docs e.g. in the Reference Documentation or Additional Information sections? (is it because Mermaid isn't available?)

[gbanasiak]

One thing I wanted to ask is how come this isn't living under the official docs e.g. in the Reference Documentation or Additional Information sections? (is it because Mermaid isn't available?)

It should be possible to use Mermaid with Sphinx but it would require additional package, see https://github.com/mgaitan/sphinxcontrib-mermaid. That's work in progress. If/when this matures we can include this in official documentation.