IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
Elastic Docs ›Observability Guide [8.3] ›Uptime and synthetic monitoring ›Use synthetic monitors
« Write a synthetic test Manage synthetic monitors »

Create a synthetic monitoredit

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.

Once you’ve written a synthetic test, you can create a monitor to run the test at a regular interval.

Choose an approachedit

There are three ways to create a browser monitor: project monitors, Heartbeat, and Elastic Agent.

Heartbeatedit

Use Heartbeat to configure and create browser monitors similar to how you would set up any other type of monitor.

Read more about the benefits of this approach in the setup guide’s Heartbeat section.

When using this approach to create multiple monitors from a project, all monitors will use a single configuration.

Project monitorsedit

Use the @elastic/synthetics library’s push command to create monitors. Pushing your project creates a new browser monitor in Kibana for each journey in the project. Using the push command allows you to manage all browser monitors using a GitOps workflow.

Alternatively, you could keep monitors in sync directly from your local development environment.

We recommend users adopt a GitOps workflow when using project monitors because it allows teams to keep their monitors in sync with their project’s main branch. Besides saving time through automation, a GitOps workflow allows users to take advantage of PR reviews and checks that could validate journeys even before they are merged.

Project monitors also allow teams to configure individual monitors through code. Instead of using Kibana to update a monitor’s schedule, for example, you can set a schedule directly in your journey. That schedule will be used when pushing the journey to Kibana.

To configure default settings, you can use a global Synthetics configuration file.

Unlike the other approaches, this method can only be used to create browser monitors.

Elastic Agentedit

Use Elastic Agent to configure and create browser monitors similarly to how you would set up any other type of monitor.

Read more about the benefits of this approach in the setup guide’s Elastic Agent section.

When using this approach to create multiple monitors from a project, all monitors will use a single configuration.

Configure monitoredit

When you’re ready to create a browser monitor to run your tests, you’ll need to set a few configuration options:

  • Give your monitor a name. Provide a human readable name and a unique ID for the monitor. This will appear in Kibana where you can view and manage monitors after they’re created.
  • Set the schedule. Specify the interval at which your tests will run.
  • Specify where to find the tests. This will vary based on the method you use to create a monitor.
  • Set other options as needed. There are several other options you can set to customize your implementation including params, tags, screenshot options, throttling options, and more.

If you used Heartbeat to set up monitors, configure the monitor in heartbeat.yml. Use source to specify where to find the tests you want to run. For example:

- name: Todos
  id: todos
  type: browser
  schedule: "@every 1m"
  params:
    target_url: "https://elastic.github.io/synthetics-demo/" 
  source:
    zip_url: 
      url: "https://github.com/elastic/synthetics-demo/archive/refs/heads/main.zip" 
      folder: "todos/synthetics-tests" 
      username: "" 
      password: ""

The params section lets you define custom parameters to use in your script. In this example the target_url parameter is used by the project to determine which site to test.

In this example, our library of synthetic tests is downloaded from the remote zip endpoint for our todos example.

Note that the url refers to the endpoint where the test project exists.

Folder refers to the relative path where the synthetic journey files are located. Heartbeat will invoke the synthetics library on this folder.

Username and password are blank here, but if provided, will be sent as HTTP Basic Authentication headers to the remote zip endpoint.

For a list of all available configuration options, see Browser options in the Heartbeat documentation.

Create monitor in Kibanaedit

After you’ve decided how you want to configure your monitor, you’re ready to create the monitor and start collecting data. Push the monitors to Kibana using one of the following methods:

If you used Heartbeat to set up monitors, save changes to your heartbeat.yml file and make sure you’ve completed Connect to the Elastic Stack.

Run on CIedit

You can also run a synthetic project on your CI environment. Elastic’s synthetics runner can output results in a few different formats, including JSON and JUnit (the standard format supported by most CI platforms).

If any of your journeys fail, the synthetics agent it will yield a non-zero exit code, which most CI systems pick up as a failure by default.

You can see an example using GitHub Actions in the elastic/synthetics-demo repository. This example sets up a job that executes the synthetics runner and tells the runner to yield results in a JUnit format.

Create an inline monitoredit

Alternatively, you can create an inline monitor.

An inline monitor is a single journey that you manage individually. Inline monitors can be quick to set up, but can also be more difficult to manage. Each inline monitor can contain only one journey, which must be maintained directly in Kibana or in your Heartbeat configuration file.

If you depend on external packages, have your journeys next to your code repository, or wish to embed and manage more than one journey from a single monitor configuration, see Configure monitor instead.

When writing an inline monitor, the journey keyword isn’t required, and variables like page and params will be part of your script’s scope. To create an inline monitor, copy the steps from inside a journey and paste them into your Elastic Synthetics integration or heartbeat.yml depending on the approach you chose to set up.

Copy and paste your test steps into heartbeat.yml. Heartbeat spawns a separate Node.js process, schedules your tests, and runs them on a Chromium browser.

For a full list of configuration options, see Browser options in the Heartbeat documentation.

- type: browser
  id: elastic-website 
  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]');
      });

Each monitor gets its own ID in the Uptime app and its own schedule entry. This allows tests to be run in parallel and analyzed separately.

In this example, a synthetic journey is defined inline. This is a two-step script that first loads a homepage and then hovers over a product menu. See Write a synthetic test for more information.
« Write a synthetic test Manage synthetic monitors »