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.
Heartbeat uses the
npx @elastic/synthetics command to run and report synthetic tests.
It can also be used locally to help develop your tests.
npx @elastic/synthetics [options] [files] [dir]
You will not need to use most command line flags — they have been implemented purely to interact with Heartbeat. However, there are some you may find useful. They are documented below.
- Prints debug info.
- Filters journey with the name or a matching tag.
- Filters journey with the given tag(s).
json. Use the JUnit reporter to provide easily parsed output to CI servers like Jenkins.
- Runs with the browser in headful mode.
Instead of reading from a file,
catinline scripted journeys and pipe them through
stdin. For example,
cat path/to/file.js | npx @elastic/synthetics --inline.
JSON object to pass in custom Playwright options for the agent.
Options passed will be merged with Playwright options defined in your synthetics.config.js file. Options defined via
- Captures screenshots for every step in the journey.
Shows help for the
Scaffold a new project using Elastic Synthetics.
This will create a template Node.js project that includes the synthetics agent, required dependencies, a synthetics configuration file, and example journey files. These journeys can be edited and then pushed to Kibana to create monitors.
npx @elastic/synthetics init <name-of-project>
Create monitors in Kibana by using your local journeys.
npx @elastic/synthetics push --auth <api-key> --url <kibana-url> --project <id|name>
API key used for Kibana authentication.
If you are pushing to a private location, you must use an API key generated in 8.4 or higher.
To create an API key, you must be logged into Kibana as a user with the following privileges:
Cluster privileges: At least one of
If using one or more public locations:
Allfor Synthetics and Uptime in the Observability section.
If using one or more private locations:
Allfor both Fleet and Integrations in the Management section.
- If using one or more public locations:
- Cluster privileges: At least one of
- The Kibana URL for the deployment to which you want to upload the monitors.
A unique id associated with your project.
It will be used for logically grouping monitors.
If you used
initto create a project, this is the
List all available locations for running synthetics monitors.
npx @elastic/synthetics locations --url <kibana-host> --auth <api-key>
npx @elastic/synthetics locations with no flags to list all the available global locations managed by Elastic for running synthetics monitors.
- The Kibana URL for the deployment from which to fetch all available public and private locations.
- API key used for Kibana authentication.