Skip to content

Commit 2da238a

Browse files
colleenmcginnismergify[bot]
colleenmcginnis
authored and
mergify[bot]
committed
[synthetics] Add lightweight monitor configuration options (#2729)
* copy-paste from beats * add data types * format and edit common options * fix links * update structure * clean up * add links * address feedback from @andrewvc * address remaining feedback, clean up * fix tiny typo (cherry picked from commit c4af37c)
1 parent 6937263 commit 2da238a

File tree

5 files changed

+709
-40
lines changed

5 files changed

+709
-40
lines changed

‎docs/en/observability/synthetics-lightweight.asciidoc

Lines changed: 179 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -3,33 +3,44 @@
33

44
beta[]
55

6-
To configure lightweight monitors define a set of `monitors` to check your remote hosts.
7-
Each `monitor` item is an entry in a YAML list and begins with a dash (`-`).
8-
You can define the type of monitor to use, the hosts to check, and other
9-
optional settings.
6+
In the {synthetics-app} you can monitor the status of network endpoints using the following lightweight checks:
7+
8+
* *HTTP*: Monitor your website. The HTTP monitor checks to make sure specific endpoints return the correct
9+
status code and display the correct text.
10+
* *ICMP*: Check the availability of your hosts. The ICMP monitor uses ICMP (v4 and v6) Echo
11+
Requests to check the network reachability of the hosts you are pinging. This will tell you whether the
12+
host is available and connected to the network, but doesn't tell you if a service on the host is running or
13+
not.
14+
* *TCP*: Monitor the services running on your hosts. The TCP monitor checks individual ports
15+
to make sure the service is accessible and running.
1016

11-
Lightweight monitors can be configured using any of the following:
17+
Lightweight monitors can be configured using either the <<synthetics-lightweight-ui>>
18+
or <<synthetics-lightweight-projects>>.
1219

13-
* *YAML files in {project-monitors}*.
14-
<<synthetics-get-started-project,Set up a project>> and configure monitors in YAML
15-
files in the `lightweight` directory.
16-
* *{synthetics-app}*.
17-
<<synthetics-get-started-ui,Go to the {synthetics-app}>> in {kib} and configure monitors.
20+
[discrete]
21+
[[synthetics-lightweight-ui]]
22+
= {synthetics-app}
23+
24+
To use the UI in the {synthetics-app}, go to the {synthetics-app} in {kib} to create and configure monitors.
25+
For step-by-step instructions, refer to <<synthetics-get-started-ui>>.
26+
27+
[role="screenshot"]
28+
image::images/uptime-set-up-ui.asciidoc.png[Synthetics Create monitor UI]
1829

1930
[discrete]
20-
[[synthetics-monitor-types]]
21-
= Monitor types
31+
[[synthetics-lightweight-projects]]
32+
= {project-monitors-cap}
33+
34+
To use YAML files in to create {project-monitors}, <<synthetics-get-started-project,set up a project>>
35+
and configure monitors in YAML files in the `lightweight` directory.
2236

23-
`http`:: Connects via HTTP and optionally verifies that the host returns the
24-
expected response. Will use `Elastic-Heartbeat` as
25-
the user agent product.
26-
`icmp`:: Uses an ICMP (v4 and v6) Echo Request to ping the configured hosts.
27-
Requires special permissions or root access.
28-
`tcp`:: Connects via TCP and optionally verifies the endpoint by sending and/or
29-
receiving a custom payload.
37+
In each YAML file, define a set of `monitors` to check your remote hosts.
38+
Each `monitor` item is an entry in a YAML list and begins with a dash (`-`).
39+
You can define the type of monitor to use, the hosts to check, and other
40+
optional settings.
3041

3142
The following example configures three monitors checking via the `http`, `icmp`, and `tcp`
32-
protocols and demonstrates how to use TCP Echo and HTTP response verification:
43+
protocols and demonstrates how to use TCP Echo response verification:
3344

3445
[source,yaml]
3546
----
@@ -51,32 +62,160 @@ heartbeat.monitors:
5162
check.send: "Check"
5263
check.receive: "Check"
5364
schedule: '@every 5s'
54-
heartbeat.scheduler:
55-
limit: 10
5665
----
5766

58-
[discrete]
5967
[[synthetics-monitor-options]]
60-
= Configuration options
68+
There are some common monitor configuration options that are the same for all lightweight monitor types.
69+
For a complete list, refer to <<synthetics-lightweight-common-options>>.
6170

62-
You can find a complete reference of available configuration options in
63-
the {heartbeat} documentation.
71+
Each monitor type also has additional configuration options that are specific to that type.
72+
Refer to:
6473

65-
[NOTE]
66-
====
67-
While the most commonly used {heartbeat} configuration options are supported,
68-
some configuration options are not yet supported in {project-monitors} and the {synthetics-app}.
69-
====
74+
* <<synthetics-lightweight-http>>
75+
* <<synthetics-lightweight-icmp>>
76+
* <<synthetics-lightweight-tcp>>
7077

71-
There are some common monitor configuration options that are the same for all monitors.
72-
For a complete list, refer to {heartbeat-ref}/monitor-options.html[Common monitor options].
78+
The `tcp` and `http` monitor types both support SSL/TLS and some proxy settings.
7379

74-
Each monitor type has additional configuration options that are specific to that monitor type.
75-
Refer to:
80+
[discrete]
81+
[[synthetics-lightweight-common-options]]
82+
== Common options
83+
84+
You can specify the following options when defining a synthetic monitor in any location.
85+
These options are the same for all monitors. Each monitor type has additional configuration
86+
options that are specific to that monitor type.
87+
88+
// Reference table
89+
include::synthetics-reference/lightweight-config/common.asciidoc[]
90+
91+
[discrete]
92+
[[synthetics-lightweight-http]]
93+
== HTTP options
94+
95+
The options described here configure Synthetics to connect via HTTP and
96+
optionally verify that the host returns the expected response.
97+
98+
Valid options for HTTP monitors include <<synthetics-lightweight-common-options,all common options>>
99+
and the following HTTP-specific options:
100+
101+
// Reference table
102+
include::synthetics-reference/lightweight-config/http.asciidoc[]
103+
104+
[discrete]
105+
[[synthetics-lightweight-icmp]]
106+
== ICMP options
107+
108+
The options described here configure Synthetics to use ICMP (v4 and v6) Echo
109+
Requests to check the configured hosts. On most platforms you must execute
110+
Synthetics with elevated permissions to perform ICMP pings.
111+
112+
On Linux, regular users may perform pings if the right file capabilities are set. Run
113+
`sudo setcap cap_net_raw+eip /path/to/heartbeat` to grant Synthetics ping capabilities on Linux.
114+
Alternatively, you can grant ping permissions to the user being used to run Synthetics.
115+
To grant ping permissions in this way, run `sudo sysctl -w net.ipv4.ping_group_range='myuserid myuserid'`.
116+
117+
Other platforms may require Synthetics to run as root or administrator to execute pings.
118+
119+
Valid options for ICMP monitors include <<synthetics-lightweight-common-options,all common options>>
120+
and the following ICMP-specific options:
121+
122+
// Reference table
123+
include::synthetics-reference/lightweight-config/icmp.asciidoc[]
124+
125+
[discrete]
126+
[[synthetics-lightweight-tcp]]
127+
== TCP options
128+
129+
The options described here configure Synthetics to connect via TCP and
130+
optionally verify the endpoint by sending and/or receiving a custom payload.
131+
132+
Valid options for TCP monitors include <<synthetics-lightweight-common-options,all common options>>
133+
and the following TCP-specific options:
134+
135+
// Reference table
136+
include::synthetics-reference/lightweight-config/tcp.asciidoc[]
137+
138+
[discrete]
139+
[[synthetics-lightweight-data-types]]
140+
== Data types reference
141+
142+
Values of configuration settings are interpreted as required by Synthetics.
143+
If a value can't be correctly interpreted as the required type - for example a
144+
string is given when a number is required - Synthetics will fail to start up.
145+
146+
[discrete]
147+
[[synthetics-lightweight-data-bool]]
148+
=== Boolean
149+
150+
Boolean values can be either `true` or `false`. Alternative names for `true` are
151+
`yes` and `on`. Instead of `false` the values `no` and `off` can be used.
152+
153+
[source,yaml]
154+
-----
155+
enabled: true
156+
disabled: false
157+
-----
158+
159+
[discrete]
160+
[[synthetics-lightweight-data-numbers]]
161+
=== Number
162+
163+
Number values require you to enter the number _without_ single or
164+
double quotes.
165+
166+
[source,yaml]
167+
-----
168+
integer: 123
169+
negative: -1
170+
float: 5.4
171+
-----
172+
173+
NOTE: Some settings only support a restricted number range.
174+
175+
[discrete]
176+
[[synthetics-lightweight-data-string]]
177+
=== String
178+
179+
In http://www.yaml.org[YAML], multiple styles of string definitions are supported:
180+
double-quoted, single-quoted, unquoted.
181+
182+
The double-quoted style is specified by surrounding the string with `"`. This
183+
style provides support for escaping unprintable characters using `\`, but comes
184+
at the cost of having to escape `\` and `"` characters.
185+
186+
The single-quoted style is specified by surrounding the string with `'`. This
187+
style supports no escaping (use `''` to quote a single quote). Only printable
188+
characters can be used when using this form.
189+
190+
Unquoted style requires no quotes, but does not support any escaping and can't
191+
include any symbol that has a special meaning in YAML.
192+
193+
NOTE: Single-quoted style is recommended when defining regular expressions,
194+
event format strings, windows file paths, or non-alphabetical symbolic characters.
195+
196+
[discrete]
197+
[[synthetics-lightweight-data-duration]]
198+
=== Duration
199+
200+
Durations require a numeric value with optional fraction and required unit.
201+
Valid time units are `ns`, `us`, `ms`, `s`, `m`, `h`. Sometimes features based
202+
on durations can be disabled by using zero or negative durations.
203+
204+
[source,yaml]
205+
-----
206+
duration1: 2.5s
207+
duration2: 6h
208+
duration_disabled: -1s
209+
-----
210+
211+
[discrete]
212+
[[synthetics-lightweight-data-regex]]
213+
=== Regular expression
76214

77-
* {heartbeat-ref}/monitor-http-options.html[HTTP monitors]
78-
* {heartbeat-ref}/monitor-tcp-options.html[ICMP monitors]
79-
* {heartbeat-ref}/monitor-tcp-options.html[TCP monitors]
215+
Regular expressions are special strings that are compiled into regular
216+
expressions at load time.
80217

81-
The `tcp` and `http` monitor types both support SSL/TLS and some proxy
82-
settings.
218+
As regular expressions and YAML use `\` for escaping
219+
characters in strings, it's highly recommended to use single quoted strings when
220+
defining regular expressions. When single quoted strings are used, the `\` character
221+
is not interpreted by YAML parser as an escape symbol.

‎docs/en/observability/synthetics-reference/lightweight-config/common.asciidoc

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
:hardbreaks-option:
2+
3+
[%header]
4+
|===
5+
| Option (type) | Description
6+
7+
// type
8+
| [[monitor-type]] *`type`*
9+
(`"http"` \| `"icmp"` \| `"tcp"`)
10+
a| *Required*. The type of monitor to run. One of:
11+
12+
* `http`: Connects via HTTP and optionally verifies that the host returns the expected response.
13+
* `icmp`: Uses an ICMP (v4 and v6) Echo Request to ping the configured hosts. Requires special permissions or root access.
14+
* `tcp`: Connects via TCP and optionally verifies the endpoint by sending and/or receiving a custom payload.
15+
16+
////////////////////////
17+
id
18+
////////////////////////
19+
| [[monitor-id]] *`id`*
20+
(<<synthetics-lightweight-data-string,string>>)
21+
a| *Required*. A unique identifier for this configuration. This should not change with edits to the monitor configuration regardless of changes to any config fields.
22+
23+
*Examples*:
24+
25+
[source,yaml]
26+
----
27+
id: uploader-service
28+
----
29+
30+
[source,yaml]
31+
----
32+
id: http://example.net
33+
----
34+
35+
[NOTE]
36+
====
37+
When querying against indexed monitor data this is the field you will be aggregating with. It appears in the exported fields as `monitor.id`.
38+
39+
If you do not set an `id` explicitly, the monitor's config will be hashed and a generated value will be used. This value will change with any options change to this monitor making aggregations over time between changes impossible. For this reason, it's recommended that you set this manually.
40+
====
41+
42+
////////////////////////
43+
name
44+
////////////////////////
45+
| [[monitor-name]] *`name`*
46+
(<<synthetics-lightweight-data-string,string>>)
47+
a| Human readable name for this monitor.
48+
49+
*Examples*:
50+
51+
[source,yaml]
52+
----
53+
name: Uploader service
54+
----
55+
56+
[source,yaml]
57+
----
58+
name: Example website
59+
----
60+
61+
////////////////////////
62+
service.name
63+
////////////////////////
64+
| [[monitor-service_name]] *`service.name`*
65+
(<<synthetics-lightweight-data-string,string>>)
66+
a| APM service name for this monitor. Corresponds to the `service.name` ECS field. Set this when monitoring an app that is also using APM to enable integrations between Synthetics and APM data in Kibana.
67+
68+
////////////////////////
69+
enabled
70+
////////////////////////
71+
| [[monitor-enabled]] *`enabled`*
72+
(<<synthetics-lightweight-data-bool,boolean>>)
73+
a| Whether the module is enabled.
74+
75+
*Default*: `true`
76+
77+
*Example*:
78+
79+
[source,yaml]
80+
----
81+
enabled: false
82+
----
83+
84+
////////////////////////
85+
schedule
86+
////////////////////////
87+
| [[monitor-schedule]] *`schedule`*
88+
(<<synthetics-lightweight-data-duration,duration>>)
89+
a| *Required*. The task schedule.
90+
91+
NOTE: Schedules with less than 1 minute resolution will be saved to the nearest minute. For example, `@every 5s` will be changed to `@every 60s` when the monitor is pushed using the CLI.
92+
93+
*Example*:
94+
Run the task every 5 minutes from the time the monitor was started.
95+
96+
[source,yaml]
97+
----
98+
schedule: @every 5m
99+
----
100+
101+
////////////////////////
102+
timeout
103+
////////////////////////
104+
| [[monitor-timeout]] *`timeout`*
105+
(<<synthetics-lightweight-data-duration,duration>>)
106+
a| The total running time for each ping test. This is the total time allowed for testing the connection and exchanging data.
107+
108+
*Default*: `16s`
109+
110+
*Example*:
111+
112+
[source,yaml]
113+
----
114+
timeout: 2m
115+
----
116+
117+
////////////////////////
118+
tags
119+
////////////////////////
120+
| [[monitor-tags]] *`tags`*
121+
(list of <<synthetics-lightweight-data-string,string>>s)
122+
a| A list of tags that will be sent with the monitor event.
123+
124+
*Examples*:
125+
126+
[source,yaml]
127+
----
128+
tags:
129+
- tag one
130+
- tag two
131+
----
132+
133+
[source,yaml]
134+
----
135+
tags: ["tag one", "tag two"]
136+
----
137+
138+
|===
139+
140+
:!hardbreaks-option:

0 commit comments

Comments
 (0)