[[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.
*<<monitor-browser-options,`browser`>>*:: Allows users to run the synthetic
monitoring test suites via Synthetic Agent on the Chromium browser.

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[]

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

[float]
[[run-once-mode]]
=== Run Once Mode (Experimental)

You can configure {beatname_uc} run monitors exactly once then exit, bypassing the scheduler. This is referred to as running {beatname_uc} in 
"run once" mode by setting `heartbeat.run_once: true`. All {beatname_uc} monitors will ignore their schedules and run exactly once at startup.
This is an experimental feature and is subject to change. 

Note, the `schedule` field is still required and is used by {beatname_uc} to set the expectation around when
the next run will occur. That duration is encoded in the `monitor.timespan` field in the {beatname_uc} output.

[source,yaml]
----------------------------------------------------------------------
# heartbeat.yml
heartbeat.run_once: true
heartbeat.monitors:
# your monitor config here...
----------------------------------------------------------------------
