Elastic Docs ›Elastic Observability [8.8] ›Synthetic monitoring
« Monitor resources on private networks Configure Synthetics projects »

Use the Synthetics CLIedit

@elastic/syntheticsedit

The Synthetics app 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 the Synthetics app. However, there are some you may find useful:

--debug
Prints debug info.
--match <name>
Filters journey with the name or a matching tag.
--tags <name...>
Filters journey with the given tag(s).
--reporter
One of junit, default, or json. Use the JUnit reporter to provide easily parsed output to CI servers like Jenkins.
--inline
Instead of reading from a file, cat inline scripted journeys and pipe them through stdin. For example, cat path/to/file.js | npx @elastic/synthetics --inline.
--playwright-options <jsonstring>
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 --playwright-options take precedence.
--screenshots <on|off|only-on-failure>
Captures screenshots for every step in the journey.
--no-throttling
Does not apply throttling.
-h, --help
Shows help for the npx @elastic/synthetics command.

@elastic/synthetics initedit

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>

Read more about what’s included in a template project in Create a project.

@elastic/synthetics pushedit

Create monitors in Kibana by using your local journeys.

npx @elastic/synthetics push --auth <api-key> --url <kibana-url> --project <id|name>

The push command includes interactive prompts to prevent you from accidentally deleting or duplicating monitors. You will see a prompt when:

  • You push a project that used to contain one or more monitors but no longer contains any monitors. Select yes to delete all monitors associated with the project ID being pushed.
  • You push a project that’s already been pushed using one project ID and then try to push it using a different ID. Select yes to create duplicates of all monitors in the project.

If the journey contains external NPM packages other than the @elastic/synthetics, those packages will be bundled along with the journey code when the push command is invoked. However there are some limitations when using external packages:

  • Bundled journeys after compression should not be more than 800 Kilobytes.
  • Native node modules will not work as expected due to platform inconsistency.
--auth

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 privileges described in Writer role.

--url
The Kibana URL for the deployment to which you want to upload the monitors.
--project
A unique id associated with your project. It will be used for logically grouping monitors. If you used init to create a project, this is the <name-of-project> you specified.
--yes

The push command includes interactive prompts to prevent you from accidentally deleting or duplicating monitors. If running the CLI non-interactively, you can override these prompts using the --yes option. When the --yes option is passed to push:

  • If you push a project that used to contain one or more monitors but no longer contains any monitors, all monitors associated with the project ID being pushed will be deleted.
  • If you push a project that’s already been pushed using one project ID and then try to push it using a different ID, it will create duplicates of all monitors in the project.

@elastic/synthetics locationsedit

List all available locations for running synthetics monitors.

npx @elastic/synthetics locations --url <kibana-host> --auth <api-key>

Run npx @elastic/synthetics locations with no flags to list all the available global locations managed by Elastic for running synthetics monitors.

To list both locations on Elastic’s global managed infrastructure and {private-locations}, include:

--url
The Kibana URL for the deployment from which to fetch all available public and Private Locations.
--auth
API key used for Kibana authentication.
« Monitor resources on private networks Configure Synthetics projects »