Update stream documentation bringing explanation of some errors

[thiagoftsm]

Summary

Fixes #6946

We are having reports from users about "bugs" in Netdata stream, but while we were helping them we are are verifying that the majority of these errors are bad configuration, this PR has the goal to clarify for the user possible errors in the stream.

Component Name

Stream documentation

Additional Information

[squash-labs]

Manage this branch in Squash

Test this branch here: https://thiagoftsmstream-doc-7iejc.squash.io

[cosmix]

@joelhans please review and improve the text. There's several parts that could use some English-language love. Thanks!

[cosmix]

If you are going to use backticks for slave, you might as well use them for master too.

[thiagoftsm]

In the beginning I was writing backticks to call attention of the people for both master and slave, but when I began to review I saw that this was not a pattern, after this I began to remove, but I forgot this one. Thank you!

[cosmix]

Capitalize.

[thiagoftsm]

I fixed the error, thank you again!

[ilyam8]

I have a feeling that the correct solution is to make errors clear and descriptive. In that case we dont need to maintain page with errors explanations and keep it up to date. @thiagoftsm think about it. Just a suggestion.

[thiagoftsm]

Thank you @cosmix and @ilyam8 , I will work on this tomorrow again, I wanna bring more some more errors and I will try to improve the text, before @joelhans touches it on Monday.

[joelhans]

Some requests here and one question about the nature of the error.

[thiagoftsm]

Thank you very much @joelhans !
I brought all the changes you gave me for the documentation.

Best regards!

[amoss]

I've just worked through this myself to setup a streaming configuration for testing. It seems that there is something missing in the documentation, which is why so many people are struggling when they go through it for the first time. It could be improved with a howto / walkthrough for a minimal example at the top of the document.

Something like:

• 192.168.1.100 as a master
• 192.168.1.101 as the first slave
• 192.168.1.102 as the second slave.

It should show exactly what to type to achieve this setup, and not involve any decisions (i.e. pick all the options to be reasonable for a first-time setup).

Once a user is over the hurdle of getting it working for the first-time the rest of the document works well as reference material:

• Common problems.
• Different options and their effects.
• Ideas for what is possible with more complex setups.

There is currently a forward-reference in the text to the ephemeral nodes section as an example, but it is not simple enough to act as an initial guide and it does not drop down to a step-by-step level of detail showing exactly what to type.

[thiagoftsm]

Hi @amoss ,

It was good you write here about the fact our documentation is not clear in some subjects, because we are working to bring Netdata Learning and this is an important characteristic for we work there. @joelhans , please, pay attention in @amoss words for all the course.
We have the sections https://docs.netdata.cloud/streaming/#configuring-the-master and https://docs.netdata.cloud/streaming/#configuring-the-slaves that are responsible to teach everybody how to configure, they are not a how to and probably they are missing parts or they are not clear enough.
I agree that we are missing some images and here I won't put them, but check the list below to verify whether they can help you and our users:

Master:
1 - Firstly run the command uuidgen

uuidgen 
dfc307cc-9b7f-487d-86f5-349199f06004

2 - now it is time to edit your stream.conf:

/etc/netdata/edit-config stream.conf

3 - Finally set the following variables:

# -----------------------------------------------------------------------------
# 2. ON MASTER NETDATA - THE ONE THAT WILL BE RECEIVING METRICS
[dfc307cc-9b7f-487d-86f5-349199f06004]
    enabled = yes
    default history = 3600
    default memory = ram
    health enabled by default = auto
    multiple connections = allow

Now it is necessary to configure your Slave:
4 - We will execute the step 3 on your slave again:

/etc/netdata/edit-config stream.conf

5 - On Slave we work in a different section:

# -----------------------------------------------------------------------------
# 1. ON SLAVE NETDATA - THE ONE THAT WILL BE SENDING METRICS
[stream]
    enabled = yes
    destination = 192.168.1.100
    api key =dfc307cc-9b7f-487d-86f5-349199f06004

The steps for the next slaves are exactly the same.

Let us know whether this steps are helping, because they will help @joelhans and I move in front with documentation and Netdata learning.

[amoss]

Yes, this is good. I think it works well as a walk-through and clarifies what to do.

[thiagoftsm]

Yes, this is good. I think it works well as a walk-through and clarifies what to do.

Thank you for the feedback! :)
I will check with @joelhans whether this is a road to use at Netdata Learning or we can bring something for our official documentation too.

[cosmix]

Why is this still open? Is there anything more to do on this PR before it gets accepted?

[thiagoftsm]

Why is this still open? Is there anything more to do on this PR before it gets accepted?

We are missing reviews, there is not any necessity to add more info in this PR.

[cakrit]

@joelhans plz review again, it looks good from my side.