Browser options
editBrowser options
editWant to get started with synthetic monitoring? See the quick start guide.
While it is possible to configure browser monitors via the heartbeat YAML config files, we highly recommend using project monitors instead! See the Elastic synthetics docs.
[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. The options described here configure Heartbeat to run the synthetic monitoring test projects via Synthetic Agent on the Chromium browser. Additional shared options are defined in Common monitor options.
Browser based monitors can only be run in our Heartbeat docker image,
or via the elastic-agent-complete
docker image.
For more information, see Synthetic monitoring using Docker.
Example configuration:
- type: browser id: synthetic-inline-tests name: Elastic website 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]'); });
source
editContains information on how to run synthetic tests.
inline
editWhile inline
browser monitors are still supported, we highly encourage trying project monitors instead. See the Elastic synthetics docs.
Runs the Synthetic test scripts that are defined inline in the configuration. See Synthetics syntax for more information.
This is the most convenient way to get Synthetic tests up and running, however, it becomes harder to maintain and share code as the number of test files increases. The recommended way to run Synthetic tests is to create an NPM project and start writing individual tests for all the user journeys and save them as JavaScript or TypeScript files. Once the project is created, the tests can be invoked either by Zip Url or Local directory method.
Heartbeat will use the latest compatible version(^1.0.0) of the Synthetics NPM library to run the inline journeys.
Zip URL
(Deprecated)
editZip URL monitors are now deprecated! Please use project monitors instead. See the Elastic synthetics docs.
Remote zip endpoint configuration allows users to specify the location of a synthetics test project ZIP file.
Under zip_url
, specify these options:
-
url
- Location of the synthetics project repository.
-
folder
- Relative directory path where the synthetic journey files are located in the repository.
-
username
- The username for authenticating with the zip endpoint. This setting is optional.
-
password
- The password for authenticating with the zip endpoint. This setting is optional.
-
ssl
- SSL options applied to downloading the zip, not the browser. See SSL for more details.
If username
and password
are provided, they will be sent as HTTP Basic Authentication
headers to the remote zip endpoint.
Example configuration:
- type: browser id: todos-project name: Todos Journeys schedule: '@every 1m' source: zip_url: url: "https://github.com/elastic/synthetics/archive/refs/heads/master.zip" folder: "examples/todos" username: "" password: "" # ssl options apply to downloading the zip, not the browser #ssl: # certificate_authorities: ['/etc/ca.crt']
Local directory
(Deprecated)
editLocal browser monitors are now deprecated! Please use project monitors instead. See the Elastic synthetics docs.
Local directory where the synthetic test files are located.
Example configuration:
- type: browser id: local-journeys name: Local journeys schedule: '@every 1m' source: local: path: "/path/to/synthetics/journeys"
params
editSet this option to add user defined parameters for your scripts. This value takes
arbitrary YAML that is then converted to JSON which is then passed into synthetics
via the --params
option. See Working with Params
for more information.
Example:
- type: browser id: local-journeys name: Local journeys schedule: '@every 1m' source: # Omitted in this example for brevity params: root_url: http://example.net my_custom_object: a_key: ["a value"]
screenshots
editSet this option to manage the screenshots captured by the synthetics agent.
Under screenshots
, specify one of these options:
-
on
- capture screenshots for all steps in a journey (default)
-
off
- do not capture any screenshots
-
only-on-failure
- capture screenshots for all steps when a journey fails (any failing step marks the whole journey as failed)
Example configuration:
- type: browser id: local-journeys name: Local journeys schedule: '@every 1m' screenshots: "on" source: local: path: "/path/to/synthetics/journeys"
ignore_https_errors
editSet this option to true
to disable TLS/SSL validation in the synthetics browser. This is useful for testing
sites that use self-signed certs. This option can also be used to test certs from non-standard CAs,
though you will no longer get errors if there is anything wrong with the certificate.
sandbox
editSet this option to true
to enable the normally disabled chromium sandbox.
Defaults to false.
throttling
editSet this option to control the network throttling. By default, all journeys are run with 5Mbps download, 3Mbps upload and 20ms latency which emulates a standard Cable connection.
Users can control the throttling parameters, Below is an example of emulating a 3G connection with 1.6Mbps download, 750Kbps upload and 150ms round trip time in two different supported formats.
- type: browser schedule: '@every 1m' throttling: download: 1.6 upload: 0.75 latency: 150
- type: browser schedule: '@every 1m' throttling: "1.6d/0.75u/150l"
Network throttling can be completely disabled by passing false
- type: browser schedule: '@every 1m' throttling: false
filter_journeys
editSet this option to filter journeys based on journey tags and names.
Example configuration:
- type: browser id: local-journeys name: Local journeys schedule: '@every 1m' filter_journeys: tags: ["browse", "checkout"] match: "login*" source: local: path: "/path/to/synthetics/journeys"
-
tags
- run only journeys with the given tag(s), or globs
-
match
- run only journeys with a name or tags that matches the configured glob
playwright_options
editA map of extra options to pass in to the synthetics agent. These are used as the context for the Playwright browser object. See the playwright browser context docs for more information.
synthetics_args
editExtra arguments to pass to the synthetics agent package. Takes a list of strings.
Run Once Mode (Experimental)
editYou can configure Heartbeat run monitors exactly once then exit, bypassing the scheduler. This is referred to as running Heartbeat in
"run once" mode by setting heartbeat.run_once: true
. All Heartbeat monitors will ignore their schedules and run exactly once at startup.
This is an experimental feature and is subject to change.
Note, the schedule
field is still required and is used by Heartbeat to set the expectation around when
the next run will occur. That duration is encoded in the monitor.timespan
field in the Heartbeat output.
# heartbeat.yml heartbeat.run_once: true heartbeat.monitors: # your monitor config here...