Skip to content

Latest commit

 

History

History
130 lines (107 loc) · 4.99 KB

heartbeat-options.asciidoc

File metadata and controls

130 lines (107 loc) · 4.99 KB

Configure {beatname_uc} monitors

Monitors

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:

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

# 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

# /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'

Monitor types

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

icmp

Uses an ICMP (v4 and v6) Echo Request to ping the configured hosts. Requires special permissions or root access.

tcp

Connects via TCP and optionally verifies the endpoint by sending and/or receiving a custom payload.

http

Connects via HTTP and optionally verifies that the host returns the expected response. Will use Elastic-Heartbeat as the user agent product.

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.

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.

# heartbeat.yml
heartbeat.run_once: true
heartbeat.monitors:
# your monitor config here...