OpenSearch: including document fields in alert messages

Scenario

Using the alerting plugin within Opensearch, you’d like to include information about the document which triggered an alert. For example, including a field within the email that is sent out as a result of the alert being triggered

The initial problem is that the message being sent via email is missing the proper fields. Using the ctx.results[0].hits syntax as suggested by the docs simply wasn’t working (which FYI is documented here).

Solution

This method necessitates the use of an “extraction query” monitor (rather than the “visual editor”)

I ran across this particular message in the forums, which provided a handy template.

• First, ensure that the “size” setting is non-zero. In other words, you should change from "size": 0 to "size": 10 or something similar
• As per the forum message, you next need to add all the fields we intended on referencing in the email alert as docvalue_fields as well as enabling “stored_fields“, shown below:
  

    "version": true,
    "_source": {
        "includes": [],
        "excludes": []
    },
    "stored_fields": "*",
    "docvalue_fields": [
        {
            "field": "@timestamp",
            "format": "date_time"
        },
        {
            "field": "winlog.event_id"
        },
        {
            "field": "messageTitle"
        },
    ]

Note in the above I am referencing three fields in the docvalue_fields array:

• @timestamp
• winlog.event_id
• messageTitle

Formatting the email message

Once we do the above, we get access to the fields required and could reference them in the email message by using the syntax "ctx.results.0.hits.hits“

Now if you run the query in the debugger you’ll notice that hits.hits is actually a list, not a string:

(note the square brackets in the screenshot above)

This means that we somehow need to “loop” over the returned results. The opensearch UI helpfully links to a basic documentation page:

Which if we search for “loop” gives us an interesting example:

Using the above example, we can modify the message to be:

Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue.
 
- Alert time: {{ctx.periodStart}}

{{#ctx.results.0.hits.hits}}
- Windows Event ID: {{_source.winlog.event_id}}
- Title: {{_source.messageTitle}}

{{/ctx.results.0.hits.hits}}

That way we can loop over the “hits” list and due to our previous changes we can reference the fields contained within each list.