[Docs] Clarify getting started exceptions when using Logstash

[cjcenizal]

The current "Getting started" docs provide guidance on loading the index template into Elasticsearch, but largely from the perspective of users who have configured Metricbeat to ship directly to ES.

When I ran through this tutorial, I was testing the full stack, with Metricbeat configured to ship to Logstash. The linked docs state:

If you accept the default configuration in the metricbeat.yml config file, Metricbeat loads the template automatically after successfully connecting to Elasticsearch.

When I read this, I saw the initial statement about "default configuration" and missed the nuance regarding "connecting to Elasticsearch" at the end. Because I was new to the stack, I assumed that because I hadn't changed much in the config file, I was still basically using the default config. Of course I was mistaken... 😄 The index template never loaded, so my dashboards were broken and I couldn't understand why.

I think we could resolve this problem by make the docs explicitly state something like this:

The recommended index template file for Metricbeat is installed by the Metricbeat packages. If your metricbeat.yml config file is configured to connect directly to Elasticsearch, then Metricbeat automatically loads the index template into Elasticsearch for you. If the template already exists, it’s not overwritten unless you configure Metricbeat to do so.
However, if you have metricbeat.yml configured to connect to something else, such as Logstash or Kafka, then you will need to manually setup the index template using the command line (see below).
Whichever path you take, you can verify the metricbeat index template has been set up by running GET _template/metricbeat* in Kibana's Dev Tools. You should see an index template with an index pattern that will match the indices you're ingesting.

And then on the Kibana dashboards step, it would be helpful to state something in an info box like this:

Not seeing data in the sample dashboards? If the dashboard panels are showing errors, then you may need to set up the metricbeat index template (link to previous step).

[cjcenizal]

CC @ruflin

[cjcenizal]

Upgrading requires re-setting up the index template to keep dashboards working

Additionally, in the beats upgrade docs we should clarify that users need to re-setup the index template in order for the sample dashboards to be updated with data that gets ingested after upgrading.

[cjcenizal]

Multi-node clusters are special exceptions

The "Getting started" docs also assume that the user is on a single-node cluster, since the index template defaults to setting number_of_shards to 1. We might want to point out that the user should either 1) update the config file with a higher number_of_shards value or 2) provide a command line flag to increase this number, if their cluster contains multiple nodes.

[dedemorton]

@alvarolobato This content is in libbeat so probably should not be labeled "Infrastructure".

[botelastic]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.