Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add documentation clarification #3382

Merged
merged 5 commits into from
Nov 28, 2023
Merged

Add documentation clarification #3382

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
3cbeeda
Update how hosts and ports are configured
paulb-elastic Nov 23, 2023
5035329
Add that monitors cannot be run headful
paulb-elastic Nov 23, 2023
fe1027e
Simplified wording following feedback
paulb-elastic Nov 24, 2023
b65b224
fix build
colleenmcginnis Nov 27, 2023
7697a53
Feedback from Colleen
paulb-elastic Nov 27, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions docs/en/observability/synthetics-configuration.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,11 @@ Read more in <<synthetics-params-secrets>>.

For all available options, refer to the https://playwright.dev/docs/test-configuration[Playwright documentation].

[NOTE]
====
Synthetics will always run browser monitors in headless mode (it is not possible to configure them to run in headful mode, even if setting Playwright options).
Copy link
Contributor

@lucabelluccini lucabelluccini Nov 23, 2023 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would have said "even forcing headless:false via Playwright options, we do not support running browser monitors in headful mode".

Maybe, can share an hint of passing a user agent like here if really needed? https://github.com/elastic/synthetics/blob/d33d899bafa686da0b547afd2145db51b411ed1b/examples/todos/synthetics.config.ts#L12

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@lucabelluccini I thought the confusion was originally because someone was specifically trying to run in headful mode - were they doing this because they wanted a non headless UA string then?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I do not have the whole detail about it, we can check together in Slack

====

Below are details on a few Playwright options that are particularly relevant to Elastic Synthetics including timeouts, timezones, and device emulation.

[discrete]
Expand Down
5 changes: 5 additions & 0 deletions docs/en/observability/synthetics-create-test.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -167,6 +167,11 @@ Use Playwright to simulate and validate user workflows including:

Visit the https://playwright.dev/docs[Playwright documentation] for information.

[NOTE]
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a bit confusing for me, I've used headful mode for debugging on synthetics cli, shouldn't this specifically refer to Elastic hosted synthetics service/heartbeat monitors instead?

Running headful locally used to be supported. IMO, it should still be

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@emilioalvap that's correct, it is still possible via the CLI, which is why I didn't add the note there

I also specifically mentioned ...run browser monitors... to try and distinguish this as the monitor (not running the journey locally for debugging purposes), but it sounds like this was still confusing. I didn't want to add a link here to the CLI saying it was still possible, as I thought it would get too confusing, but do you think that would help then?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the wording on the CLI specific page is quite detailed, I'd replicate that here:

Do not attempt to run in headful mode when running through Elastic’s global managed testing infrastructure or Private Locations as this is not supported.

IMO, this page is more generic than the CLI one to simply state that headful mode is not supported, it might be confusing for users as well.

====
Synthetics will always run browser monitors in headless mode (it is not possible to configure them to run in headful mode, even if setting Playwright options).
====

However, not all Playwright functionality should be used with Elastic Synthetics.
In some cases, there are alternatives to Playwright functionality built into the
Elastic Synthetics library. These alternatives are designed to work better for
Expand Down
6 changes: 3 additions & 3 deletions docs/en/observability/synthetics-reference/lightweight-config/http.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,8 +6,8 @@

// hosts
| [[monitor-http-hosts]] *`hosts`*
(list of <<synthetics-lightweight-data-string,string>>s)
a| *Required*. A list of URLs to ping.
(<<synthetics-lightweight-data-string,string>>)
a| *Required*. The URL to ping.

////////////////////////
max_redirects
Expand Down Expand Up @@ -70,7 +70,7 @@ a| The TLS/SSL connection settings for use with the HTTPS endpoint. If you don't
- type: http
id: my-http-service
name: My HTTP Service
hosts: ["https://myhost:443"]
hosts: "https://myhost:443"
schedule: '@every 5s'
ssl:
certificate_authorities: ['/etc/ca.crt']
Expand Down
6 changes: 3 additions & 3 deletions docs/en/observability/synthetics-reference/lightweight-config/icmp.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,14 +6,14 @@

// hosts
| [[monitor-icmp-hosts]] *`hosts`*
(list of <<synthetics-lightweight-data-string,string>>s)
a| *Required*. A list of hosts to ping.
(<<synthetics-lightweight-data-string,string>>)
a| *Required*. The host to ping.

*Example*:

[source,yaml]
----
hosts: ["myhost"]
hosts: "myhost"
----

////////////////////////
Expand Down
28 changes: 5 additions & 23 deletions docs/en/observability/synthetics-reference/lightweight-config/tcp.asciidoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,11 +6,8 @@

// hosts
| [[monitor-tcp-hosts]] *`hosts`*
(list of <<synthetics-lightweight-data-string,string>>s)
a| *Required*. A list of hosts to ping. The entries in the list can be:

* *A plain host name, such as `localhost`, or an IP address.*
If you specify this option, you must also specify a value for <<monitor-tcp-ports,`ports`>>. If the monitor is {heartbeat-ref}/configuration-ssl.html[configured to use SSL], Synthetics establishes an SSL/TLS-based connection. Otherwise, it establishes a plain TCP connection.
(<<synthetics-lightweight-data-string,string>>)
a| *Required*. The host to ping. The entries in the list can be:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
a| *Required*. The host to ping. The entries in the list can be:
a| *Required*. The host to ping. The value can be:

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch, thanks


* *A hostname and port, such as `localhost:12345`.*
Synthetics connects to the port on the specified host. If the monitor is {heartbeat-ref}/configuration-ssl.html[configured to use SSL], Synthetics establishes an SSL/TLS-based connection. Otherwise, it establishes a TCP connection.
Expand All @@ -24,32 +21,17 @@ a| *Required*. A list of hosts to ping. The entries in the list can be:

[source,yaml]
----
hosts: ["localhost"]
----

[source,yaml]
----
hosts: ["localhost:8000"]
hosts: "localhost"
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I noticed you removed "A plain host name, such as localhost, or an IP address." above. Should we also remove this example?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks - good catch, removing

----

[source,yaml]
----
hosts: ["tcp://localhost:8000"]
hosts: "localhost:8000"
----

////////////////
ports
////////////////
| [[monitor-tcp-ports]] *`ports`*
(list of <<synthetics-lightweight-data-string,string>>s)
a| A list of ports to ping if the host specified in <<monitor-tcp-hosts,`hosts`>> does not contain a port number. It is generally preferable to use a single value here, since each port will be monitored using a separate `id`, with the given `id` value, used as a prefix in the Synthetics data, and the configured `name` shared across events sent via this check.

*Example*:

[source,yaml]
----
hosts: ["localhost"]
ports: [80, 9200, 5044]
hosts: "tcp://localhost:8000"
----

////////////////
Expand Down
Loading