[synthetics] Add lightweight monitor configuration options

[colleenmcginnis]

Closes #2372

Approach

This is still a work in progress, but here's the plan:

• Copy over content from Heartbeat docs including: Common monitor options, ICMP options, TCP options, and HTTP options
• Create a page with all config file data types (preview link)
• Verify list of Heartbeat options that are supported in projects
  • Needs input from Synthetics team ([REQUEST]: Document all lightweight monitor configuration options #2372 (comment))
• Format and refine content for Common monitor options (see the preview link to see the format I'm proposing)
• Format and refine content for HTTP-specific options
• Format and refine content for TCP-specific options
• Format and refine content for ICMP-specific options

Open questions

In the original issue, @andrewvc mentioned:

If you're using a project based lightweight monitor it doesn't make sense to have to go to the heartbeat docs, ideally you don't even know what heartbeat is.

How far do we want to take this? Do we not want to link back to any Heartbeat-related docs? If so, we would need to also copy (or single-source) content that is linked to from these reference pages. For example, if processors is a supported config option, users would probably need to know how processors can be defined.

Feel free to tag in others to provide feedback!

[github-actions]

A documentation preview will be available soon:

• 📚 HTML diff
• 📘 Fleet and Elastic Agent Guide
• 📙 Observability Guide

[paulb-elastic]

I'm not sure if the example on the initial page might be a bit confusing?

For instance, https://observability-docs_2729.docs-preview.app.elstc.co/guide/en/observability/master/synthetics-lightweight.html#synthetics-lightweight talks about the different types of monitor, with links to how to go and set those up (which I think works).

The section beneath though shows an example YML, but it's not necessarily clear what that relates to (e.g. someone can't use those if they are configuring through the UI).

Maybe the common/http/icmp/tcp/data-types pages should be linked to from Project Monitors for example. I wonder if it will be easier to understand that with the split of the docs between Synthetics and Uptime/Heartbeat too.

Be interested to hear from @andrewvc too on how this fits in with what he had in mind initially too.

[colleenmcginnis]

Maybe the common/http/icmp/tcp/data-types pages should be linked to from Project Monitors for example.

Ahh interesting. Do you think it would be helpful to document lightweight monitor options regardless of whether they are created in the Synthetics UI or using projects? Or do you think we should just document options for YAML configuration and let the UI text serve as its own documentation for the monitors configured in the UI?

For example, if there's enough overlap between configuration options for each method, we could structure the docs with a single description for each option with the ability to switch between "Synthetics app" and "Project Monitors" for more specific details and examples. Here's a snapshot of what the TCP options page could look like:

Synthetics app (UI)	Project Monitors (YAML)

This could also highlight limitations of each method for creating monitors like... if you want to set a schedule/frequency that isn't one of the available durations available in the UI, you could use a project to customize it. I'm not sure if that's a good thing or a bad thing, though. Let me know what you think.

[paulb-elastic]

There is a gap between the configurations in the UI, Project Monitors, and traditional heartbeat.yml.

We have a variety of issues to close this gap, but it will take time, they are:

• [Synthetics] Normalizing Heartbeat YML from synthetics agent for monitor management kibana#140864
• Synthetics to push all Heartbeat config options synthetics#655
• [Project Monitors] Support multiple hosts/urls/ports in lightweight monitors. synthetics#627
• Serialize Lightweight Monitor TLS certs  synthetics#599
• [Project Monitors] Gap between UI configuration for browser monitors and push synthetics#657

The full set is the current implementation in heartbeat.yml, but that's already documented in Heartbeat and I understand @andrewvc's purpose here was to remove the need to know or understand what Heartbeat is (when running monitors via the new mechanism).

I think that adding all these options under Synthetics will be confusing as many configurations are not supported. I think the UI does a good job of describing the various configurations (and as we add them, this will continue). That leaves Project Monitors, for which it is not clear what options are supported.

@andrewvc what were your thoughts here, should this be something like:

• Leave the full set (heartbeat.yml docs as they are anyway) <= don't think there was any intention of removing these
• Not document anything for the UI settings right now (maybe in the future when they're all implemented)
• Document the config options available for Project Monitors (and just be mindful to keep adding to these docs as we add new capabilities)

[andrewvc]

This is certainly a complex issue, I think the guiding principle here should be that we should remove the need for most users to look at the heartbeat docs.

That means that we should document the YAML for lightweight monitors enough to cover at 95% of use cases.

I think your last comments are dead on in aligning with that @paulb-elastic . No need to document the UI, and just document the available config options for project monitors, making it clear that they only affect the YAML options for project monitors.

[colleenmcginnis]

Thanks @paulb-elastic @andrewvc! Is the latest preview looking closer to what you're describing?

If yes, next up is to determine if we should replace all instances of the word "Heartbeat".

I understand @andrewvc's purpose here was to remove the need to know or understand what Heartbeat is (when running monitors via the new mechanism).

The copied-over content from the Heartbeat docs references "Heartbeat" several times. Should we replace it as to not confuse users? What is the right replacement... "Synthetics"? Here are a couple examples:

• The text at the beginning of ICMP options (source)
• The text describing the hosts option for TCP monitors (source)

Document the config options available for Project Monitors (and just be mindful to keep adding to these docs as we add new capabilities)

Yes. It will be a bit of a challenge to keep these docs up to dat, but I structured the tables of options in a way that (hopefully) in the future we could generate docs from structured data.

[colleenmcginnis]

To expand on my previous comment, I've added some specific questions I'd like to get answers to in order to move this PR forward. @paulb-elastic who's the best point of contact for this PR?

[andrewvc]

LGTM

[vigneshshanmugam]

typo: module -> monitor