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
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
git clone https://github.com/elastic/synthetics.git &&\ cd examples/docker
There are two files in
synthetics/examples/docker that you’ll need to edit:
Step 2: Update
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:
monitorgets 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
elastic/synthetics. Heartbeat will attempt to run all files in that directory with the extension
.journey.js. See Syntax for more information.
Step 3: Run
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.
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.2 \ -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.2 \ -E output.elasticsearch.hosts=["localhost:9200"] \ -E output.elasticsearch.username=elastic \ -E output.elasticsearch.password=changeme \
Step 4: View in Kibanaedit
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.
Now you can customize the provided Docker example with your own tests! See Syntax to learn more.