[Request]: Document alert data for observability rule types

[maryam-saeidi]

Description

🍒 Summary

We save different alert information for different observability rule types. This information can be used in multiple features such as maintenance window and conditional actions:

We would like to document the alert data available in all the observability rules and the differences between rules so that our users can get an idea of how to filter their alerts for the above-mentioned features.

Resources

Here is a list of fields that I am preparing based on fields that we define in code such as default_alert_as_data.

Which documentation set does this change impact?

Stateful and Serverless

Feature differences

No difference

What release is this request related to?

N/A

Collaboration model

The documentation team

Point of contact.

Main contact: @maryam-saeidi

Stakeholders: @jasonrhodes, @drewpost

[jasonrhodes]

I assume we should be engaging @dedemorton for (part of) this?

[maryam-saeidi]

Yes! I had a chat with @dedemorton about this topic, and she proposed some places where we can start including this information; we just need to first prepare a list of fields and their description, possibly with an example, that we want to include in the documentation.

[lcawl]

It's still needs some pondering but we're proposing to have reference content derivable from yaml files in the new docs system (so that it doesn't require fussy maintenance of tables and lends itself it automation so they get less out-dated). We're playing with this for settings references, for example, in elastic/kibana#191787. A similar effort might make sense in the case of these field references for each rule. At a basic level it would require consensus on what properties we'd want in the yaml file and then we'd just work with the docs engineers to ensure it can be output well in the new system.

[maryam-saeidi]

Thanks, @lcawl, for sharing the example PR. Having a yaml file for each rule sounds good to me! Regarding coming up with a sample template and list of fields, maybe we can start with a small set of fields, such as name, description, and an example and then extend it in future if needed. Or did you have something else in mind?

[heespi]

Adding @mikecote for visibility and inputs here.