Skip to content

Commit

Permalink
Document heartbeat config reloading
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrewvc
andrewvc committed Sep 14, 2018
1 parent 037a4f2 commit 6e0c1e3
Showing 1 changed file with 104 additions and 66 deletions.
170 changes: 104 additions & 66 deletions heartbeat/docs/heartbeat-options.asciidoc
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,17 +5,22 @@
<titleabbrev>Set up Heartbeat monitors</titleabbrev>
++++

The `heartbeat.monitors` section of the +heartbeat.yml+ config file specifies
the list of `monitors` that Heartbeat uses to check your remote hosts to
determine if they are available. Each `monitor` item begins with a dash (-) and
specifies the type of monitor to use, the hosts to check, and other settings
that control Heartbeat behavior.
Heartbeat is configured by defining a set of `monitors` to check your remote hosts.
These can be specified either inside the +heartbeat.yml+ config file, or in external
files. One advantage of using external files is that these can be automatically
reloaded without stopping the Heartbeat process.

The following example configures three monitors, `icmp`, `tcp`, and `http`, and
demonstrates how to use TCP Echo and HTTP response verification:
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 Heartbeat 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
schedule: '*/5 * * * * * *'
Expand All @@ -33,14 +38,44 @@ 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
# 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
schedule: '@every 5s'
urls: ["http://localhost:80/service/status"]
check.response.status: 200
----------------------------------------------------------------------

[float]
[[monitor-options]]
=== Monitor options

You can specify the following options in the `heartbeat.monitors` section of the
+heartbeat.yml+ config file. These options are the same for all monitors.
Each monitor type has additional configuration options that are specific to that
monitor type.
You can specify the following options when defining a Heartbeat monitor in any location.
These options are the same for all monitors. Each monitor type has additional configuration
options that are specific to that monitor type.

[float]
[[monitor-type]]
Expand Down Expand Up @@ -160,61 +195,6 @@ A list of processors to apply to the data generated by the monitor.
See <<filtering-and-enhancing-data>> for information about specifying
processors in your config.

[float]
[[monitor-watch-poll-file]]
==== `watch.poll_file`

experimental[]

The JSON file to watch for additional monitor configurations. The JSON file can
contain multiple objects, each of which specifies a different monitor config.
Heartbeat checks this file periodically and starts a new monitor instance for
each new JSON object added to the file. For example, imagine that you add
10 new entries to the JSON file, each for a different hostname. When Heartbeat
picks up the changes in the file, it merges the original config
(`heartbeat.yml`) plus the JSON objects, and starts a monitor for each new host
that you've configured. If you delete an object from the JSON file and it
doesn't exist in the main config, Heartbeat stops the monitor instance running
for that object.

Each monitor has a unique ID that's based on parameters like protocol, host,
and port. If two monitors have the same ID, Heartbeat uses the settings that
are defined in the last JSON object of the merged config. This means that
you can specify settings in the JSON file that overwrite the settings in
the main config. In this way, the configuration that you specify for the
monitor in the main Heartbeat config file acts like a default config that you
can live-reconfigure by specifying additional configurations in the external
JSON file.

Example configuration:

[source, yaml]
-------------------------------------------------------------------------------
heartbeat.monitors:
- type: tcp
schedule: '*/5 * * * * * *'
hosts: ["myhost"]
watch.poll_file:
path: {path.config}/monitors/dynamic.json
interval: 5s
-------------------------------------------------------------------------------

*`path`*:: Specifies the path to the JSON file to check for updates.
*`interval`*:: Specifies how often Heartbeat checks the file for changes.

To reconfigure the settings specified in the example config, you could define
the following JSON objects in `dynamic.json`:

[source, json]
-------------------------------------------------------------------------------
{"hosts": ["myhost:1234"], "schedule": "*/15 * * * * * *"} <1>
{"hosts": ["tls://otherhost:479"], "ssl.certificate_authorities": ["path/to/ca/file.pem"]} <2>
-------------------------------------------------------------------------------
<1> Upon detecting the changes, Heartbeat stops the old monitor and then
restarts it with a schedule of 15 seconds between checks.
<2> Heartbeat starts a new monitor that uses a TLS-based connection with a
custom CA certificate.

[float]
[[monitor-icmp-options]]
=== ICMP options
Expand Down Expand Up @@ -556,5 +536,63 @@ specify for `limit` should be below the configured ulimit.

The timezone for the scheduler. By default the scheduler uses localtime.

[float]
[[monitor-watch-poll-file]]
==== `watch.poll_file`

experimental[]

THIS EXPERIMENTAL FEATURE IS NOW DEPRECATED. IT WILL BE REMOVED IN A FUTURE
RELEASE. It is replaced by using dynamic reloading via the
`heartbeat.config.monitors` option.

The JSON file to watch for additional monitor configurations. The JSON file can
contain multiple objects, each of which specifies a different monitor config.
Heartbeat checks this file periodically and starts a new monitor instance for
each new JSON object added to the file. For example, imagine that you add
10 new entries to the JSON file, each for a different hostname. When Heartbeat
picks up the changes in the file, it merges the original config
(`heartbeat.yml`) plus the JSON objects, and starts a monitor for each new host
that you've configured. If you delete an object from the JSON file and it
doesn't exist in the main config, Heartbeat stops the monitor instance running
for that object.

Each monitor has a unique ID that's based on parameters like protocol, host,
and port. If two monitors have the same ID, Heartbeat uses the settings that
are defined in the last JSON object of the merged config. This means that
you can specify settings in the JSON file that overwrite the settings in
the main config. In this way, the configuration that you specify for the
monitor in the main Heartbeat config file acts like a default config that you
can live-reconfigure by specifying additional configurations in the external
JSON file.

Example configuration:

[source, yaml]
-------------------------------------------------------------------------------
heartbeat.monitors:
- type: tcp
schedule: '*/5 * * * * * *'
hosts: ["myhost"]
watch.poll_file:
path: {path.config}/monitors/dynamic.json
interval: 5s
-------------------------------------------------------------------------------

*`path`*:: Specifies the path to the JSON file to check for updates.
*`interval`*:: Specifies how often Heartbeat checks the file for changes.

To reconfigure the settings specified in the example config, you could define
the following JSON objects in `dynamic.json`:

[source, json]
-------------------------------------------------------------------------------
{"hosts": ["myhost:1234"], "schedule": "*/15 * * * * * *"} <1>
{"hosts": ["tls://otherhost:479"], "ssl.certificate_authorities": ["path/to/ca/file.pem"]} <2>
-------------------------------------------------------------------------------
<1> Upon detecting the changes, Heartbeat stops the old monitor and then
restarts it with a schedule of 15 seconds between checks.
<2> Heartbeat starts a new monitor that uses a TLS-based connection with a
custom CA certificate.


0 comments on commit 6e0c1e3

Please sign in to comment.