Browse Source

Recommend cluster scope for Metricbeat (#70865)

Today we mention Metricbeat's `scope` parameter but offer no guidance
about how it should be used. This commit adds guidance to use `scope:
cluster`, especially on clusters with dedicated master-eligible nodes.
David Turner 4 years ago
parent
commit
f3792169b8
1 changed files with 18 additions and 5 deletions
  1. 18 5
      docs/reference/monitoring/configuring-metricbeat.asciidoc

+ 18 - 5
docs/reference/monitoring/configuring-metricbeat.asciidoc

@@ -42,8 +42,18 @@ view the cluster settings and `manage` cluster privileges to change them.
 For more information, see <<monitoring-settings>> and <<cluster-update-settings>>.
 --
 
-. {metricbeat-ref}/metricbeat-installation-configuration.html[Install {metricbeat}] on each
-{es} node in the production cluster. Failure to install on each node may result in incomplete or missing results.
+. {metricbeat-ref}/metricbeat-installation-configuration.html[Install
+{metricbeat}]. Ideally install a single {metricbeat} instance configured with
+`scope: cluster` and configure `hosts` to point to an endpoint (e.g. a
+load-balancing proxy) which directs requests to the master-ineligible nodes in
+the cluster. If this is not possible then install one {metricbeat} instance for
+each {es} node in the production cluster and use the default `scope: node`.
+When {metricbeat} is monitoring {es} with `scope: node` then you must install a
+{metricbeat} instance for each {es} node. If you don't, some metrics will not
+be collected. {metricbeat} with `scope: node` collects most of the metrics from
+the elected master of the cluster, so you must scale up all your
+master-eligible nodes to account for this extra load and you should not use
+this mode if you have dedicated master nodes.
 
 . Enable the {es} module in {metricbeat} on each {es} node.
 +
@@ -86,9 +96,12 @@ update the `hosts` setting. If you configured {es} to use encrypted
 communications, you must access it via HTTPS. For example, use a `hosts` setting
 like `https://localhost:9200`.
 <2> By default, `scope` is set to `node` and each entry in the `hosts` list
-indicates a distinct node in an {es} cluster. If you set `scope` to `cluster`,
-each entry in the `hosts` list indicates a single endpoint for a distinct {es}
-cluster (for example, a load-balancing proxy fronting the cluster).
+indicates a distinct node in an {es} cluster. If you set `scope` to `cluster`
+then each entry in the `hosts` list indicates a single endpoint for a distinct
+{es} cluster (for example, a load-balancing proxy fronting the cluster). You
+should use `scope: cluster` if the cluster has dedicated master nodes, and
+configure the endpoint in the `hosts` list not to direct requests to the
+dedicated master nodes.
 
 If Elastic {security-features} are enabled, you must also provide a user ID
 and password so that {metricbeat} can collect metrics successfully: