Enhance per bucket, and per document monitor notification message ctx.

[AWSHurneyt]

Issue #, if available:
#1300
#1396
#1401

Description of changes:

1. Added support for returning sample documents for bucket level monitors, and document level monitors.
2. Added support for printing query/rule info in notification messages for document level monitors.

CheckList:

• Commits are signed per the DCO using --signoff

By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.
For more information on following Developer Certificate of Origin and signing off your commits, please check here.

[eirsep]

typically we create smaller PRs. one for each issue is a practice we should try follow

[AWSHurneyt]

The nonsecurity-related test failures seem related to the fixes in PR #1464

The security-related test failures have been failing for some time, so they're unrelated to these changes.
https://github.com/opensearch-project/alerting/actions/workflows/security-test-workflow.yml?query=branch%3Amain

[AWSHurneyt]

typically we create smaller PRs. one for each issue is a practice we should try follow

@eirsep agreed. Would you say that's blocking for this PR? All of the changes will require the AlertContext class, so the second PR couldn't be raised until the first is merged.

[opensearch-trigger-bot]

The backport to 2.x failed:

The process '/usr/bin/git' failed with exit code 128

To backport manually, run these commands in your terminal:

# Navigate to the root of your repository
cd $(git rev-parse --show-toplevel)
# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add ../.worktrees/alerting/backport-2.x 2.x
# Navigate to the new working tree
pushd ../.worktrees/alerting/backport-2.x
# Create a new branch
git switch --create backport-1450-to-2.x
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 5dc690caf1d4b9935f9aeb946c104be8d4861a77
# Push it to GitHub
git push --set-upstream origin backport-1450-to-2.x
# Go back to the original working tree
popd
# Delete the working tree
git worktree remove ../.worktrees/alerting/backport-2.x

Then, create a pull request where the base branch is 2.x and the compare/head branch is backport-1450-to-2.x.

[opensearch-trigger-bot]

The backport to 2.11 failed:

The process '/usr/bin/git' failed with exit code 128

To backport manually, run these commands in your terminal:

# Navigate to the root of your repository
cd $(git rev-parse --show-toplevel)
# Fetch latest updates from GitHub
git fetch
# Create a new working tree
git worktree add ../.worktrees/alerting/backport-2.11 2.11
# Navigate to the new working tree
pushd ../.worktrees/alerting/backport-2.11
# Create a new branch
git switch --create backport-1450-to-2.11
# Cherry-pick the merged commit of this pull request and resolve the conflicts
git cherry-pick -x --mainline 1 5dc690caf1d4b9935f9aeb946c104be8d4861a77
# Push it to GitHub
git push --set-upstream origin backport-1450-to-2.11
# Go back to the original working tree
popd
# Delete the working tree
git worktree remove ../.worktrees/alerting/backport-2.11

Then, create a pull request where the base branch is 2.11 and the compare/head branch is backport-1450-to-2.11.

[AWSHurneyt]

This current implementation executes the monitor query multiple times; the first time on line 124 to collect the data for trigger evaluation, and then subsequent searches are executed for each triggered trigger in order to collect sample documents.

Ideally, we want to collect the sample documents in the call to collectInputResults on line 124 so we can avoid multiple queries as that will improve performance.

[AWSHurneyt]

Created issue #1481 to track this follow-up item.

[chiarch84]

Dear @AWSHurneyt it is not clear to me weather this should fix or not the fact that {{ctx.results.0.hits.hits.0._source}} doesn't print anything. I tried OpenSearch version 2.16.0 but it seems not to work as in previous versions. Do I need to use a different syntax to make it work?

[AWSHurneyt]

Hi @chiarch84!

This is the documentation, and an example for these enhancements.
https://opensearch.org/docs/latest/observing-your-data/alerting/triggers/#mustache-template-example-1

A concern for us when making these enhancements was that the number of hits could easily be several thousand depending on the use case. Printing out a single _source from that list of thousands probably wouldn't be an issue, but mustache template supports iterating through lists, and printing values from each entry. Printing data in a notification message for thousands of hits could cause the message to exceed the size restrictions accepted by the destination webhook; causing the message to fail to send. So we added the sample_documents variable to the ctx to help manage the size of the notification message. We currently return a max of 10 sample docs, but we want to enhance that so it's a configurable cluster setting (no timeline for that just yet though).

[chiarch84]

Thank you for your answer @AWSHurneyt
I tried your suggestion in my OpenSearch version 2.16.0 but I still get an empty message.
Here the details:
Content of the message:

{{ctx.monitor.name}} just entered alert status. 
Please investigate the issue.

  - Severity: {{ctx.trigger.severity}}
  - Period start: {{ctx.periodStart}}
  - Period end: {{ctx.periodEnd}}
  - Hits:  {{ctx.results.0.hits.total.value}}
  - Alerts Info: {{ctx.results.0.hits}}

Alerts
{{#ctx.alerts}}
    Sample documents:
    {{#sample_documents}}
        Index: {{_index}}
        Document ID: {{_id}}
       
        Exc TYPE: {{_source.bdap_exception_type}}
        -----------------
    {{/sample_documents}}
    {{#associated_queries}}
        Name: {{name}}
        Id: {{id}}
        Tags: {{tags}}
    ------------------------
    {{/associated_queries}}
{{/ctx.alerts}}

Previewed message obtained:

Monitor BDAP data download - per QUERY just entered alert status. 
Please investigate the issue.

  - Severity: 3
  - Period start: 2024-11-26T12:10:52+01:00
  - Period end: 2024-11-26T12:20:52+01:00
  - Hits:  80
  - Alerts Info: [object Object]

Alerts

So even though there are 80 hits, I get nothing in the details part of Alerts.
Thank you for your help!

[AWSHurneyt]

@chiarch84 Just to clarify, are you only seeing the issue in the preview of the message, or is the variable missing when an actual message is received after a monitor execution?

I just tested using the 2.16.0 docker image, and was able to successfully print sample docs in the message when my per bucket monitor executed; but it does look like the preview isn't showing the samples correctly (I created issue opensearch-project/alerting-dashboards-plugin#1175 to track that visual bug).

Also, based on the message template you shared, it looks like the monitor type is per query? Unfortunately, the sample docs variable is only available for per bucket, and per document monitors currently.
https://opensearch.org/docs/latest/observing-your-data/alerting/triggers/#:~:text=Only%20available%20with%20bucket%2D%20and%20document%2Dlevel%20monitors.

[chiarch84]

@AWSHurneyt in fact my monitor is per query, so I will try with one per bucket and let you know.
I was not seeing the result nor in the preview nor in the email, but probably because it is not the correct type of monitoring.