elasticsearch/docs/reference/monitoring/configuring-monitoring.asciidoc

[role="xpack"]
[testenv="gold"]
[[configuring-monitoring]]
== Configuring monitoring in {es}
++++
<titleabbrev>Configuring monitoring</titleabbrev>
++++

If you enable the collection of monitoring data in your cluster, you can 
optionally collect metrics about {es}. By default, {monitoring} is enabled but 
data collection is disabled. 

The following method involves sending the metrics to the monitoring cluster by 
using exporters. For an alternative 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 
{stack-ov}/xpack-monitoring.html[Monitoring the {stack}]. 

. To collect monitoring data about your {es} cluster:

.. Verify that the `xpack.monitoring.enabled`, 
`xpack.monitoring.collection.enabled`, and 
`xpack.monitoring.elasticsearch.collection.enabled` settings are `true` on each
node in the  cluster. By default `xpack.monitoring.collection.enabled` is disabled
(`false`), and that overrides `xpack.monitoring.elasticsearch.collection.enabled`,
which defaults to being enabled (`true`). Both settings can be set dynamically
at runtime. For more information, see <<monitoring-settings>>.

.. 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 
example:

[source,yaml]
----------------------------------
xpack.monitoring.collection.indices: logstash-*, index1, test2
----------------------------------

You can prepend `+` or `-` to explicitly include or exclude index names or 
patterns. For example, to include all indices that start with `test` except 
`test3`, you could specify `+test*,-test3`.
--

.. Optional: Specify how often to collect monitoring data. The default value for 
the `xpack.monitoring.collection.interval` setting 10 seconds. See 
<<monitoring-settings>>.

. Optional: Configure your cluster to route monitoring data from sources such 
as {kib}, Beats, and Logstash to a monitoring cluster:

.. Verify that `xpack.monitoring.collection.enabled` settings are `true` on each 
node in the cluster. 

..  {stack-ov}/xpack-monitoring.html[Configure {monitoring} across the Elastic Stack].

. Identify where to store monitoring data. 
+
--
By default, {monitoring} uses a `local` exporter that indexes monitoring data 
on the same cluster. See <<es-monitoring-default-exporter>> and <<local-exporter>>. 

Alternatively, you can use an `http` exporter to send data to a separate 
monitoring cluster. See <<http-exporter>>. 

For more information about typical monitoring architectures, 
see {stack-ov}/how-monitoring-works.html[How Monitoring Works].
--

. If {security} is enabled and you are using an `http` exporter to send data to 
 a dedicated monitoring cluster: 

.. Create a user on the monitoring cluster that has the 
{stack-ov}/built-in-roles.html#built-in-roles-remote-monitoring-agent[`remote_monitoring_agent` built-in role]. 
For example, the following request creates a `remote_monitor` user that has the 
`remote_monitoring_agent` role:
+
--
[source, sh]
---------------------------------------------------------------
POST /_xpack/security/user/remote_monitor
{
  "password" : "changeme",
  "roles" : [ "remote_monitoring_agent"],
  "full_name" : "Internal Agent For Remote Monitoring"
}
---------------------------------------------------------------
// CONSOLE
// TEST[skip:needs-gold+-license]
--

.. On each node in the cluster that is being monitored, configure the `http` 
exporter to use the appropriate credentials when data is shipped to the 
monitoring cluster. 
+
--
If SSL/TLS is enabled on the monitoring cluster, you must use the HTTPS protocol 
in the `host` setting. You must also include the CA certificate in each node's 
trusted certificates in order to verify the identities of the nodes in the 
monitoring cluster. 

The following example specifies the location of the PEM encoded certificate with 
the `certificate_authorities` setting:

[source,yaml]
--------------------------------------------------
xpack.monitoring.exporters:
  id1:
    type: http
    host: ["https://es-mon1:9200", "https://es-mon2:9200"] 
    auth:
      username: remote_monitor <1>
      password: changeme
    ssl:
      certificate_authorities: [ "/path/to/ca.crt" ]
  id2:
    type: local
--------------------------------------------------
<1> The `username` and `password` parameters provide the user credentials.

Alternatively, you can configure trusted certificates using a truststore
(a Java Keystore file that contains the certificates):

[source,yaml]
--------------------------------------------------
xpack.monitoring.exporters:
  id1:
    type: http
    host: ["https://es-mon1:9200", "https://es-mon2:9200"]
    auth:
      username: remote_monitor
      password: changeme
    ssl:
      truststore.path: /path/to/file
      truststore.password: password
  id2:
    type: local
--------------------------------------------------
--

. If {security} is enabled and you want to visualize monitoring data in {kib}, 
you must create users that have access to the {kib} indices and permission to 
read from the monitoring indices.
+
--
You set up {monitoring} UI users on the cluster where the monitoring data is 
stored, that is to say the monitoring cluster. To grant all of the necessary permissions, assign users the
`monitoring_user` and `kibana_user` roles. For more information, see 
{stack-ov}/mapping-roles.html[Mapping users and groups to roles].
--

. Optional: 
<<config-monitoring-indices,Configure the indices that store the monitoring data>>. 

. {kibana-ref}/monitoring-data.html[View the monitoring data in {kib}]. 

include::configuring-metricbeat.asciidoc[]
include::indices.asciidoc[]
include::{es-repo-dir}/settings/monitoring-settings.asciidoc[]