Migrate from the Elastic Synthetics integration
editMigrate from the Elastic Synthetics integration
editThis 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 Elastic Synthetics integration is a method for creating synthetic monitors that is no longer recommended.
You should not use the Elastic Synthetics integration to set up new monitors and should make a plan to migrate existing monitors to use either Project monitors or the Synthetics app:
- With Elastic Project monitors, you write tests in an external version-controlled project and use a CLI tool to push monitors to the Elastic Stack.
- The Synthetics app is an application in Kibana that you can use to configure and create monitors using a user interface.
Compare approaches
editBelow is a comparison of how you used the Elastic Agent integration to create monitors and how you’ll use the Synthetics app or projects to create monitors:
Elastic Agent integration | Projects or the Synthetics app | |
---|---|---|
Supported monitors |
Supported both lightweight and browser monitors |
Supports both lightweight and browser monitors |
Where monitors run (read more) |
You had to run monitors on your infrastructure. |
You can run monitors on both:
|
Where you configure monitors |
You could configure monitors using:
|
You can configure monitors using:
|
How to use projects (read more) |
|
Find more details in Use Project monitors. |
How to use the UI (read more) |
|
Find more details in Use the Synthetics app. |
Where monitors run
editIf you want to continue hosting on your infrastructure, you will need to create a
Private Location before creating monitors.
If you have already have an Elastic Agent running using elastic-agent-complete
,
you can add it as a new Private Location
in the Synthetics app.
To create a new Private Location from scratch, follow all instructions in
Monitor resources on private networks.
Alternatively, you can start hosting on Elastic’s global managed infrastructure. With Elastic’s global managed testing infrastructure, you can create and run monitors in multiple locations without having to manage your own infrastructure. Elastic takes care of software updates and capacity planning for you.
How to use projects
editIf you already have an external project you were adding via a ZIP URL you can use the same project, but you will have to make some changes.
First, upgrade the existing project to use the latest version of
@elastic/synthetics
:
-
Run
npm install -g @elastic/synthetics@latest
to install the latest version of the CLI. -
Upgrade your existing project to use new project settings:
-
Run
npm @elastic/synthetics init <path-to-existing-project>
. -
Respond to all prompts provided by the CLI.
To ensure that your project will work with the latest version of Elastic Synthetics, the CLI will create a new configuration file on
init
, but you will see a prompt asking if you would like to continue before overwriting an existing configuration file.
-
Run
-
Review updated files and directories, including:
-
journeys/
will contain sample journey code. Move existing journey files into this directory. -
synthetics.config.ts
will contain updated default settings needed for the upgraded project. -
package.json
will contain updated NPM settings for your project.If there is already a
package.json
file in the directory when you runinit
, the synthetics agent will not create a newpackage.json
file. Instead it will modify the existingpackage.json
file to:-
Add
@elastic/synthetics
library to the dependencies if it’s not already present. -
Add a
test
andpush
script if they are not already present.
-
Add
-
.github/
will contain sample workflow files to use with GitHub Actions.
-
Then, you can further configure monitors as needed. In the upgraded project, you’ll use code (instead of the Integrations UI) to define settings like the name of the monitor and the frequency at which it will run. There are two ways you can configure monitors using code:
-
For individual monitors, use
monitor.use
directly in the journey code. Read more in Configure individual monitors. - To configure all monitors at once, use the synthetics configuration file. Read more in Configure projects.
Finally, you’ll create monitors using push
instead of by adding a ZIP URL in
the Integrations UI. This will require an API token.
Read more in @elastic/synthetics push
.
Optionally, you can also add lightweight monitors to the project in YAML files. Read more about adding lightweight monitors to projects in Configure lightweight monitors.
For more information on getting started with projects, refer to Use Project monitors.
How to use the UI
editIf you created monitors solely via the Elastic Synthetics integration UI, you can recreate monitors in the Synthetics app.
The configuration options in the Synthetics app look very similar to the Elastic Synthetics integration UI with a few exceptions. In the Synthetics app:
- You will select one or more locations for each monitor.
- You cannot use a ZIP URL for browser monitors. Use projects instead.
- You can test the configuration (including the journey for browser monitors) using Run test before creating the monitor.
For more information on getting started with the Synthetics app, refer to Use the Synthetics app.