[Request]: [Draft] Document additional context for observability rules

[maryam-saeidi]

⚠️ This is a placeholder for our request and will be updated as we progress with the implementation. 🚧

Description

We are working on adding ECS group by fields to the alerting document so that it can be used for features such as maintenance windows and conditional actions. (ticket: https://github.com/elastic/kibana/issues/183220)

We would like to have a document to explain what additional context will be added to the alerting document when selecting groups by fields, and the user will be able to use it for the features mentioned above.

For the group by fields, we only promote them to the root level of the AAD (Alert as data) document if their type is keyword.

Also, as mentioned in this comment, if the selected field already has a meaning in the alerting framework, it will be overridden by the framework. (For example: event.action) I can either provide a list of such fields, or we can link this part of the documentation to the alerting document default fields.

We are aiming at the following structure: (ticket: https://github.com/elastic/kibana/issues/181831)

Rule	Group	Include	Exclude
All rules	fields contain any of these prefixes: host, cloud, orchestrator, container	host.*, cloud.*, orchestrator.*, container.*, labels, tags	*.cpu.*, *.disk.*, *.network.*, *.memory.*

• All rules:
  • Custom threshold
  • Log threshold
  • Metric threshold
  • Inventory rule
  • SLO burn rate (?)

Resources

Related issues:

• https://github.com/elastic/kibana/issues/183220
• https://github.com/elastic/kibana/issues/181831

Which documentation set does this change impact?

Stateful and Serverless

Feature differences

Identical

What release is this request related to?

8.16

Collaboration model

The documentation team

Point of contact.

Main contact: @maryam-saeidi

Stakeholders: @jasonrhodes @vinayamohandoss

[dedemorton]

@maryam-saeidi What is the status of this request? It looks like the issue for adding additional context (https://github.com/elastic/kibana/issues/181831) is still in your backlog and hasn't been implemented.

Do we still need to update the docs for 8.16, or should I put this issue in our backlog, too?

[maryam-saeidi]

Hi @dedemorton, Do we have any document regarding what is available in an alerting document for observability rules?

If we have such a document, it would be great to add information about our recent change for saving ECS keyword fields at the root level of the alert document and also mention exceptions such as event.action. If we don't have such a page, I think we can postpone this ticket until we implement https://github.com/elastic/kibana/issues/181831.

cc @jasonrhodes

[dedemorton]

@maryam-saeidi Regarding your question:

Do we have any document regarding what is available in an alerting document for observability rules?

AFAIK we don't document the structure of the Alert as Data (AAD) document anywhere, if that's what you mean. Do you think we should?

We do document the fields that are exposed as "action variables" (context.*) but TBH I know how action variables are used, but I don't understand how they relate to the fields in the AAD document. There's still a lot I don't know about how alerting works. :-/

Should we continue this discussion or put this issue in the backlog for now?

[maryam-saeidi]

Let's put it in the backlog for now. We can bring it back when we unify the logic mentioned in https://github.com/elastic/kibana/issues/181831.