[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.

[jasonrhodes]

@maryam-saeidi do we still need these docs? Have things changed sufficiently that we need to redescribe what we want to document?

[maryam-saeidi]

@maryam-saeidi do we still need these docs? Have things changed sufficiently that we need to redescribe what we want to document?

I still think it is valuable for our users to know which data we have available in our alerting documents so that they can use them in features such as maintenance window and conditional actions. We are adding some fields (such as kibana.alert.grouping) that we can add to this list, but we don't need to be blocked by that work.

There are two questions that we need to answer here:

1. How and where can we document these fields? (needs input from the documentation team)
2. Does it make sense to document all the fields, or should we start with a subset of fields that we see as more useful for the features mentioned above? (In any case, we need to think about how to handle shared fields between all rules vs fields only related to one rule type.)

For the second question, @heespi, who would be the best person from the ResponseOps team to contact?

[heespi]

Does it make sense to document all the fields, or should we start with a subset of fields that we see as more useful for the features mentioned above? (In any case, we need to think about how to handle shared fields between all rules vs fields only related to one rule type.)

For the second question, @heespi, who would be the best person from the ResponseOps team to contact?

Apologies.. I missed responding here. I´d ask @tiamliu for starters, @maryam-saeidi