[Synthetics] Best practice guide for Synthetics

Description

Might be good to start working on this after 8.8 has gone out (prioritising the other 8.8 docs tasks for now)

Different but linking to enhancing the troubleshooting page https://github.com/elastic/observability-docs/issues/2695

It would be useful to create a best practice guide for Synthetics. This has come up a few times where users and the field have asked for guidance on pitfalls or other suggestions we can help them with. We already have the troubleshooting page but probably want something else, more focused on best practices.

I expect this will be something we’ll want to update ad hoc as we and users learn and ask for different scenario advice.

Resources

This will need to be a team wide collaboration as I’m sure we’ll all have ideas on what to include.

Some very initial suggestions as a starting point:

Aware of geographical differences on websites
- Language, content, behaviour can be different from the website when delivered to different regions (e.g. cookie banners, but much more)
- Particularly pertinent when recording a script in one region and running it another, or expecting a single script to work in multiple regions
The Synthetics Recorder is most useful for creating a skeleton for a script, to help build the actions and assertions and step separation
- Although this may suffice for a simpler website or journey, additional scripting or logic it’s often needed to make the script more reliable and less brittle
- For example, selecting a date on a ticket purchasing website should not typically use a fixed date, as over time, that date will become invalid as it’s in the past. It may be more appropriate to dynamically generate the date to select (e.g. today + 60 days)
Avoid repeating the same code for common actions used across multiple scripts
- As with other development disciplines, consider the DRY principle when writing multiple scripts
- For example, you may have a login step that’s needed across multiple scripts. Consider using Project Monitors and separating out the login logic into a separate code block.
- See an example in our Synthetics Demo repo where journeys in advanced-example.journey.ts call the loadAppStep method (and others) which are defined in advanced-example-helpers.ts
- This is useful because if that common action changes (e.g. your login step), then you’re only changing this in one place and it’s used in all your scripts.
Avoid the use of xpath locators
- As is general practice in any web automation, you should avoid using xpath selectors in your scripts as they are typically more brittle and likely to fail over time
- Elastic Synthetics is built using Playwright, which has a more robust locator implementation that should be used
Advice on timeouts and throttling settings
- For slower / bigger / more variable performance
- Consider an SRE not wanting to get alerted because the site is slower, as opposed to down
Working with the Playwright context
- Need to define this in more detail, may be as restricted as don't touch it as it can break data collection

Collaboration

TBD. The docs and product team will work together to determine the best path forward.

Point of contact.

Main contact: @paulb-elastic

Stakeholders:

@elastic/uptime

elastic / observability-docs