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

[role="xpack"]
[[monitoring-settings]]
=== Monitoring settings in {es}
++++
<titleabbrev>Monitoring settings</titleabbrev>
++++

// tag::monitoring-deprecation-notice[]
deprecated[7.16, "Using the {es} Monitoring plugin to collect and ship monitoring data is deprecated. {agent} and {metricbeat} are the recommended methods for collecting and shipping monitoring data to a monitoring cluster. If you previously configured legacy collection methods, you should migrate to using <<configuring-elastic-agent,{agent}>> or <<configuring-metricbeat,{metricbeat}>> collection methods."]
// end::monitoring-deprecation-notice[]

By default, {es} {monitor-features} are enabled but data collection is disabled.
To enable data collection, use the `xpack.monitoring.collection.enabled` setting.

Except where noted otherwise, these settings can be dynamically updated on a
live cluster with the <<cluster-update-settings,cluster-update-settings>> API.

To adjust how monitoring data is displayed in the monitoring UI, configure
{kibana-ref}/monitoring-settings-kb.html[`xpack.monitoring` settings] in
`kibana.yml`. To control how monitoring data is collected from {ls},
configure monitoring settings in `logstash.yml`.

For more information, see <<monitor-elasticsearch-cluster>>.

[discrete]
[[general-monitoring-settings]]
==== General monitoring settings

`xpack.monitoring.enabled`::
deprecated:[7.8.0,Basic License features should always be enabled]
(<<static-cluster-setting,Static>>) This deprecated setting has no effect.

[discrete]
[[monitoring-collection-settings]]
==== Monitoring collection settings

[[monitoring-settings-description]]
// tag::monitoring-settings-description-tag[]
The `xpack.monitoring.collection` settings control how data is collected from
your {es} nodes.
// end::monitoring-settings-description-tag[]

`xpack.monitoring.collection.enabled`::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0]  Set to `true` to enable the collection of
monitoring data. When this setting is `false` (default), {es} monitoring data is
not collected and all monitoring data from other sources such as {kib}, Beats,
and {ls} is ignored.

[[xpack-monitoring-collection-interval]]
// tag::monitoring-collection-interval-tag[]
`xpack.monitoring.collection.interval` {ess-icon}::
deprecated:[6.3.0,"Use `xpack.monitoring.collection.enabled` set to `false` instead."] 
(<<cluster-update-settings,Dynamic>>) Setting to `-1` to disable data collection
is no longer supported beginning with 7.0.0.
+
Controls how often data samples are collected. Defaults to `10s`. If you
modify the collection interval, set the `xpack.monitoring.min_interval_seconds`
option in `kibana.yml` to the same value.
// end::monitoring-collection-interval-tag[]

`xpack.monitoring.elasticsearch.collection.enabled`::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0] Controls whether statistics about your
{es} cluster should be collected. Defaults to `true`. This is different from 
`xpack.monitoring.collection.enabled`, which allows you to enable or disable all
monitoring collection. However, this setting simply disables the collection of
{es} data while still allowing other data (e.g., {kib}, {ls}, Beats, or APM
Server monitoring data) to pass through this cluster.

`xpack.monitoring.collection.cluster.stats.timeout`::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0] Timeout for collecting the cluster
statistics, in <<time-units,time units>>. Defaults to `10s`.

`xpack.monitoring.collection.node.stats.timeout`::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0] Timeout for collecting the node statistics,
in <<time-units,time units>>. Defaults to `10s`.

`xpack.monitoring.collection.indices`::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0] Controls which indices the
{monitor-features} collect data from. Defaults to all indices. Specify the index
names as a comma-separated list, for example `test1,test2,test3`. Names can
include wildcards, for example `test*`. You can explicitly exclude indices by
prepending `-`. For example `test*,-test3` will monitor all indexes that start
with `test` except for `test3`. System indices like .security* or .kibana*
always start with a `.` and generally should be monitored. Consider adding `.*`
to the list of indices ensure monitoring of system indices. For example:
`.*,test*,-test3`

`xpack.monitoring.collection.index.stats.timeout`::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0] Timeout for collecting index statistics,
in <<time-units,time units>>. Defaults to `10s`.

`xpack.monitoring.collection.index.recovery.active_only`::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0] Controls whether or not all recoveries are
collected. Set to `true` to collect only active recoveries. Defaults to `false`.

`xpack.monitoring.collection.index.recovery.timeout`::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0] Timeout for collecting the recovery
information, in <<time-units,time units>>. Defaults to `10s`.

[[xpack-monitoring-history-duration]]
// tag::monitoring-history-duration-tag[]
`xpack.monitoring.history.duration` {ess-icon}::
(<<cluster-update-settings,Dynamic>>)  deprecated:[7.16.0] Retention duration beyond which the
indices created by a monitoring exporter are automatically deleted, in
<<time-units,time units>>. Defaults to `7d` (7 days).
+
--
This setting has a minimum value of `1d` (1 day) to ensure that something is
being monitored and it cannot be disabled.

IMPORTANT: This setting currently impacts only `local`-type exporters. Indices
created using the `http` exporter are not deleted automatically.

--

// end::monitoring-history-duration-tag[]

`xpack.monitoring.exporters`::
(<<static-cluster-setting,Static>>) Configures where the agent stores monitoring
data. By default, the agent uses a local exporter that indexes monitoring data
on the cluster where it is installed. Use an HTTP exporter to send data to a
separate monitoring cluster. For more information, see
<<local-exporter-settings,Local exporter settings>>,
<<http-exporter-settings,HTTP exporter settings>>, and <<how-monitoring-works>>.

[discrete]
[[local-exporter-settings]]
==== Local exporter settings

The `local` exporter is the default exporter used by {monitor-features}. As the
name is meant to imply, it exports data to the _local_ cluster, which means that
there is not much needed to be configured.

If you do not supply _any_ exporters, then the {monitor-features} automatically
create one for you. If any exporter is provided, then no default is added.

[source,yaml]
----------------------------------
xpack.monitoring.exporters.my_local:
  type: local
----------------------------------

`type`::
 deprecated:[7.16.0] The value for a Local exporter must always be `local` and it is required.

`use_ingest`::
Whether to supply a placeholder pipeline to the cluster and a pipeline processor
with every bulk request. The default value is `true`. If disabled, then it means
that it will not use pipelines, which means that a future release cannot
automatically upgrade bulk requests to future-proof them.

`cluster_alerts.management.enabled`::

 deprecated:[7.16.0] Whether to create cluster alerts for this cluster. The default value is `true`.
To use this feature, {watcher} must be enabled. If you have a basic license,
cluster alerts are not displayed.

`wait_master.timeout`::
 deprecated:[7.16.0] Time to wait for the master node to setup `local` exporter for monitoring, in
<<time-units,time units>>. After that wait period, the non-master nodes warn the
user for possible missing configuration. Defaults to `30s`.

[discrete]
[[http-exporter-settings]]
==== HTTP exporter settings

The following lists settings that can be supplied with the `http` exporter.
All settings are shown as what follows the name you select for your exporter:

[source,yaml]
----------------------------------
xpack.monitoring.exporters.my_remote:
  type: http
  host: ["host:port", ...]
----------------------------------

`type`::
 deprecated:[7.16.0] The value for an HTTP exporter must always be `http` and it is required.

`host`::
 deprecated:[7.16.0] Host supports multiple formats, both as an array or as a single value. Supported
formats include `hostname`, `hostname:port`,
`http://hostname` `http://hostname:port`, `https://hostname`, and
`https://hostname:port`. Hosts cannot be assumed. The default scheme is always
`http` and the default port is always `9200` if not supplied as part of the
`host` string.
+
[source,yaml]
----------------------------------
xpack.monitoring.exporters:
  example1:
    type: http
    host: "10.1.2.3"
  example2:
    type: http
    host: ["http://10.1.2.4"]
  example3:
    type: http
    host: ["10.1.2.5", "10.1.2.6"]
  example4:
    type: http
    host: ["https://10.1.2.3:9200"]
----------------------------------

`auth.username`::
 deprecated:[7.16.0] The username is required if `auth.secure_password` is supplied.

`auth.secure_password`::
(<<secure-settings,Secure>>, <<reloadable-secure-settings,reloadable>>)  deprecated:[7.16.0] The
password for the `auth.username`.

`connection.timeout`::
 deprecated:[7.16.0] Amount of time that the HTTP connection is supposed to wait for a socket to open
for the request, in <<time-units,time units>>. The default value is `6s`.

`connection.read_timeout`::
 deprecated:[7.16.0] Amount of time that the HTTP connection is supposed to wait for a socket to
send back a response, in <<time-units,time units>>. The default value is
`10 * connection.timeout` (`60s` if neither are set).

`ssl`::
 deprecated:[7.16.0] Each HTTP exporter can define its own TLS / SSL settings or inherit them. See
<<ssl-monitoring-settings>>.

`proxy.base_path`::
 deprecated:[7.16.0] The base path to prefix any outgoing request, such as `/base/path` (e.g., bulk
requests would then be sent as `/base/path/_bulk`). There is no default value.

`headers`::
 deprecated:[7.16.0] Optional headers that are added to every request, which can assist with routing
requests through proxies.
+
[source,yaml]
----------------------------------
xpack.monitoring.exporters.my_remote:
  headers:
    X-My-Array: [abc, def, xyz]
    X-My-Header: abc123
----------------------------------
+
Array-based headers are sent `n` times where `n` is the size of the array.
`Content-Type` and `Content-Length` cannot be set. Any headers created by the
monitoring agent will override anything defined here.

`index.name.time_format`::
 deprecated:[7.16.0] A mechanism for changing the default date suffix for daily monitoring indices.
The default format is `yyyy.MM.dd`. For example, `.monitoring-es-7-2021.08.26`.

`use_ingest`::
Whether to supply a placeholder pipeline to the monitoring cluster and a
pipeline processor with every bulk request. The default value is `true`. If
disabled, then it means that it will not use pipelines, which means that a
future release cannot automatically upgrade bulk requests to future-proof them.

`cluster_alerts.management.enabled`::
 deprecated:[7.16.0] Whether to create cluster alerts for this cluster. The default value is `true`.
To use this feature, {watcher} must be enabled. If you have a basic license,
cluster alerts are not displayed.

`cluster_alerts.management.blacklist`::
 deprecated:[7.16.0] Prevents the creation of specific cluster alerts. It also removes any applicable
watches that already exist in the current cluster.
+
--
You can add any of the following watch identifiers to the list of blocked alerts:

* `elasticsearch_cluster_status`
* `elasticsearch_version_mismatch`
* `elasticsearch_nodes`
* `kibana_version_mismatch`
* `logstash_version_mismatch`
* `xpack_license_expiration`

For example: `["elasticsearch_version_mismatch","xpack_license_expiration"]`.
--

[[ssl-monitoring-settings]]
:ssl-prefix:             xpack.monitoring.exporters.$NAME
:component:              {monitoring}
:verifies:
:server!:
:ssl-context:            monitoring

==== {component} TLS/SSL settings
You can configure the following TLS/SSL settings.

+{ssl-prefix}.ssl.supported_protocols+::
(<<static-cluster-setting,Static>>)  deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-supported-protocols]

ifdef::verifies[]
+{ssl-prefix}.ssl.verification_mode+::
(<<static-cluster-setting,Static>>)  deprecated:[7.16.0] 
Controls the verification of certificates.
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
endif::verifies[]

+{ssl-prefix}.ssl.cipher_suites+::
(<<static-cluster-setting,Static>>)  deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-cipher-suites-values]

[#{ssl-context}-tls-ssl-key-trusted-certificate-settings]
===== {component} TLS/SSL key and trusted certificate settings

The following settings are used to specify a private key, certificate, and the
trusted certificates that should be used when communicating over an SSL/TLS connection.
ifndef::server[]
A private key and certificate are optional and would be used if the server requires client authentication for PKI
authentication.
endif::server[]

===== PEM encoded files

When using PEM encoded files, use the following settings:

+{ssl-prefix}.ssl.key+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0]
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem]

+{ssl-prefix}.ssl.key_passphrase+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]

+{ssl-prefix}.ssl.secure_key_passphrase+::
(<<secure-settings,Secure>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-secure-key-passphrase]

+{ssl-prefix}.ssl.certificate+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate]

+{ssl-prefix}.ssl.certificate_authorities+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-certificate-authorities]

===== Java keystore files

When using Java keystore files (JKS), which contain the private key, certificate
and certificates that should be trusted, use the following settings:

+{ssl-prefix}.ssl.keystore.path+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]

+{ssl-prefix}.ssl.keystore.password+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]

+{ssl-prefix}.ssl.keystore.secure_password+::
(<<secure-settings,Secure>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]

+{ssl-prefix}.ssl.keystore.key_password+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]

+{ssl-prefix}.ssl.keystore.secure_key_password+::
(<<secure-settings,Secure>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]

+{ssl-prefix}.ssl.truststore.path+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]

+{ssl-prefix}.ssl.truststore.password+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]

+{ssl-prefix}.ssl.truststore.secure_password+::
(<<secure-settings,Secure>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]

[#{ssl-context}-pkcs12-files]
===== PKCS#12 files

{es} can be configured to use PKCS#12 container files (`.p12` or `.pfx` files)
that contain the private key, certificate and certificates that should be trusted.

PKCS#12 files are configured in the same way as Java keystore files:

+{ssl-prefix}.ssl.keystore.path+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]

+{ssl-prefix}.ssl.keystore.type+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]

+{ssl-prefix}.ssl.keystore.password+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]

+{ssl-prefix}.ssl.keystore.secure_password+::
(<<secure-settings,Secure>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]

+{ssl-prefix}.ssl.keystore.key_password+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]

+{ssl-prefix}.ssl.keystore.secure_key_password+::
(<<secure-settings,Secure>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key-password]

+{ssl-prefix}.ssl.truststore.path+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]

+{ssl-prefix}.ssl.truststore.type+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file.
//TBD:Should this use the ssl-truststore-type definition and default values?

+{ssl-prefix}.ssl.truststore.password+::
(<<static-cluster-setting,Static>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]

+{ssl-prefix}.ssl.truststore.secure_password+::
(<<secure-settings,Secure>>) deprecated:[7.16.0] 
include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-secure-password]