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

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

By default, monitoring is enabled but data collection is disabled. To enable
data collection, use the `xpack.monitoring.collection.enabled` setting.

You can configure these monitoring settings in the `elasticsearch.yml` file. You
can also dynamically set some of these settings using the
<<cluster-update-settings,cluster update settings API>>.

TIP: Cluster settings take precedence over settings in the `elasticsearch.yml`
file.

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 Logstash,
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] +
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 Elasticsearch nodes. You can dynamically change all monitoring collection
settings using the <<cluster-update-settings,cluster update settings API>>.
// end::monitoring-settings-description-tag[]

`xpack.monitoring.collection.enabled` (<<cluster-update-settings,Dynamic>>)::

added[6.3.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 Logstash is
ignored.

[[xpack-monitoring-collection-interval]]
// tag::monitoring-collection-interval-tag[]
`xpack.monitoring.collection.interval` (<<cluster-update-settings,Dynamic>>) {ess-icon}::

Setting to `-1` to disable data collection is no longer supported beginning with
7.0.0. deprecated[6.3.0, Use `xpack.monitoring.collection.enabled` set to `false` instead.]
+
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>>)::

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 Elasticsearch
data while still allowing other data (e.g., Kibana, Logstash, Beats, or APM Server monitoring data)
to pass through this cluster.

`xpack.monitoring.collection.cluster.stats.timeout` (<<cluster-update-settings,Dynamic>>)::

(<<time-units,time value>>) Timeout for collecting the cluster statistics. Defaults to `10s`.

`xpack.monitoring.collection.node.stats.timeout` (<<cluster-update-settings,Dynamic>>)::

(<<time-units,time value>>) Timeout for collecting the node statistics. Defaults to `10s`.

`xpack.monitoring.collection.indices` (<<cluster-update-settings,Dynamic>>)::

Controls which indices Monitoring collects 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>>)::

(<<time-units,time value>>) Timeout for collecting index statistics. Defaults to `10s`.

`xpack.monitoring.collection.index.recovery.active_only` (<<cluster-update-settings,Dynamic>>)::

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>>)::

(<<time-units,time value>>) Timeout for collecting the recovery information. Defaults to `10s`.

[[xpack-monitoring-history-duration]]
// tag::monitoring-history-duration-tag[]
`xpack.monitoring.history.duration` (<<cluster-update-settings,Dynamic>>) {ess-icon}::

(<<time-units,time value>>) Retention duration beyond which the indices created by a Monitoring
exporter are automatically deleted. 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 only impacts `local`-type exporters. Indices created using
the `http` exporter will not be deleted automatically.
--

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

`xpack.monitoring.exporters`::

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 Monitoring. 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 Monitoring will 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`::

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`::

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`::

(<<time-units,time value>>) Time to wait for the master node to setup `local` exporter for monitoring.
After that, the non-master nodes will warn the user for possible missing X-Pack 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`::

The value for an HTTP exporter must always be `http` and it is required.

`host`::

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`::

The username is required if `auth.secure_password` or `auth.password` is supplied.

`auth.secure_password` (<<secure-settings,Secure>>, <<reloadable-secure-settings,reloadable>>)::

The password for the `auth.username`. Takes precedence over `auth.password` if it is also specified.

`auth.password`::

The password for the `auth.username`. If `auth.secure_password` is also specified, this setting is ignored.

deprecated[7.7.0, Use `auth.secure_password` instead.]

`connection.timeout`::

(<<time-units,time value>>) Amount of time that the HTTP connection is supposed to wait for a socket to open for the
request. The default value is `6s`.

`connection.read_timeout`::

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

`ssl`::

Each HTTP exporter can define its own TLS / SSL settings or inherit them. See the
<<ssl-monitoring-settings, TLS / SSL section below>>.

`proxy.base_path`::

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`::

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`::

A mechanism for changing the default date suffix for the, by default, daily Monitoring indices.
The default value is `yyyy.MM.dd`, which is why the indices are created daily.

`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`::

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`::

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

include::ssl-settings.asciidoc[]