From 43095d4e94eff5b4f059170902e3fea11d3d8673 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 14 Jul 2023 10:38:05 -0500 Subject: [PATCH 1/5] add info on timezones --- .../synthetics-command-reference.asciidoc | 3 ++ .../synthetics-configuration.asciidoc | 43 +++++++++++++++++-- 2 files changed, 42 insertions(+), 4 deletions(-) diff --git a/docs/en/observability/synthetics-command-reference.asciidoc b/docs/en/observability/synthetics-command-reference.asciidoc index 2b5baaa410..bf4e27c3c0 100644 --- a/docs/en/observability/synthetics-command-reference.asciidoc +++ b/docs/en/observability/synthetics-command-reference.asciidoc @@ -42,6 +42,9 @@ 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 `--playwright-options` take precedence. ++ +For more details on relevant Playwright options, refer to the +<>. *`--screenshots `*:: Captures screenshots for every step in the journey. diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc index 6e3011991f..6e761b02ba 100644 --- a/docs/en/observability/synthetics-configuration.asciidoc +++ b/docs/en/observability/synthetics-configuration.asciidoc @@ -52,17 +52,52 @@ An object that defines any variables your tests require. [[synthetics-configuration-playwright-options]] = `playwrightOptions` -For available options, see the https://playwright.dev/docs/test-configuration[Playwright documentation]. +For all available options, refer to the https://playwright.dev/docs/test-configuration[Playwright documentation]. + +Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including timeouts, timezones, and device emulation. + +[discrete] +[[synthetics-configuration-playwright-options-timeouts]] +== Timeouts -[NOTE] -==== Playwright has two types of timeouts that are used in Elastic Synthetics: https://playwright.dev/docs/test-timeouts#action-and-navigation-timeouts[action and navigation timeouts]. Elastic Synthetics uses a default action and navigation timeout of 50 seconds. You can override this default using https://playwright.dev/docs/api/class-testoptions#test-options-action-timeout[`actionTimeout`] and https://playwright.dev/docs/api/class-testoptions#test-options-navigation-timeout[`navigationTimeout`] in `playwrightOptions`. -==== + +[discrete] +[[synthetics-configuration-playwright-options-timezones]] +== Timezones + +By default monitors will run in the ??? timezone, but you can specify a timezone in +`playwrightOptions` on a per monitor or global basis. + +To set the timezone for all monitors in the project, set https://playwright.dev/docs/emulation#locale--timezone[`locale` and `timezoneId`] +in the configuration file: + +[source,js] +---- +playwrightOptions: { + locale: 'en-AU', + timezoneId: 'Australia/Brisbane', +} +---- + +To set the timezone for a specific monitor, add these options to a journey using +<>. + +// Uncomment note when this is added to the Synthetics Service + +////// +[NOTE] +===== +The timezone can also be set using the {synthetics-app}. +If you specify a timezone in the configuration file or using `monitor.use` in the journey code, +that timezone with take precedence over the timezone set in the {synthetics-app}. +===== +////// [discrete] [[synthetics-config-device-emulation]] From f9f9ffd3beef1d2670e95a91b3eafe471dfbeaf9 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 14 Jul 2023 10:43:11 -0500 Subject: [PATCH 2/5] align cli and config docs --- .../synthetics-command-reference.asciidoc | 102 +++++++++++--- .../synthetics-configuration.asciidoc | 130 ++++++++++-------- 2 files changed, 153 insertions(+), 79 deletions(-) diff --git a/docs/en/observability/synthetics-command-reference.asciidoc b/docs/en/observability/synthetics-command-reference.asciidoc index bf4e27c3c0..d78b50e75e 100644 --- a/docs/en/observability/synthetics-command-reference.asciidoc +++ b/docs/en/observability/synthetics-command-reference.asciidoc @@ -21,38 +21,58 @@ 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`*:: +`--debug`:: Prints debug info. -*`--match `*:: +`--match `:: Filters journey with the name or a matching tag. -*`--tags `*:: +`--tags Array`:: Filters journey with the given tag(s). -*`--reporter`*:: +`--reporter `:: One of `junit`, `default`, or `json`. Use the JUnit reporter to provide easily parsed output to CI servers like Jenkins. -*`--inline`*:: +`--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 `*:: +`--params `:: +A JSON object that defines any variables your tests require. +Read more in <>. ++ +Params passed will be merged with params defined in your +<>. +Params defined via the CLI take precedence. + +`--playwright-options `:: 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. +For available options, see the https://playwright.dev/docs/test-configuration[Playwright documentation]. ++ +Options passed will be merged with Playwright options defined in your +<>. +Options defined via the CLI take precedence. + For more details on relevant Playwright options, refer to the <>. -*`--screenshots `*:: -Captures screenshots for every step in the journey. +`--screenshots `:: +Control whether or not to capture screenshots. +Options include `'on'`, `'off'`, or `'only-on-failure'`. ++ +This can also be set in the configuration file using +<>. +The value defined via the CLI will take precedence. -*`--no-throttling`*:: +`--no-throttling`:: Does not apply throttling. ++ +Throttling can also be disabled in the configuration file using +<>. +The value defined via the CLI will take precedence. -*`-h, --help`*:: +`-h, --help`:: Shows help for the `npx @elastic/synthetics` command. [discrete] @@ -104,7 +124,7 @@ However there are some limitations when using external packages: * Native node modules will not work as expected due to platform inconsistency. ==== -`--auth`:: +`--auth `:: API key used for {kibana-ref}/api-keys.html[{kib} authentication]. + If you are pushing to a <>, you must use an API key generated in 8.4 or higher. @@ -112,13 +132,57 @@ If you are pushing to a <>, you must use a To create an API key, you must be logged into {kib} as a user with the privileges described in <>. -`--url`:: -The {kib} URL for the deployment to which you want to upload the monitors. - -`--project`:: +`--project `:: A unique id associated with your project. It will be used for logically grouping monitors. ++ If you used <>, this is the `` you specified. ++ +This can also be set in the configuration file using +<>. +The value defined via the CLI will take precedence. + +`--url `:: +The {kib} URL for the deployment to which you want to upload the monitors. ++ +This can also be set in the configuration file using +<>. +The value defined via the CLI will take precedence. + +`--space `:: +The identifier of the target {kibana-ref}/xpack-spaces.html[{kib} space] for the pushed monitors. +Spaces help you organize pushed monitors. +Defaults to `default`. ++ +This can also be set in the configuration file using +<>. +The value defined via the CLI will take precedence. + +`--schedule `:: +The interval (in minutes) at which the monitor should run. ++ +This can also be set in the configuration file using +<>. +The value defined via the CLI will take precedence. + +https://github.com/elastic/synthetics/blob/{synthetics_version}/src/locations/public-locations.ts#L28-L37[`--locations Array`]:: +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, refer to <>. ++ +Locations passed will be merged with locations defined in your +<> and +<> in individual journey files. + +`--private-locations Array`:: +The <> to which the monitors will be deployed. These {private-location}s 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-location}s, refer to <>. ++ +{private-location}s passed will be merged with {private-location}s defined in your +<> and +<> in individual journey files. `--yes`:: The `push` command includes interactive prompts to prevent you from accidentally deleting or duplicating monitors. @@ -145,8 +209,8 @@ Run `npx @elastic/synthetics locations` with no flags to list all the available To list both locations on Elastic's global managed infrastructure and {private-locations}, include: -`--url`:: +`--url `:: The {kib} URL for the deployment from which to fetch all available public and {private-location}s. -`--auth`:: +`--auth `:: API key used for {kibana-ref}/api-keys.html[{kib} authentication]. diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc index 6e761b02ba..7b3cf3035d 100644 --- a/docs/en/observability/synthetics-configuration.asciidoc +++ b/docs/en/observability/synthetics-configuration.asciidoc @@ -13,31 +13,53 @@ in Playwright-specific methods, for example, `ignoreHTTPSErrors`, `extraHTTPHead [[synthetics-config-file]] Create a `synthetics.config.js` or `synthetics.config.ts` file in the root of the -synthetics project and specify the options: +synthetics project and specify the options. For example: -[source,js] +[source,ts] ---- -import { SyntheticsConfig } from '@elastic/synthetics' - -const config: SyntheticsConfig = { - params: { - url: 'https://www.elastic.co' - }, - playwrightOptions: { - ignoreHTTPSErrors: true, // ignores all HTTPS errors during navigation - extraHTTPHeaders: { - 'foo': 'bar' // additional HTTP headers to be sent with every request - } - }, - monitor: { - schedule: 10, - locations: [ 'us-east4-a' ], +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-east4-a' ], + }, + /** + * 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 = "" + */ } -} - -export default config; + return config; +}; ---- +[NOTE] +===== +`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 <> documentation. @@ -46,58 +68,26 @@ the tests based on environments, look at the <>. [discrete] [[synthetics-configuration-playwright-options]] = `playwrightOptions` -For all available options, refer to the https://playwright.dev/docs/test-configuration[Playwright documentation]. - -Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including timeouts, timezones, and device emulation. - -[discrete] -[[synthetics-configuration-playwright-options-timeouts]] -== Timeouts +For available options, see the https://playwright.dev/docs/test-configuration[Playwright documentation]. +// tag::timeouts[] +[NOTE] +==== Playwright has two types of timeouts that are used in Elastic Synthetics: https://playwright.dev/docs/test-timeouts#action-and-navigation-timeouts[action and navigation timeouts]. Elastic Synthetics uses a default action and navigation timeout of 50 seconds. You can override this default using https://playwright.dev/docs/api/class-testoptions#test-options-action-timeout[`actionTimeout`] and https://playwright.dev/docs/api/class-testoptions#test-options-navigation-timeout[`navigationTimeout`] in `playwrightOptions`. - -[discrete] -[[synthetics-configuration-playwright-options-timezones]] -== Timezones - -By default monitors will run in the ??? timezone, but you can specify a timezone in -`playwrightOptions` on a per monitor or global basis. - -To set the timezone for all monitors in the project, set https://playwright.dev/docs/emulation#locale--timezone[`locale` and `timezoneId`] -in the configuration file: - -[source,js] ----- -playwrightOptions: { - locale: 'en-AU', - timezoneId: 'Australia/Brisbane', -} ----- - -To set the timezone for a specific monitor, add these options to a journey using -<>. - -// Uncomment note when this is added to the Synthetics Service - -////// -[NOTE] -===== -The timezone can also be set using the {synthetics-app}. -If you specify a timezone in the configuration file or using `monitor.use` in the journey code, -that timezone with take precedence over the timezone set in the {synthetics-app}. -===== -////// +==== +// end::timeouts[] [discrete] [[synthetics-config-device-emulation]] @@ -120,6 +110,26 @@ const config: SyntheticsConfig = { export default config; ---- +[discrete] +[[synthetics-configuration-project]] += `project` + +Information about the project. + +id (`string`):: +A unique id associated with your project. +It will be used for logically grouping monitors. ++ +If you used <>, this is the `` you specified. + +url (`string`):: +The {kib} URL for the deployment to which you want to upload the monitors. + +space (`string`):: +The identifier of the target {kibana-ref}/xpack-spaces.html[{kib} space] for the pushed monitors. +Spaces help you organize pushed monitors. +Defaults to `default`. + [discrete] [[synthetics-configuration-monitor]] = `monitor` From efe76e07ba6c871e62deb896f7a83b28de24e866 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 14 Jul 2023 10:49:34 -0500 Subject: [PATCH 3/5] locations don't get merged --- .../synthetics-command-reference.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/en/observability/synthetics-command-reference.asciidoc b/docs/en/observability/synthetics-command-reference.asciidoc index d78b50e75e..19a23de3e1 100644 --- a/docs/en/observability/synthetics-command-reference.asciidoc +++ b/docs/en/observability/synthetics-command-reference.asciidoc @@ -170,9 +170,9 @@ Where to deploy the monitor. Monitors can be deployed in multiple locations so t + To list available locations, refer to <>. + -Locations passed will be merged with locations defined in your -<> and -<> in individual journey files. +This can also be set in the configuration file using +<>. +The value defined via the CLI will take precedence. `--private-locations Array`:: The <> to which the monitors will be deployed. These {private-location}s refer to locations hosted and managed by you, whereas @@ -180,9 +180,9 @@ The <> to which the monitors wi + To list available {private-location}s, refer to <>. + -{private-location}s passed will be merged with {private-location}s defined in your -<> and -<> in individual journey files. +This can also be set in the configuration file using +<>. +The value defined via the CLI will take precedence. `--yes`:: The `push` command includes interactive prompts to prevent you from accidentally deleting or duplicating monitors. From a613d80e45968576c35026fcc877285c37917551 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Fri, 14 Jul 2023 18:27:19 -0500 Subject: [PATCH 4/5] remove debug flag --- docs/en/observability/synthetics-command-reference.asciidoc | 3 --- 1 file changed, 3 deletions(-) diff --git a/docs/en/observability/synthetics-command-reference.asciidoc b/docs/en/observability/synthetics-command-reference.asciidoc index 19a23de3e1..2a484decc7 100644 --- a/docs/en/observability/synthetics-command-reference.asciidoc +++ b/docs/en/observability/synthetics-command-reference.asciidoc @@ -21,9 +21,6 @@ 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 `:: Filters journey with the name or a matching tag. From bf059a22ac942bd0fec49f8468197687683aa4a2 Mon Sep 17 00:00:00 2001 From: Colleen McGinnis Date: Tue, 18 Jul 2023 19:59:50 -0500 Subject: [PATCH 5/5] address feedback --- .../observability/synthetics-command-reference.asciidoc | 8 +++++++- docs/en/observability/synthetics-configuration.asciidoc | 2 +- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/en/observability/synthetics-command-reference.asciidoc b/docs/en/observability/synthetics-command-reference.asciidoc index 2a484decc7..1553cf0ed3 100644 --- a/docs/en/observability/synthetics-command-reference.asciidoc +++ b/docs/en/observability/synthetics-command-reference.asciidoc @@ -72,6 +72,12 @@ The value defined via the CLI will take precedence. `-h, --help`:: Shows help for the `npx @elastic/synthetics` command. +[NOTE] +===== +For debugging synthetic tests locally, you can set an environment variable, +`DEBUG=synthetics`, to capture Synthetics agent logs when running `npx @elastic/synthetics`. +===== + [discrete] [[elastic-synthetics-init-command]] = `@elastic/synthetics init` @@ -149,7 +155,7 @@ The value defined via the CLI will take precedence. `--space `:: The identifier of the target {kibana-ref}/xpack-spaces.html[{kib} space] for the pushed monitors. Spaces help you organize pushed monitors. -Defaults to `default`. +Pushes to the "default" space if not specified. + This can also be set in the configuration file using <>. diff --git a/docs/en/observability/synthetics-configuration.asciidoc b/docs/en/observability/synthetics-configuration.asciidoc index 7b3cf3035d..0b096d02a1 100644 --- a/docs/en/observability/synthetics-configuration.asciidoc +++ b/docs/en/observability/synthetics-configuration.asciidoc @@ -128,7 +128,7 @@ The {kib} URL for the deployment to which you want to upload the monitors. space (`string`):: The identifier of the target {kibana-ref}/xpack-spaces.html[{kib} space] for the pushed monitors. Spaces help you organize pushed monitors. -Defaults to `default`. +Pushes to the "default" space if not specified. [discrete] [[synthetics-configuration-monitor]]