Skip to content

Commit

Permalink
[DOCS] Document static monitoring settings (#61748) (#61757)
Browse files Browse the repository at this point in the history
  • Loading branch information
@lcawl
lcawl authored Aug 31, 2020
1 parent 457c824 commit 4f91964
Showing 1 changed file with 123 additions and 137 deletions.
260 changes: 123 additions & 137 deletions docs/reference/settings/monitoring-settings.asciidoc
View file
Original file line number Diff line number Diff line change
@@ -1,139 +1,134 @@
[role="xpack"]
[[monitoring-settings]]
=== Monitoring settings in Elasticsearch
=== Monitoring settings in {es}
++++
<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.
By default, {es} {monitor-features} are 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.
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 Logstash,
`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
==== General monitoring settings

`xpack.monitoring.enabled`::
deprecated:[7.8.0,Basic License features should always be enabled] +
This deprecated setting has no effect.
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 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>>.
your {es} nodes.
// 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.enabled`::
(<<cluster-update-settings,Dynamic>>) 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` (<<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.]
`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>>)::

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.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
{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>>) Timeout for collecting the cluster
statistics, in <<time-units,time units>>. Defaults to `10s`.

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

`xpack.monitoring.collection.indices`::
(<<cluster-update-settings,Dynamic>>) 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>>) Timeout for collecting index statistics,
in <<time-units,time units>>. 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>>) 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` (<<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).
`xpack.monitoring.history.duration` {ess-icon}::
(<<cluster-update-settings,Dynamic>>) 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.
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.

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>>.
(<<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
==== 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.
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 Monitoring will automatically create
one for you. If any exporter is provided, then no default is added.
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]
----------------------------------
Expand All @@ -142,15 +137,13 @@ xpack.monitoring.exporters.my_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.
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`::

Expand All @@ -159,13 +152,13 @@ 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`.
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
==== 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:
Expand All @@ -178,15 +171,15 @@ xpack.monitoring.exporters.my_remote:
----------------------------------

`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.
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]
----------------------------------
Expand All @@ -206,43 +199,39 @@ xpack.monitoring.exporters:
----------------------------------

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

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.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.]
deprecated:[7.7.0,"Use `auth.secure_password` instead."] The password for the
`auth.username`. If `auth.secure_password` is also specified, this setting is
ignored.

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

(<<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).
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`::

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

`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.
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.
Optional headers that are added to every request, which can assist with routing
requests through proxies.
+
[source,yaml]
----------------------------------
Expand All @@ -252,30 +241,27 @@ xpack.monitoring.exporters.my_remote:
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.
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.
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.
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,
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.
+
Expand Down

0 comments on commit 4f91964

Please sign in to comment.