Set up monitorsedit

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 approachedit

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


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 Agentedit

[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 upedit

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

Pull the Docker imageedit

Start by pulling the Docker image.

docker pull

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.

- type: http
  id: service-status 
  name: Service Status 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 Stackedit

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 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" \ heartbeat -e \
  -E{cloud-id} \
  -E cloud.auth=elastic:{cloud-pass}

If you aren’t using Elastic Cloud, replace -E 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" \ 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.

View in Kibanaedit

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.