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.10] ›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: Clone the elastic/synthetics repository

edit

This template pulls the Elastic synthetics image, builds your synthetic tests, schedules and runs them with Heartbeat, and sends the resulting data to the Elastic Stack.

Clone the elastic/synthetics repository and change directories into examples/docker:

git clone https://github.com/elastic/synthetics.git &&\
cd synthetics/examples/docker

There are two files in synthetics/examples/docker that you’ll need to edit:

synthetics
  |- examples
     |- docker
        |- heartbeat.docker.yml 
        |- run.sh

heartbeat.docker.yml is your Heartbeat configuration file. This is where you’ll configure your synthetic test suites.

run.sh provides the main docker run command that pulls the Elastic synthetics image and runs Heartbeat.

Step 2: Update heartbeat.docker.yml

edit

There are two ways to configure a synthetic test. Let’s take a quick look at each.

Run an inline test

If you’re running an inline, browser based test, you can use the traditional Heartbeat flow to completely configure your synthetic testing directly in heartbeat.docker.yml. An example is provided: 

heartbeat.monitors:
- type: browser
  id: my-monitor 
  name: My Monitor
  schedule: "@every 1m"
  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]');
    });

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.
Run a test suite

If you’d like to run multiple tests, you’d probably be better off creating a library of tests defined outside of heartbeat.docker.yml. This, for example, allows your tests to live with your application or in a separate Git repository. 

heartbeat.synthetic_suites: 
- name: Todos
  path: "/opt/examples/todos" 
  schedule: "@every 1m"

Specify the name, path, and schedule of your test suite.

In this example, our library of synthetic tests live in the /examples/todos directory of elastic/synthetics. Heartbeat will attempt to run all files in that directory with the extension .journey.ts or .journey.js. See Syntax for more information.

Step 3: Run run.sh

edit

run.sh pulls the Elastic/synthetics image, shares your configuration details and test suites with Heartbeat, and provides the location of your Elasticsearch instance.

Running a Chrome browser requires elevated privileges. Synthetic monitoring scripts can escape the docker container. It is recommend to run your tests on a separate box. Do not run any scripts that you don’t trust.

#...
docker run \
  --rm \
  --name=heartbeat \
  --user=heartbeat \
  --net=host \
  --security-opt seccomp=seccomp_profile.json \ 
  --volume="$(pwd)/heartbeat.docker.yml:/usr/share/heartbeat/heartbeat.yml:ro" \ 
  --volume="$(pwd)/../../:/opt/elastic-synthetics:rw" \ 
  $IMAGE \
  --strict.perms=false -e \
  $HEARTBEAT_ARGS
#...

Running a Chrome browser requires elevated privileges. Do not run any scripts that you don’t trust.

Provides your heartbeat.docker.yml file as a volume.

Provides the elastic-synthetics repo as a volume.

Use the following command to run the provided sample tests (or your own). Don’t forget to update the example with your Elasticsearch credentials.

sh run.sh 7.10.0 \
  '-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:

sh run.sh 7.10.0 \
  '-E output.elasticsearch.hosts=["localhost:9200"]' \
  '-E output.elasticsearch.username=elastic' \
  '-E output.elasticsearch.password=changeme'

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 »