Add documentation clarification #3382

paulb-elastic · 2023-11-23T11:30:25Z

Following on from #3263, there are more places where this limitation was not reflected in the documentation. This is also true for not supporting ports in Project Monitors.

The docs have also been updated to clarify that monitors cannot run in headful mode, but always headless, and cannot be overridden with Playwright Options.

github-actions · 2023-11-23T11:30:38Z

A documentation preview will be available soon:

📚 HTML diff
📙 Observability Guide

mergify · 2023-11-23T11:31:00Z

This pull request does not have a backport label. Could you fix it @paulb-elastic? 🙏
To fixup this pull request, you need to add the backport labels for the needed
branches, such as:

backport-/d./d is the label to automatically backport to the /d./d branch. /d is the digit
NOTE: backport-skip has been added to this pull request.

paulb-elastic · 2023-11-23T12:01:15Z

@elasticmachine run elasticsearch-ci/docs

paulb-elastic · 2023-11-23T14:17:29Z

@elasticmachine run elasticsearch-ci/docs

lucabelluccini · 2023-11-23T17:19:52Z

docs/en/observability/synthetics-configuration.asciidoc

@@ -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).


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

@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?

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

emilioalvap · 2023-11-23T17:27:15Z

docs/en/observability/synthetics-create-test.asciidoc

@@ -167,6 +167,11 @@ Use Playwright to simulate and validate user workflows including:

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

+[NOTE]


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

@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?

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.

emilioalvap

LGTM

colleenmcginnis · 2023-11-27T17:32:03Z

@elasticmachine, run elasticsearch-ci/docs

colleenmcginnis

Some questions and suggestions below.

colleenmcginnis · 2023-11-27T19:14:44Z

docs/en/observability/synthetics-reference/lightweight-config/tcp.asciidoc

 * *A full URL using the syntax `scheme://<host>:[port]`*, where:
 ** `scheme` is one of `tcp`, `plain`, `ssl` or `tls`. If `tcp` or `plain` is specified, Synthetics establishes a TCP connection even if the monitor is configured to use SSL. If `tls` or `ssl` is specified, Synthetics establishes an SSL connection. However, if the monitor is not configured to use SSL, the system defaults are used (currently not supported on Windows).
 ** `host` is the hostname.
-** `port` is the port number. If `port` is missing in the URL, the <<monitor-tcp-ports,`ports`>> setting is required.
+** `port` is the port number.


@paulb-elastic this is the change I pushed to get the build to succeed (this line was still linking to the ports option, which was removed below). Should the whole line be removed instead?

Ah, thanks @colleenmcginnis!!
I think this part of line 18 should still be there as it describes what the port is under the A full URL using the syntax section

colleenmcginnis · 2023-11-27T19:14:46Z

docs/en/observability/synthetics-reference/lightweight-config/tcp.asciidoc

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


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

Thanks - good catch, removing

colleenmcginnis · 2023-11-27T19:15:59Z

docs/en/observability/synthetics-reference/lightweight-config/tcp.asciidoc

-* *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:


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:

Good catch, thanks

paulb-elastic · 2023-11-27T19:30:03Z

Thanks for the feedback @colleenmcginnis, updated as per the comments

colleenmcginnis

✨

elasticmachine · 2023-11-27T20:40:37Z

💚 Build Succeeded

Buildkite Build
Commit: 7697a53
Documentation preview
- 📚 HTML diff
- 📙 Preview

History

💚 Build #118 succeeded 742a6d4ad31d42637cedba646a8cc0061a795fbe
💔 Build #116 failed 742a6d4ad31d42637cedba646a8cc0061a795fbe
💔 Build #115 failed 742a6d4ad31d42637cedba646a8cc0061a795fbe

* Update how hosts and ports are configured * Add that monitors cannot be run headful (cherry picked from commit 3271331) # Conflicts: # docs/en/observability/synthetics-configuration.asciidoc

* Update how hosts and ports are configured * Add that monitors cannot be run headful (cherry picked from commit 3271331)

* Update how hosts and ports are configured * Add that monitors cannot be run headful (cherry picked from commit 3271331) Co-authored-by: Paul Bianciardi <[email protected]>

…#3384) * Add documentation clarification (elastic#3382) * Update how hosts and ports are configured * Add that monitors cannot be run headful (cherry picked from commit 3271331) # Conflicts: # docs/en/observability/synthetics-configuration.asciidoc * fix conflicts --------- Co-authored-by: Paul Bianciardi <[email protected]> Co-authored-by: Colleen McGinnis <[email protected]>

paulb-elastic added 2 commits November 23, 2023 11:17

Update how hosts and ports are configured

3cbeeda

Add that monitors cannot be run headful

5035329

mergify bot added the backport-skip Skip notification from the automated backport with mergify label Nov 23, 2023

paulb-elastic requested review from lucabelluccini and emilioalvap November 23, 2023 12:14

paulb-elastic marked this pull request as ready for review November 23, 2023 12:17

paulb-elastic requested a review from a team as a code owner November 23, 2023 12:17

paulb-elastic requested review from alaudazzi and mdbirnstiehl November 23, 2023 12:17

lucabelluccini reviewed Nov 23, 2023

View reviewed changes

emilioalvap reviewed Nov 23, 2023

View reviewed changes

Simplified wording following feedback

fe1027e

emilioalvap previously approved these changes Nov 24, 2023

View reviewed changes

lucabelluccini approved these changes Nov 24, 2023

View reviewed changes

mdbirnstiehl requested review from colleenmcginnis and removed request for mdbirnstiehl November 27, 2023 17:23

fix build

b65b224

colleenmcginnis dismissed emilioalvap’s stale review via b65b224 November 27, 2023 18:47

colleenmcginnis reviewed Nov 27, 2023

View reviewed changes

colleenmcginnis removed the request for review from alaudazzi November 27, 2023 19:25

Feedback from Colleen

7697a53

paulb-elastic requested a review from colleenmcginnis November 27, 2023 19:29

colleenmcginnis approved these changes Nov 27, 2023

View reviewed changes

paulb-elastic merged commit 3271331 into elastic:main Nov 28, 2023
3 checks passed

paulb-elastic deleted the add-doc-clarifications branch November 28, 2023 12:35

mergify bot pushed a commit that referenced this pull request Nov 28, 2023

Add documentation clarification (#3382)

a751b73

* Update how hosts and ports are configured * Add that monitors cannot be run headful (cherry picked from commit 3271331)

mergify bot pushed a commit that referenced this pull request Nov 28, 2023

Add documentation clarification (#3382)

5a50244

* Update how hosts and ports are configured * Add that monitors cannot be run headful (cherry picked from commit 3271331)

This was referenced Nov 28, 2023

[8.8](backport #3382) Add documentation clarification #3384

Merged

[8.9](backport #3382) Add documentation clarification #3385

Merged

[8.10](backport #3382) Add documentation clarification #3386

Merged

mergify bot pushed a commit that referenced this pull request Nov 28, 2023

Add documentation clarification (#3382)

5288ab4

* Update how hosts and ports are configured * Add that monitors cannot be run headful (cherry picked from commit 3271331)

mergify bot mentioned this pull request Nov 28, 2023

[8.11](backport #3382) Add documentation clarification #3387

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation clarification #3382

Add documentation clarification #3382

paulb-elastic commented Nov 23, 2023

github-actions bot commented Nov 23, 2023

mergify bot commented Nov 23, 2023

paulb-elastic commented Nov 23, 2023

paulb-elastic commented Nov 23, 2023

lucabelluccini Nov 23, 2023 •

edited

Loading

paulb-elastic Nov 23, 2023

lucabelluccini Nov 23, 2023

emilioalvap Nov 23, 2023

paulb-elastic Nov 23, 2023

emilioalvap Nov 23, 2023

emilioalvap left a comment

colleenmcginnis commented Nov 27, 2023

colleenmcginnis left a comment

colleenmcginnis Nov 27, 2023

paulb-elastic Nov 27, 2023

colleenmcginnis Nov 27, 2023

paulb-elastic Nov 27, 2023

colleenmcginnis Nov 27, 2023

paulb-elastic Nov 27, 2023

paulb-elastic commented Nov 27, 2023

colleenmcginnis left a comment

elasticmachine commented Nov 27, 2023

		@@ -167,6 +167,11 @@ Use Playwright to simulate and validate user workflows including:

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

		[NOTE]

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

Add documentation clarification #3382

Add documentation clarification #3382

Conversation

paulb-elastic commented Nov 23, 2023

github-actions bot commented Nov 23, 2023

mergify bot commented Nov 23, 2023

paulb-elastic commented Nov 23, 2023

paulb-elastic commented Nov 23, 2023

lucabelluccini Nov 23, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

emilioalvap left a comment

Choose a reason for hiding this comment

colleenmcginnis commented Nov 27, 2023

colleenmcginnis left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

paulb-elastic commented Nov 27, 2023

colleenmcginnis left a comment

Choose a reason for hiding this comment

elasticmachine commented Nov 27, 2023

💚 Build Succeeded

History

lucabelluccini Nov 23, 2023 •

edited

Loading