Configure Synthetics projects
editConfigure Synthetics projects
editSynthetic tests support the configuration of dynamic parameters that can be
used in projects. In addition, the Synthetics agent, which is built on top
of Playwright, supports configuring browser and context options that are available
in Playwright-specific methods, for example, ignoreHTTPSErrors
, extraHTTPHeaders
, and viewport
.
Create a synthetics.config.js
or synthetics.config.ts
file in the root of the
synthetics project and specify the options. For example:
import type { SyntheticsConfig } from '@elastic/synthetics'; export default env => { const config: SyntheticsConfig = { params: { url: 'https://www.elastic.co', }, playwrightOptions: { ignoreHTTPSErrors: false, }, /** * Configure global monitor settings */ monitor: { schedule: 10, locations: [ 'us_east' ], }, /** * Project monitors settings */ project: { id: 'my-project', url: 'https://abc123', space: 'custom-space', }, }; if (env !== 'development') { /** * Override configuration specific to environment * For example, config.params.url = "" */ } return config; };
env
in the example above is the environment you are pushing from
not the environment where monitors will run. In other words, env
corresponds to the configured NODE_ENV
.
The configuration file can either export an object, or a function that when called should return the generated configuration. To know more about configuring the tests based on environments, look at the dynamic configuration documentation.
params
editA JSON object that defines any variables your tests require. Read more in Work with params and secrets.
playwrightOptions
editFor all available options, refer to the Playwright documentation.
Do not attempt to run in headful mode (using headless:false
) when running through Elastic’s global managed testing infrastructure or Private Locations as this is not supported.
Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including TLS client authentication, timeouts, timezones, and device emulation.
TLS client authentication
editTo enable TLS client authentication, set the clientCertificates
option in the configuration file:
Path-based options {certPath, keyPath, pfxPath}
are only supported on Private Locations, defer to in-memory alternatives {cert, key, pfx}
when running on locations hosted by Elastic.
playwrightOptions: { clientCertificates: [ { origin: 'https://example.com', certPath: './cert.pem', keyPath: './key.pem', passphrase: 'mysecretpassword', }, { origin: 'https://example.com', cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."), key: Buffer.from("-----BEGIN RSA PRIVATE KEY-----\n..."), passphrase: 'mysecretpassword', } ], }
When using Synthetics monitor UI, cert
, key
and pfx
can simply be specified using a string literal:
clientCertificates: [ { cert: "-----BEGIN CERTIFICATE-----\n...", // Not cert: Buffer.from("-----BEGIN CERTIFICATE-----\n..."), } ],
Timeouts
editPlaywright has two types of timeouts that are used in Elastic Synthetics: action and navigation timeouts.
Elastic Synthetics uses a default action and navigation timeout of 50 seconds.
You can override this default using actionTimeout
and navigationTimeout
in playwrightOptions
.
Timezones and locales
editThe Elastic global managed testing infrastructure does not currently set the timezone.
For Private Locations, the monitors will use the timezone of the host machine running
the Elastic Agent. This is not always desirable if you want to test how a web application
behaves across different timezones. To specify what timezone to use when the monitor runs,
you can use playwrightOptions
on a per monitor or global basis.
To use a timezone and/or locale for all monitors in the project, set
locale
and/or timezoneId
in the configuration file:
playwrightOptions: { locale: 'en-AU', timezoneId: 'Australia/Brisbane', }
To use a timezone and/or locale for a specific monitor, add these options to a
journey using monitor.use
.
Device emulation
editUsers can emulate a mobile device using the configuration file. The example configuration below runs tests in "Pixel 5" emulation mode.
import { SyntheticsConfig } from "@elastic/synthetics" import { devices } from "playwright-chromium" const config: SyntheticsConfig = { playwrightOptions: { ...devices['Pixel 5'] } } export default config;
project
editInformation about the project.
-
id (
string
) -
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. -
url (
string
) - The Kibana URL for the deployment to which you want to upload the monitors.
-
space (
string
) - The identifier of the target Kibana space for the pushed monitors. Spaces help you organize pushed monitors. Pushes to the "default" space if not specified.
monitor
editDefault values to be applied to all monitors when using the @elastic/synthetics
push
command.
-
id
(string
) - A unique identifier for this monitor.
-
name
(string
) - A human readable name for the monitor.
-
tags
(Array<string>
) - A list of tags that will be sent with the monitor event. Tags are displayed in the Synthetics app and allow you to search monitors by tag.
-
schedule
(number
) - The interval (in minutes) at which the monitor should run.
-
enabled
(boolean
) - Enable or disable the monitor from running without deleting and recreating it.
-
locations
(Array<SyntheticsLocationsType>
) -
Where to deploy the monitor. Monitors can be deployed in multiple locations so that you can detect differences in availability and response times across those locations.
To list available locations you can:
-
Run the
elastic-synthetics locations
command. - Go to Synthetics → Management and click Create monitor. Locations will be listed in Locations.
-
Run the
-
privateLocations
(Array<string>
) -
The Private Locations to which the monitors will be deployed. These Private Locations refer to locations hosted and managed by you, whereas
locations
are hosted by Elastic. You can specify a Private Location using the location’s name.To list available Private Locations you can:
-
Run the
elastic-synthetics locations
command with the Kibana URL for the deployment from which to fetch available locations. - Go to Synthetics → Management and click Create monitor. Private Locations will be listed in Locations.
-
Run the
-
throttling
(boolean
|ThrottlingOptions
) -
Control the monitor’s download speeds, upload speeds, and latency to simulate your application’s behavior on slower or laggier networks. Set to
false
to disable throttling altogether. -
screenshot
(ScreenshotOptions
) -
Control whether or not to capture screenshots. Options include
'on'
,'off'
, or'only-on-failure'
. -
alert.status.enabled
(boolean
) - Enable or disable monitor status alerts. Read more about alerts in Alerting.
-
retestOnFailure
(boolean
) -
Enable or disable retesting when a monitor fails. Default is
true
.By default, monitors are automatically retested if the monitor goes from "up" to "down". If the result of the retest is also "down", an error will be created, and if configured, an alert sent. Then the monitor will resume running according to the defined schedule. Using
retestOnFailure
can reduce noise related to transient problems. -
fields
(object
) -
A list of key-value pairs that will be sent with each monitor event. The
fields
are appended to Elasticsearch documents aslabels
, and those labels are displayed in Kibana in the Monitor details panel in the individual monitor’s Overview tab.For example:
fields: { foo: 'bar', team: 'synthetics', }
For information on configuring monitors individually, refer to:
- Configure individual monitors for browser monitors
- Configure lightweight monitors for lightweight monitors