IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Uptime and synthetic monitoring Use synthetic monitors »

› ›

Set up monitors

edit

Set up monitors

edit

To set up an uptime monitor, you need to configure the monitor, run it, and send data back to Elasticsearch. Elastic provides Docker images that you can use to run monitors, which reduces the chance of problems. After setup is complete, the data will be available in the Uptime app in Kibana to view, analyze, and alert on.

Choose an approach

edit

There are two ways to set up an uptime monitor: Heartbeat or Elastic Agent.

Heartbeat

edit

Heartbeat is a lightweight daemon that you install on a remote server to periodically check the status of your services and determine if they are available. Performance data is then gathered and reported back to Heartbeat, where it’s formatted and sent to the Elastic Stack.

This approach works well for system administrators wanting to configure monitors using YAML files. It’s also the only method that will allow you to run monitors on premises that support configuring more than one location.

If you are not familiar with sysadmin processes and don’t need to run checks from more than one location, consider using the Elastic Agent approach.

Elastic Agent

edit

[beta] This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. Elastic Agent is a single, unified agent that you can deploy to hosts or containers to collect data and send it to the Elastic Stack. Behind the scenes, Elastic Agent runs Beats or Elastic Endpoint as required for your configuration.

The Elastic Agent approach works well if you want to configure and update monitors using a UI in your browser. While there are many benefits to using Elastic Agent, the Elastic Synthetics integration is currently in beta and is subject to change.

The Elastic Agent approach may not work for all use cases. This method does not support custom location names so is only suitable for running checks from a single location. Also, if you want to create and delete monitors programmatically, using Elastic Agent can be less convenient than using Heartbeat directly.

If you are using the Elastic Agent approach, there are also two prerequisites to complete before you can configure monitors:

Set up Fleet Server: If you are using Elastic Cloud, Fleet Server will already be provided and you can skip this step. To learn more, see Fleet.
Create a separate Fleet policy to use for Synthetics monitors: Generally, synthetics monitors should run on dedicated nodes. For more information on Fleet policies and creating them, see Elastic Agent policy.

Set up

edit

Once you’ve chosen an approach, you can begin setting up your first monitor.

Pull the Docker image

edit

Start by pulling the Docker image.

docker pull docker.elastic.co/beats/heartbeat:8.2.3

There are two Docker images you can use based on the type of monitor you are setting up.

For browser checks, you must use the elastic-agent-complete Docker image to create a self-hosted Elastic Agent node. This image contains the dependencies needed to run synthetic monitors. The standard Elastic Cloud or self-hosted Elastic Agent will not work.

docker pull docker.elastic.co/beats/elastic-agent-complete:8.2.3

For lightweight HTTP/S, TCP, and ICMP checks, you can use either the elastic-agent-complete image mentioned above or the following elastic-agent image:

docker pull docker.elastic.co/beats/elastic-agent:8.2.3

Configure

edit

Configure the monitor using either a heartbeat.yml configuration file or through the Elastic Agent UI.

Create a heartbeat.yml configuration file. There are four possible monitor types. The example below shows how to configure an http monitor.

heartbeat.monitors:
- 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'

Each monitor gets its own ID in the Uptime app and its own schedule entry. This allows tests to be run in parallel and analyzed separately.

Read more about configuration options in Configure Heartbeat monitors.

If you are setting up a browser monitor, see Write a synthetic test for more details on writing synthetic tests to be added to the configuration file.

Connect to the Elastic Stack

edit

After configuring the monitor, run it in Docker and connect the monitor to the Elastic Stack.

You’ll need to retrieve your Elasticsearch credentials for either an Elastic Cloud ID or another Elasticsearch Cluster.

The example below, shows how to run synthetics tests indexing data into Elasticsearch. You’ll need to insert your actual cloud.id and cloud.auth values to successfully index data to your cluster.

docker run \
  --rm \
  --name=heartbeat \
  --user=heartbeat \
  --volume="$PWD/heartbeat.yml:/usr/share/heartbeat/heartbeat.yml:ro" \
  docker.elastic.co/beats/elastic-agent-complete:8.2.3 heartbeat -e \
  -E cloud.id={cloud-id} \
  -E cloud.auth=elastic:{cloud-pass}

If you aren’t using Elastic Cloud, replace -E cloud.id and -E cloud.auth with your Elasticsearch hosts, username, and password:

docker run \
  --rm \
  --name=heartbeat \
  --user=heartbeat \
  --volume="$PWD/heartbeat.yml:/usr/share/heartbeat/heartbeat.yml:ro" \
  docker.elastic.co/beats/elastic-agent-complete:8.2.3 heartbeat -e \
  -E output.elasticsearch.hosts=["localhost:9200"] \
  -E output.elasticsearch.username=elastic \
  -E output.elasticsearch.password=changeme

Note the --volume option, which mounts local directories into the container. Here, we mount the heartbeat.yml from the working directory, into Heartbeat’s expected location for heartbeat.yml.

Elastic Synthetics runs Chromium without the extra protection of its process sandbox for greater compatibility with Linux server distributions. Add the sandbox: true option to a given browser monitor in Heartbeat to enable sandboxing. This may require using a custom seccomp policy with docker, which brings its own added risks. This is generally safe when run against sites whose content you trust, and with a recent version of Elastic Synthetics and Chromium.

[beta] This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features. To add an Elastic Agent to Fleet, you’ll need an enrollment token and the URL of your Fleet Server. You can use the default enrollment token for your policy or create new enrollment tokens as needed. This example uses the elastic-agent-complete Docker container.

docker run \
  --env FLEET_ENROLL=1 \
  --env FLEET_URL={fleet-server-host-url} \
  --env FLEET_ENROLLMENT_TOKEN={enrollment-token} \
  --rm docker.elastic.co/beats/elastic-agent-complete:8.2.3

For more information on running Elastic Agent with Docker, see Run Elastic Agent in a container and Fleet enrollment tokens.

You may need to set other environment variables. Learn how in Elastic Agent environment variables guide.

View in Kibana

edit

Elastic Synthetics is now sending synthetic monitoring data to the Elastic Stack. Navigate to the Uptime app in Kibana, where you can see screenshots of each run, set up alerts in case of test failures, and more.

If a test does fail (shown as down in the Uptime app), you’ll be able to view the step script that failed, any errors, and a stack trace. See Visualize for more information.

« Uptime and synthetic monitoring Use synthetic monitors »