[[configuration-heartbeat-options]]
== Configure {beatname_uc} monitors

++++
<titleabbrev>Monitors</titleabbrev>
++++

To configure {beatname_uc} define a set of `monitors` to check your remote hosts.
Specify monitors either directly inside the +heartbeat.yml+ config file, or in external
dynamically loaded files located in the directory referenced by `heartbeat.config.monitors.path`.
One advantage of using external files is that these can be automatically reloaded
without stopping the {beatname_uc} process.

Each `monitor` item is an entry in a yaml list, and so begins with a dash (-).
You can define the type of monitor to use, the hosts to check, and other
optional settings that control {beatname_uc} behavior.

The following example configures three monitors checking via the `icmp`, `tcp`, and `http`
protocols directly inside the +heartbeat.yml+ file, and demonstrates how to use TCP Echo
and HTTP response verification:

[source,yaml]
----------------------------------------------------------------------
# heartbeat.yml
heartbeat.monitors:
- type: icmp
  id: ping-myhost
  name: My Host Ping
  hosts: ["myhost"]
  schedule: '*/5 * * * * * *'
- type: tcp
  id: myhost-tcp-echo
  name: My Host TCP Echo
  hosts: ["myhost:777"]  # default TCP Echo Protocol
  check.send: "Check"
  check.receive: "Check"
  schedule: '@every 5s'
- type: http
  id: service-status
  name: Service Status
  service.name: my-apm-service-name
  hosts: ["http://localhost:80/service/status"]
  check.response.status: [200]
  schedule: '@every 5s'
heartbeat.scheduler:
  limit: 10
----------------------------------------------------------------------

Using the +heartbeat.yml+ configuration file is convenient, but has two drawbacks:
it can become hard to manage with large numbers of monitors, and it will not reload
heartbeat automatically when its contents changes.

Define monitors via the +heartbeat.config.monitors+ to prevent those issues from
happening to you. To do so you would instead have your +heartbeat.yml+ file contain the following:

[source,yaml]
----------------------------------------------------------------------
# heartbeat.yml
heartbeat.config.monitors:
  # Directory + glob pattern to search for configuration files
  path: /path/to/my/monitors.d/*.yml
  # If enabled, heartbeat will periodically check the config.monitors path for changes
  reload.enabled: true
  # How often to check for changes
  reload.period: 1s
----------------------------------------------------------------------

Then, define one or more files in the directory pointed to by `heartbeat.config.monitors.path`.
You may specify multiple monitors in a given file if you like. The contents of these files is
monitor definitions only, e.g. what is normally under the `heartbeat.monitors` section of
+heartbeat.yml+. See below for an example

[source,yaml]
----------------------------------------------------------------------
# /path/to/my/monitors.d/localhost_service_check.yml
- type: http
  id: service-status
  name: Service Status
  hosts: ["http://localhost:80/service/status"]
  check.response.status: [200]
  schedule: '@every 5s'
----------------------------------------------------------------------

[float]
[[monitor-types]]
=== Monitor types

You can configure {beatname_uc} to use the following monitor types:

*<<monitor-icmp-options,`icmp`>>*:: Uses an ICMP (v4 and v6) Echo Request to ping the configured hosts.
Requires special permissions or root access.
*<<monitor-tcp-options,`tcp`>>*:: Connects via TCP and optionally verifies the endpoint by sending and/or
receiving a custom payload.
*<<monitor-http-options,`http`>>*:: Connects via HTTP and optionally verifies that the host returns the
expected response. Will use `Elastic-Heartbeat` as
the user agent product.

The `tcp` and `http` monitor types both support SSL/TLS and some proxy
settings.

include::monitors/monitor-common-options.asciidoc[]

include::monitors/monitor-icmp.asciidoc[]

include::monitors/monitor-tcp.asciidoc[]

include::monitors/monitor-http.asciidoc[]
