IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Synthetic monitoring Create a new synthetic test »
Elastic Docs ›Observability Guide [7.12] ›Synthetic monitoring

Quickstart: Synthetic monitoring via Docker

edit

Quickstart: Synthetic monitoring via Docker

edit

This functionality is experimental and may be changed or removed completely in a future release. Elastic will take a best effort approach to fix any issues, but experimental features are not subject to the support SLA of official GA features.

Have a question? Want to leave feedback? Visit the Synthetics discussion forum.

A customizable Docker project template is provided to get started with Elastic Synthetics quickly. This template provides two types of sample tests: a simple, two-step, inline test, and a packaged todo application with a custom suite of tests.

Step 1: Pull the latest synthetics docker image

edit

Elastic Synthetics is regularly updated during this experimental phase, even within the same version. You’ll want to ensure you’re running the latest docker image by running the command below .

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

Step 2: Create a heartbeat.yml configuration file

edit

There are two ways to configure a synthetic test. The config file below demonstrates both. The first entry in heartbeat.monitors uses the inline source type, where the entire synthetic journey is directly embedded in the yaml file. The second method, uses the local source type, which points to a local directory containing multiple tests. For test suites Heartbeat will attempt to run all files in that directory with the extension .journey.ts or .journey.js. See Syntax for more information.

To start, download or clone a local copy of our todos example suite from our synthetics repo to your local machine, and navigate to the examples/todos folder. We’ll work inside that folder going forward.

heartbeat.monitors:
- type: browser
  id: my-monitor 
  name: My Monitor
  schedule: "@every 1m"
  source:
    inline:
      script: |- 
        step("load homepage", async () => {
            await page.goto('https://www.elastic.co');
        });
        step("hover over products menu", async () => {
            await page.hover('css=[data-nav-item=products]');
        });
- name: Todos
  id: todos
  type: browser
  schedule: "@every 1m"
  source:
    local: 
      path: "/opt/todos"

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

In this example, a synthetic test is defined inline. This is a two-step script that first loads a homepage and then hovers over a product menu. See Syntax for more information.

In this example, our library of synthetic tests come from our todos example. The path shown here corresponds to the path Heartbeat will look at inside the docker container.

Note that this path is local to the docker container, not the host system. You can have the todos files anywhere you like on the host, and map them to /opt/todos in the container.

Step 3: Run the container, connecting it to Elasticsearch

edit

Before we proceed, you’ll need to retrieve your Elasticsearch credentials for either an Elastic Cloud ID or another Elasticsearch Cluster.

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 additional risks. This is generally safe when run against sites whose content you trust, and with a recent version of Elastic synthetics and chromium.

The example below, run from the examples/todos directory shows how to run synthetics tests indexing data into Elasticsearch.

Run the script below to start running your synthetics tests. 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" \
  --volume="$PWD:/opt/todos:ro" \
  docker.elastic.co/beats/heartbeat:7.12.1 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" \
  --volume="$PWD:/opt/todos:ro" \
  docker.elastic.co/beats/heartbeat:7.12.1 heartbeat -e \
  -E output.elasticsearch.hosts=["localhost:9200"] \
  -E output.elasticsearch.username=elastic \
  -E output.elasticsearch.password=changeme

Note the two --volume options, which mount local directories into the container. The first mounts the heartbeat.yml file configured above, into Heartbeat’s expected location for heartbeat.yml. The second mounts the test suite into the VM in the same location listed in the source section of our heartbeat.yml.

Step 4: View in Kibana

edit

That’s it! 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 app), you’ll be able to view the step script that failed, any errors, and a stack trace. See Visualize for more information.

Next steps

edit

Now you can customize the provided Docker example with your own tests! See Syntax to learn more.

« Synthetic monitoring Create a new synthetic test »