Quickstart: Synthetic monitoring via Docker
editQuickstart: Synthetic monitoring via Docker
editThis 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
editThis 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:
|
|
|
Step 2: Update heartbeat.docker.yml
editThere 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.Specify the name, path, and schedule of your test suite.
In this example, our library of synthetic tests live in the
/examples/todos
directory ofelastic/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
editrun.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 |
|
Provides the |
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
editThat’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
editNow you can customize the provided Docker example with your own tests! See Syntax to learn more.