Documenting rate aggregation for the new custom threshold rule

[maryam-saeidi]

Description

We are introducing rate aggregation to the custom threshold alerting rule in this PR. (To check this aggregation, you need to create a custom threshold rule from Observability > Alerts > Create rule > Custom threshold (Beta) and select rate aggregation)

This logic is similar to rate aggregation in the metric threshold alerting rule, and based on some questions (like this one) it is not clear how this aggregation works behind the scene. So, we would like to share more information through documentation and possibly include a link in the rule creation flyout when rate aggregation is selected, something like:

Information that can be useful to our users

We want to make sure we explain (1) how the rate is calculated and also (2) what the number shown on the preview chart means. (example)

The rate is calculated as follows: (code)

params.second > 0.0 && params.first > 0.0 && params.second > params.first ? (params.second - params.first) / ${intervalInSeconds}

Where first is the max value of the selected field in the previous bucket, and second is the maximum value for the current bucket.
The number shown on the preview chart is, therefore, the difference between the second and first bucket divided by the number of seconds in the selected interval.

Tasks

• Create a dedicated section/page for rate aggregation + example
• Add rate and percentile aggregations to the list of custom threshold aggregations (related comment)
  
• Custom threshold rule has a different header than other rules

Custom threshold	Inventory

Resources

PR: elastic/kibana#173728

Which documentation set does this change impact?

Stateful and Serverless

Feature differences

The feature is identical in Stateful and Serverless.

What release is this request related to?

8.13

Collaboration model

The documentation team

Point of contact.

Main contact: @maryam-saeidi

Stakeholders:

• @paulb-elastic
• @vinaychandrasekhar

[bmorelli25]

@maryam-saeidi will this go into Serverless before the 8.13 release?

[maryam-saeidi]

@bmorelli25 It depends on when we have the mentioned PR ready for merge. I think it should still be ready by next week, in any case, I can update this ticket when that happens.

I think we can add this link in a separate PR, so even though we merge the PR, we don't need to have the documentation right away and we can add the link in a future Serverless release. @paulb-elastic do you agree?

[paulb-elastic]

If the docs are not ready, then merging the PR when it's ready (without the link) is a good idea @maryam-saeidi (to decouple them).

If we follow up with a separate PR for the docs link, then I'd suggest ensuring it also makes 8.13, so we're not releasing the stateful version without the docs link.

[dedemorton]

@maryam-saeidi I have a quick question about your request to:

Create a dedicated section/page for rate aggregation + example

You say that the logic for the rate aggregation in the custom threshold rule is similar to rate aggregation in the metric threshold rule. Is the logic similar enough that it makes sense to create a separate/dedicated page that covers rate aggregation for both types of rules? So we would have a page that:

• Explains why you would use rate instead of average for something like a counter.
• Shows how the rate is calculated.
• Provides a realistic example.

And then we could point to the page from both rules. The other option is to provide a section or block in the custom threshold rule docs that explains these concepts.

I'm actually pretty new to a lot of these concepts, so my apologies if I'm getting things wrong.

[maryam-saeidi]

Is the logic similar enough that it makes sense to create a separate/dedicated page that covers rate aggregation for both types of rules?

@dedemorton Yes! I like the idea of having a dedicated page and linking it to both rules.
No worries, I am also learning more about this aggregation through examples that other developers provide, so we can learn together! :D

[dedemorton]

Closed by #3676 and https://github.com/elastic/staging-serverless-observability-docs/pull/241/