Configure lightweight monitors

type ("http", "icmp", or "tcp")

Required. The type of monitor to run. One of:

id (string)

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:

id: uploader-service

id: http://example.net

name (string)

Human readable name for this monitor.

Examples:

name: Uploader service

name: Example website

service.name (string)

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 your Observability project.

enabled (boolean)

Whether the monitor is enabled.

Default: true

Example:

enabled: false

schedule (duration)

Required. The task schedule.

Example: Run the task every 5 minutes from the time the monitor was started.

schedule: @every 5m

timeout (duration)

The total running time for each ping test. This is the total time allowed for testing the connection and exchanging data.

Default: 16s

Example:

timeout: 2m

tags (list of strings)

A list of tags that will be sent with the monitor event.

Examples:

tags:
  - tag one
  - tag two

tags: ["tag one", "tag two"]

mode ("any" or "all")

One of two modes in which to run the monitor:

Default: any

Example: If you’re using a DNS-load balancer and want to ping every IP address for the specified hostname, you should use all.

ipv4 (boolean)

Whether to ping using the ipv4 protocol if hostnames are configured.

Default: true

Example:

ipv4: false

ipv6 (boolean)

Whether to ping using the ipv6 protocol if hostnames are configured.

Default: true

Example:

ipv6: false

alert

Enable or disable alerts on this monitor. Read more about alerts in Alerting.

retest_on_failure (boolean)

Enable or disable retesting when a monitor fails. Default is true.

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 retestOnFailure can reduce noise related to transient problems.

Example:

retest_on_failure: false

locations (list of SyntheticsLocationsType)

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:

locations: ["japan", "india"]

locations:
  - japan
  - india

private_locations (list of strings)

The Private Locations to which the monitors will be deployed. These Private Locations refer to locations hosted and managed by you, whereas locations are hosted by Elastic. You can specify a Private Location using the location’s name.

To list available Private Locations you can:

Examples:

private_locations: ["Private Location 1", "Private Location 2"]

private_locations:
  - Private Location 1
  - Private Location 2

fields

A list of key-value pairs that will be sent with each monitor event. The fields are appended to Elasticsearch documents as labels, and those labels are displayed in Kibana in the Monitor details panel in the individual monitor’s Overview tab.

Examples:

fields:
  foo: bar
  team: synthetics

fields.foo: bar
fields.team: synthetics

urls (string)

Required. The URL to ping.

max_redirects (number)

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 0, Synthetics will follow that number of redirects.

When this option is set to a value greater than 0, the monitor.ip field will no longer be reported, as multiple DNS requests across multiple IPs may return multiple IPs. Fine-grained network timing data will also not be recorded, as with redirects that data will span multiple requests. Specifically the fields http.rtt.content.us, http.rtt.response_header.us, http.rtt.total.us, http.rtt.validate.us, http.rtt.write_request.us and dns.rtt.us will be omitted.

Default: 0

proxy_headers

Additional headers to send to proxies during CONNECT requests.

proxy_url (string)

The HTTP proxy URL. This setting is optional.

Example:

http://proxy.mydomain.com:3128

username (string)

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 check.response settings require it. For example, you can check for a 403 response (check.response.status: [403]) without setting credentials.

password (string)

The password for authenticating with the server. This setting is optional.

ssl (SSL)

The TLS/SSL connection settings for use with the HTTPS endpoint. If you don’t specify settings, the system defaults are used.

Example:

- type: http
  id: my-http-service
  name: My HTTP Service
  urls: "https://myhost:443"
  schedule: '@every 5s'
  ssl:
    certificate_authorities: ['/etc/ca.crt']
    supported_protocols: ["TLSv1.0", "TLSv1.1", "TLSv1.2"]

headers (boolean)

Controls the indexing of the HTTP response headers http.response.body.headers field. Set response.include_headers to false to disable.

Default: true

response

Controls the indexing of the HTTP response body contents to the http.response.body.contents field.

check

hosts (string)

Required. The host to ping.

Example:

hosts: "myhost"

wait (duration)

The duration to wait before emitting another ICMP Echo Request if no response is received.

Default: 1s

Example:

wait: 1m

hosts (string)

Required. The host to ping. The value can be:

Examples:

hosts: "localhost:8000"

hosts: "tcp://localhost:8000"

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 send is specified without receive, any response is accepted as OK. If receive is specified without send, no payload is sent, but the client expects to receive a payload in the form of a "hello message" or "banner" on connect.

Example:

check.send: 'Hello World'
check.receive: 'Hello World'

check:
  send: 'Hello World'
  receive: 'Hello World'

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 proxy_use_local_resolver option.

Examples:

A proxy URL that requires client authentication:

proxy_url: socks5://user:password@socks5-proxy:2233

proxy_use_local_resolver (boolean)

A Boolean value that determines whether hostnames are resolved locally instead of being resolved on the proxy server. The default value is false, which means that name resolution occurs on the proxy server.

Default: false

ssl (SSL)

The TLS/SSL connection settings. If the monitor is configured to use SSL, it will attempt an SSL handshake. If check is not configured, the monitor will only check to see if it can establish an SSL/TLS connection. This check can fail either at TCP level or during certificate validation.

Example:

ssl:
  certificate_authorities: ['/etc/ca.crt']
  supported_protocols: ["TLSv1.0", "TLSv1.1", "TLSv1.2"]

Also see Configure SSL for a full description of the ssl options.