Configure lightweight monitors
Monitor the status of network endpoints using the following lightweight checks:
-
HTTP: Monitor your website. The HTTP monitor checks to make sure specific endpoints return the correct status code and display the correct text.
-
ICMP: Check the availability of your hosts. The ICMP monitor uses ICMP (v4 and v6) Echo Requests to check the network reachability of the hosts you are pinging. This will tell you whether the host is available and connected to the network, but doesn't tell you if a service on the host is running or not.
-
TCP: Monitor the services running on your hosts. The TCP monitor checks individual ports to make sure the service is accessible and running.
Lightweight monitors can be configured using either the Synthetics UI or a Synthetics project.
Synthetics UI
To use the UI, go to Synthetics in your Observability project to create and configure monitors. For step-by-step instructions, refer to Create monitors in the Synthetics UI.
Synthetics project
To use YAML files to create lightweight monitors in a Synthetics project, set up the Synthetics project
and configure monitors in YAML files in the lightweight
directory.
In each YAML file, define a set of monitors
to check your remote hosts.
Each monitor
item is an entry in a YAML list and begins with a dash (-
).
You can define the type of monitor to use, the hosts to check, and other
optional settings.
The following example configures three monitors checking via the http
, icmp
, and tcp
protocols and demonstrates how to use TCP Echo response verification:
heartbeat.monitors:
- type: http
name: Todos Lightweight
id: todos-lightweight
urls: "https://elastic.github.io/synthetics-demo/"
schedule: '@every 1m'
- type: icmp
id: ping-myhost
name: My Host Ping
hosts: "myhost"
schedule: '@every 5m'
- 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 60s'
There are some common monitor configuration options that are the same for all lightweight monitor types. For a complete list, refer to Common options.
Each monitor type also has additional configuration options that are specific to that type. Refer to:
The tcp
and http
monitor types both support SSL/TLS and some proxy settings.
Common options
You can specify the following options when defining a synthetic 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.
Option (type) | Description |
---|---|
| Required. The type of monitor to run. One of:
|
| Required. A unique identifier for this configuration. This should not change with edits to the monitor configuration regardless of changes to any config fields. Examples:
Note When querying against indexed monitor data this is the field you will be aggregating with. It appears in the exported fields as If you do not set an |
| Human readable name for this monitor. Examples:
|
| APM service name for this monitor. Corresponds to the |
| Whether the monitor is enabled. Default: Example:
|
| Required. The task schedule. Note Schedules with less than 1 minute resolution will be saved to the nearest minute. For example, Example: Run the task every 5 minutes from the time the monitor was started.
|
| The total running time for each ping test. This is the total time allowed for testing the connection and exchanging data. Default: Example:
|
| A list of tags that will be sent with the monitor event. Examples:
|
| One of two modes in which to run the monitor:
Default: Example:
If you're using a DNS-load balancer and want to ping every IP address for the specified hostname, you should use |
| Whether to ping using the ipv4 protocol if hostnames are configured. Default: Example:
|
| Whether to ping using the ipv6 protocol if hostnames are configured. Default: Example:
|
alert | Enable or disable alerts on this monitor. Read more about alerts in Alerting. |
| Enable or disable retesting when a monitor fails. Default is By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created, and if configured, an alert sent. Then the monitor will resume running according to the defined schedule. Using Example:
|
| Where to deploy the monitor. You can deploy monitors in multiple locations to detect differences in availability and response times across those locations. To list available locations you can:
Examples:
Note This can also be set using
The value defined via the CLI takes precedence over the value defined in the lightweight monitor configuration, and the value defined in the lightweight monitor configuration takes precedence over the value defined in Synthetics project configuration file. |
| The Private Locations to which the monitors will be deployed. These Private Locations refer to locations hosted and managed by you, whereas To list available Private Locations you can:
Examples:
Note This can also be set using
The value defined via the CLI takes precedence over the value defined in the lightweight monitor configuration, and the value defined in the lightweight monitor configuration takes precedence over the value defined in Synthetics project configuration file. |
fields | A list of key-value pairs that will be sent with each monitor event.
The Examples:
|
HTTP options
The options described here configure Synthetics to connect via HTTP and optionally verify that the host returns the expected response.
Valid options for HTTP monitors include all common options and the following HTTP-specific options:
Option (type) | Description |
---|---|
| Required. The URL to ping. |
| The total number of redirections Synthetics will follow. By default, Synthetics will not follow redirects, but will report the status of the redirect. If set to a number greater than When this option is set to a value greater than Default: |
proxy_headers | Additional headers to send to proxies during |
| The HTTP proxy URL. This setting is optional. Example:
|
| The username for authenticating with the server. The credentials are passed with the request. This setting is optional. You need to specify credentials when your |
| The password for authenticating with the server. This setting is optional. |
| The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't specify settings, the system defaults are used. Example:
|
| Controls the indexing of the HTTP response headers Default: |
response | Controls the indexing of the HTTP response body contents to the
|
check |
|
ICMP options
The options described here configure Synthetics to use ICMP (v4 and v6) Echo Requests to check the configured hosts. On most platforms you must execute Synthetics with elevated permissions to perform ICMP pings.
On Linux, regular users may perform pings if the right file capabilities are set. Run
sudo setcap cap_net_raw+eip /path/to/heartbeat
to grant Synthetics ping capabilities on Linux.
Alternatively, you can grant ping permissions to the user being used to run Synthetics.
To grant ping permissions in this way, run sudo sysctl -w net.ipv4.ping_group_range='myuserid myuserid'
.
Other platforms may require Synthetics to run as root or administrator to execute pings.
Valid options for ICMP monitors include all common options and the following ICMP-specific options:
Option (type) | Description |
---|---|
| Required. The host to ping. Example:
|
| The duration to wait before emitting another ICMP Echo Request if no response is received. Default: Example:
|
TCP options
The options described here configure Synthetics to connect via TCP and optionally verify the endpoint by sending and/or receiving a custom payload.
Valid options for TCP monitors include all common options and the following TCP-specific options:
Option (type) | Description |
---|---|
| Required. The host to ping. The value can be:
Examples:
|
check | An optional payload string to send to the remote host and the expected answer. If no payload is specified, the endpoint is assumed to be available if the connection attempt was successful. If Example:
|
proxy_url | The URL of the SOCKS5 proxy to use when connecting to the server. The value must be a URL with a scheme of socks5://. If the SOCKS5 proxy server requires client authentication, then a username and password can be embedded in the URL. When using a proxy, hostnames are resolved on the proxy server instead of on the client. You can change this behavior by setting the Examples: A proxy URL that requires client authentication:
|
| A Boolean value that determines whether hostnames are resolved locally instead of being resolved on the proxy server. The default value is Default: |
| The TLS/SSL connection settings. If the monitor is configured to use SSL, it will attempt an SSL handshake. If Example:
Also see Configure SSL for a full description of the |
Data types reference
Values of configuration settings are interpreted as required by Synthetics. If a value can't be correctly interpreted as the required type - for example a string is given when a number is required - Synthetics will fail to start up.
Boolean
Boolean values can be either true
or false
. Alternative names for true
are
yes
and on
. Instead of false
the values no
and off
can be used.
enabled: true
disabled: false
Number
Number values require you to enter the number without single or double quotes.
integer: 123
negative: -1
float: 5.4
Note
Some settings only support a restricted number range.
String
In YAML, multiple styles of string definitions are supported: double-quoted, single-quoted, unquoted.
The double-quoted style is specified by surrounding the string with "
. This
style provides support for escaping unprintable characters using \
, but comes
at the cost of having to escape \
and "
characters.
The single-quoted style is specified by surrounding the string with '
. This
style supports no escaping (use ''
to quote a single quote). Only printable
characters can be used when using this form.
Unquoted style requires no quotes, but does not support any escaping and can't include any symbol that has a special meaning in YAML.
Note
Single-quoted style is recommended when defining regular expressions, event format strings, windows file paths, or non-alphabetical symbolic characters.
Duration
Durations require a numeric value with optional fraction and required unit.
Valid time units are ns
, us
, ms
, s
, m
, h
. Sometimes features based
on durations can be disabled by using zero or negative durations.
duration1: 2.5s
duration2: 6h
duration_disabled: -1s
Regular expression
Regular expressions are special strings that are compiled into regular expressions at load time.
As regular expressions and YAML use \
for escaping
characters in strings, it's highly recommended to use single quoted strings when
defining regular expressions. When single quoted strings are used, the \
character
is not interpreted by YAML parser as an escape symbol.