[Doc] better define the hosts selection policy

[andsel]

This commit update the description of the hosts setting

[karenzone]

Thanks for adding this info to explain how hosts selection work. It includes sentence that isn't quite clear to me. Perhaps we can reword or elaborate.

You are a good explainer. If you explain it to me, I can help with the right wording.

[karenzone]

Suggested change

	List of addresses lumberjack can send to. When the plugins needs to connect to the remote
	peer it randomly selects one of the hosts. The connection happens when the plugin is registered
	and when it detects a connection error.
	List of addresses lumberjack can send to. When the plugin needs to connect to the remote
	peer, it randomly selects one of the hosts. The connection happens when the plugin is registered
	and when it detects a connection error.

[karenzone]

"The connection happens when the plugin is registered
and when it detects a connection error."

This sentence seems counter intuitive. What is it about the connection error that makes the connection happen?

Maybe if one connection fails, it moves to another one?

[andsel]

Thanks @karen to look at this, I try to explain the logic flow. When the pipeline is created and the plugin registered it open a connection to one of the hosts. When the plugin is sending data and receives an IO error (due to network or host problems) is opens a freshly connection, bringing the new host from the hosts list. How the plugin selects the host to connect, is always in a random way.

[karenzone]

Gotcha! Great explanation.
Let's make it clear that we're covering two different scenarios--happy path and failure.

What about something like:

When the plugin is registered, it opens a connection to one of the hosts.
If the plugin detects a connection error, it selects a different host from the list and opens a new connection.

[andsel]

That's better, but we need to say that the selection from the host list is random, because the original point that generated this PR was "how the host is selected from the hosts list?".

Maybe something like:

When the plugin is registered, it opens a connection to one of the hosts.
If the plugin detects a connection error, it selects a different host from the list and opens a new connection.
The host is selected in randomly fashion.

[karenzone]

You've already got that info covered in Lines 64-65.

[andsel]

ahh ok, I thought your phrase was a complete replacement

[andsel]

@karenzone I've integrated your suggestion and bumped a new version to publish the documentation changes

[karenzone]

Nice doc enhancement. Thank you! 🎉
I left some very minor suggestions inline (adding a comma and a return) for your consideration. Otherwise, LGTM!

I trust your judgement and don't need to see it again, unless you want me to for some reason.

[karenzone]

Published as v3.1.9: https://rubygems.org/gems/logstash-output-lumberjack/versions/3.1.9