[DOCS] Recommend Metricbeat for 7.x (elastic#49758)

docs/reference/monitoring/collecting-monitoring-data.asciidoc

@@ -3,44 +3,56 @@
 [[collecting-monitoring-data]]
 == Collecting monitoring data
 
-If you enable the Elastic {monitor-features} in your cluster, you can 
-optionally collect metrics about {es}. By default, monitoring is enabled but 
-data collection is disabled. 
+[IMPORTANT]
+=========================
+{metricbeat} is the recommended method for collecting and shipping monitoring
+data to a monitoring cluster.
 
-This method involves sending the metrics to the monitoring cluster by using 
-exporters. For an alternative method, see <<configuring-metricbeat>>.
+If you have previously configured internal collection, you should migrate to
+using {metricbeat} collection. Use either {metricbeat} collection or
+internal collection; do not use both.
 
-Advanced monitoring settings enable you to control how frequently data is 
-collected, configure timeouts, and set the retention period for locally-stored 
-monitoring indices. You can also adjust how monitoring data is displayed. 
+Learn more about <<configuring-metricbeat>>.
+=========================
 
-To learn about monitoring in general, see <<monitor-elasticsearch-cluster>>. 
+If you enable the Elastic {monitor-features} in your cluster, you can
+optionally collect metrics about {es}. By default, monitoring is enabled but
+data collection is disabled.
+
+This method involves sending the metrics to the monitoring cluster by using
+exporters. For the recommended method, see <<configuring-metricbeat>>.
+
+Advanced monitoring settings enable you to control how frequently data is
+collected, configure timeouts, and set the retention period for locally-stored
+monitoring indices. You can also adjust how monitoring data is displayed.
+
+To learn about monitoring in general, see <<monitor-elasticsearch-cluster>>.
 
 . Configure your cluster to collect monitoring data:
 
-.. Verify that the `xpack.monitoring.enabled` setting is `true`, which is its 
-default value, on each node in the cluster. For more information, see 
-<<monitoring-settings>>. 
+.. Verify that the `xpack.monitoring.enabled` setting is `true`, which is its
+default value, on each node in the cluster. For more information, see
+<<monitoring-settings>>.
 
-.. Verify that the `xpack.monitoring.elasticsearch.collection.enabled` setting 
-is `true`, which is its default value, on each node in the cluster. 
+.. Verify that the `xpack.monitoring.elasticsearch.collection.enabled` setting
+is `true`, which is its default value, on each node in the cluster.
 +
 --
-NOTE: You can specify this setting in either the `elasticsearch.yml` on each 
-node or across the cluster as a dynamic cluster setting. If {es} 
-{security-features} are enabled, you must have `monitor` cluster privileges to 
+NOTE: You can specify this setting in either the `elasticsearch.yml` on each
+node or across the cluster as a dynamic cluster setting. If {es}
+{security-features} are enabled, you must have `monitor` cluster privileges to
 view the cluster settings and `manage` cluster privileges to change them.
 
 For more information, see <<monitoring-settings>> and <<cluster-update-settings>>.
 --
 
 .. Set the `xpack.monitoring.collection.enabled` setting to `true` on each
-node in the cluster. By default, it is is disabled (`false`). 
-+ 
+node in the cluster. By default, it is is disabled (`false`).
++
 --
-NOTE: You can specify this setting in either the `elasticsearch.yml` on each 
-node or across the cluster as a dynamic cluster setting. If {es} 
-{security-features} are enabled, you must have `monitor` cluster privileges to 
+NOTE: You can specify this setting in either the `elasticsearch.yml` on each
+node or across the cluster as a dynamic cluster setting. If {es}
+{security-features} are enabled, you must have `monitor` cluster privileges to
 view the cluster settings and `manage` cluster privileges to change them.
 
 For example, use the following APIs to review and change this setting:
@@ -57,21 +69,21 @@ PUT _cluster/settings
 }
 ----------------------------------
 
-Alternatively, you can enable this setting in {kib}. In the side navigation, 
-click *Monitoring*. If data collection is disabled, you are prompted to turn it 
-on. 
+Alternatively, you can enable this setting in {kib}. In the side navigation,
+click *Monitoring*. If data collection is disabled, you are prompted to turn it
+on.
 
-For more 
+For more
 information, see <<monitoring-settings>> and <<cluster-update-settings>>.
 --
 
-.. Optional: Specify which indices you want to monitor. 
+.. Optional: Specify which indices you want to monitor.
 +
 --
 By default, the monitoring agent collects data from all {es} indices.
 To collect data from particular indices, configure the
-`xpack.monitoring.collection.indices` setting. You can specify multiple indices 
-as a comma-separated list or use an index pattern to match multiple indices. For 
+`xpack.monitoring.collection.indices` setting. You can specify multiple indices
+as a comma-separated list or use an index pattern to match multiple indices. For
 example:
 
 [source,yaml]
@@ -80,36 +92,36 @@ xpack.monitoring.collection.indices: logstash-*, index1, test2
 ----------------------------------
 
 You can prepend `-` to explicitly exclude index names or
-patterns. For example, to include all indices that start with `test` except 
+patterns. For example, to include all indices that start with `test` except
 `test3`, you could specify `test*,-test3`. To include system indices such as
 .security and .kibana, add `.*` to the list of included names.
 For example `.*,test*,-test3`
 --
 
-.. Optional: Specify how often to collect monitoring data. The default value for 
-the `xpack.monitoring.collection.interval` setting 10 seconds. See 
+.. Optional: Specify how often to collect monitoring data. The default value for
+the `xpack.monitoring.collection.interval` setting 10 seconds. See
 <<monitoring-settings>>.
 
-. Identify where to store monitoring data. 
+. Identify where to store monitoring data.
 +
 --
-By default, the data is stored on the same cluster by using a 
-<<local-exporter,`local` exporter>>. Alternatively, you can use an <<http-exporter,`http` exporter>> to send data to 
-a separate _monitoring cluster_. 
+By default, the data is stored on the same cluster by using a
+<<local-exporter,`local` exporter>>. Alternatively, you can use an <<http-exporter,`http` exporter>> to send data to
+a separate _monitoring cluster_.
 
 IMPORTANT: The {es} {monitor-features} use ingest pipelines, therefore the
-cluster that stores the monitoring data must have at least one 
-<<ingest,ingest node>>. 
+cluster that stores the monitoring data must have at least one
+<<ingest,ingest node>>.
 
-For more information about typical monitoring architectures, 
+For more information about typical monitoring architectures,
 see <<how-monitoring-works>>.
 --
 
-. If you choose to use an `http` exporter: 
+. If you choose to use an `http` exporter:
 
-.. On the cluster that you want to monitor (often called the _production cluster_), 
-configure each node to send metrics to your monitoring cluster. Configure an 
-HTTP exporter in the `xpack.monitoring.exporters` settings in the 
+.. On the cluster that you want to monitor (often called the _production cluster_),
+configure each node to send metrics to your monitoring cluster. Configure an
+HTTP exporter in the `xpack.monitoring.exporters` settings in the
 `elasticsearch.yml` file. For example:
 +
 --
@@ -118,19 +130,19 @@ HTTP exporter in the `xpack.monitoring.exporters` settings in the
 xpack.monitoring.exporters:
   id1:
     type: http
-    host: ["http://es-mon-1:9200", "http://es-mon2:9200"] 
+    host: ["http://es-mon-1:9200", "http://es-mon2:9200"]
 --------------------------------------------------
 --
 
-.. If the Elastic {security-features} are enabled on the monitoring cluster, you 
+.. If the Elastic {security-features} are enabled on the monitoring cluster, you
 must provide appropriate credentials when data is shipped to the monitoring cluster:
 
-... Create a user on the monitoring cluster that has the 
-<<built-in-roles,`remote_monitoring_agent` built-in role>>. 
-Alternatively, use the 
+... Create a user on the monitoring cluster that has the
+<<built-in-roles,`remote_monitoring_agent` built-in role>>.
+Alternatively, use the
 <<built-in-users,`remote_monitoring_user` built-in user>>.
 
-... Add the user ID and password settings to the HTTP exporter settings in the 
+... Add the user ID and password settings to the HTTP exporter settings in the
 `elasticsearch.yml` file on each node. +
 +
 --
@@ -141,19 +153,19 @@ For example:
 xpack.monitoring.exporters:
   id1:
     type: http
-    host: ["http://es-mon-1:9200", "http://es-mon2:9200"] 
-    auth.username: remote_monitoring_user 
+    host: ["http://es-mon-1:9200", "http://es-mon2:9200"]
+    auth.username: remote_monitoring_user
     auth.password: YOUR_PASSWORD
 --------------------------------------------------
 --
 
-.. If you configured the monitoring cluster to use 
-<<configuring-tls,encrypted communications>>, you must use the HTTPS protocol in 
-the `host` setting. You must also specify the trusted CA certificates that will 
-be used to verify the identity of the nodes in the monitoring cluster. 
+.. If you configured the monitoring cluster to use
+<<configuring-tls,encrypted communications>>, you must use the HTTPS protocol in
+the `host` setting. You must also specify the trusted CA certificates that will
+be used to verify the identity of the nodes in the monitoring cluster.
 
-*** To add a CA certificate to an {es} node's trusted certificates, you can 
-specify the location of the PEM encoded certificate with the 
+*** To add a CA certificate to an {es} node's trusted certificates, you can
+specify the location of the PEM encoded certificate with the
 `certificate_authorities` setting. For example:
 +
 --
@@ -162,7 +174,7 @@ specify the location of the PEM encoded certificate with the
 xpack.monitoring.exporters:
   id1:
     type: http
-    host: ["https://es-mon1:9200", "https://es-mon2:9200"] 
+    host: ["https://es-mon1:9200", "https://es-mon2:9200"]
     auth:
       username: remote_monitoring_user
       password: YOUR_PASSWORD
@@ -190,12 +202,12 @@ xpack.monitoring.exporters:
 --------------------------------------------------
 --
 
-. Configure your cluster to route monitoring data from sources such as {kib}, 
+. Configure your cluster to route monitoring data from sources such as {kib},
 Beats, and {ls} to the monitoring cluster. For information about configuring
 each product to collect and send monitoring data, see <<monitor-elasticsearch-cluster>>.
 
-. If you updated settings in the `elasticsearch.yml` files on your production 
-cluster, restart {es}. See <<stopping-elasticsearch>> and <<starting-elasticsearch>>. 
+. If you updated settings in the `elasticsearch.yml` files on your production
+cluster, restart {es}. See <<stopping-elasticsearch>> and <<starting-elasticsearch>>.
 +
 --
 TIP: You may want to temporarily {ref}/modules-cluster.html[disable shard
@@ -204,7 +216,7 @@ reallocation during the install process.
 
 --
 
-. Optional: 
-<<config-monitoring-indices,Configure the indices that store the monitoring data>>. 
+. Optional:
+<<config-monitoring-indices,Configure the indices that store the monitoring data>>.
 
-. {kibana-ref}/monitoring-data.html[View the monitoring data in {kib}]. 
+. {kibana-ref}/monitoring-data.html[View the monitoring data in {kib}].

docs/reference/monitoring/collectors.asciidoc

@@ -3,6 +3,18 @@
 [[es-monitoring-collectors]]
 == Collectors
 
+[IMPORTANT]
+=========================
+{metricbeat} is the recommended method for collecting and shipping monitoring
+data to a monitoring cluster.
+
+If you have previously configured internal collection, you should migrate to
+using {metricbeat} collection. Use either {metricbeat} collection or
+internal collection; do not use both.
+
+Learn more about <<configuring-metricbeat>>.
+=========================
+
 Collectors, as their name implies, collect things. Each collector runs once for
 each collection interval to obtain data from the public APIs in {es} and {xpack}
 that it chooses to monitor. When the data collection is finished, the data is
@@ -12,9 +24,9 @@ runs once per collection interval.
 
 There is only one collector per data type gathered. In other words, for any
 monitoring document that is created, it comes from a single collector rather
-than being merged from multiple collectors. {monitoring} for {es} currently has
-a few collectors because the goal is to minimize overlap between them for
-optimal performance.
+than being merged from multiple collectors. The {es} {monitor-features}
+currently have a few collectors because the goal is to minimize overlap between
+them for optimal performance.
 
 Each collector can create zero or more monitoring documents. For example,
 the `index_stats` collector collects all index statistics at the same time to
@@ -70,7 +82,7 @@ node to be able to perform the collection, the master node must have
 | Node Stats      | `node_stats`
 | Gathers details about the running node, such as memory utilization and CPU
 usage (for example, `GET /_nodes/_local/stats`). This runs on _every_ node with
-{monitoring} enabled. One common failure results in the timeout of the node
+{monitor-features} enabled. One common failure results in the timeout of the node
 stats request due to too many segment files. As a result, the collector spends
 too much time waiting for the file system stats to be calculated until it
 finally times out. A single `node_stats` document is created per collection.
@@ -79,19 +91,19 @@ with each other, but not with the monitoring cluster (for example, intermittent
 network issues or memory pressure).
 |=======================
 
-{monitoring} uses a single threaded scheduler to run the collection of {es} 
-monitoring data by all of the appropriate collectors on each node. This 
-scheduler is managed locally by each node and its interval is controlled by 
-specifying the `xpack.monitoring.collection.interval`, which defaults to 10 
-seconds (`10s`), at either the node or cluster level.
+The {es} {monitor-features} use a single threaded scheduler to run the
+collection of {es} monitoring data by all of the appropriate collectors on each
+node. This scheduler is managed locally by each node and its interval is
+controlled by specifying the `xpack.monitoring.collection.interval`, which
+defaults to 10 seconds (`10s`), at either the node or cluster level.
 
 Fundamentally, each collector works on the same principle. Per collection
-interval, each collector is checked to see whether it should run and then the 
-appropriate collectors run. The failure of an individual collector does not 
+interval, each collector is checked to see whether it should run and then the
+appropriate collectors run. The failure of an individual collector does not
 impact any other collector.
 
 Once collection has completed, all of the monitoring data is passed to the
-exporters to route the monitoring data to the monitoring clusters. 
+exporters to route the monitoring data to the monitoring clusters.
 
 If gaps exist in the monitoring charts in {kib}, it is typically because either
 a collector failed or the monitoring cluster did not receive the data (for
@@ -112,7 +124,7 @@ For more information about the configuration options for the collectors, see
 [[es-monitoring-stack]]
 ==== Collecting data from across the Elastic Stack
 
-{monitoring} in {es} also receives monitoring data from other parts of the
+{es} {monitor-features} also receive monitoring data from other parts of the
 Elastic Stack. In this way, it serves as an unscheduled monitoring data
 collector for the stack.
 
@@ -125,7 +137,7 @@ Once data is received, it is forwarded to the exporters
 to be routed to the monitoring cluster like all monitoring data.
 
 WARNING: Because this stack-level "collector" lives outside of the collection
-interval of {monitoring} for {es}, it is not impacted by the
+interval of {es} {monitor-features}, it is not impacted by the
 `xpack.monitoring.collection.interval` setting. Therefore, data is passed to the
 exporters whenever it is received. This behavior can result in indices for {kib},
 Logstash, or Beats being created somewhat unexpectedly.