From 98767e6208ef3d5e02ceeb5aa0362bf305aedb2f Mon Sep 17 00:00:00 2001 From: AWSHurneyt Date: Tue, 2 Apr 2024 21:55:20 -0700 Subject: [PATCH 01/12] Added documentation for printing associated queries, and sample documents in notification message. Signed-off-by: AWSHurneyt --- _observing-your-data/alerting/triggers.md | 75 ++++++++++++++++++++--- 1 file changed, 68 insertions(+), 7 deletions(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index c89f1c45e6..39d4c3936b 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -125,15 +125,76 @@ Variable | Data type | Description #### Other variables Variable | Data type | Description -:--- | :--- : :--- -`ctx.results` | Array | An array with one element (`ctx.results[0]`). Contains the query results. This variable is empty if the trigger was unable to retrieve results. See `ctx.error`. +:--- | :--- | : --- +`ctx.results` | Array | An array with one element (`ctx.results.0`). Contains the query results. This variable is empty if the trigger was unable to retrieve results. See `ctx.error`. `ctx.last_update_time` | Milliseconds | Unix epoch time of when the monitor was last updated. `ctx.periodStart` | String | Unix timestamp for the beginning of the period during which the alert was triggered. For example, if a monitor runs every 10 minutes, a period might begin at 10:40 and end at 10:50. `ctx.periodEnd` | String | The end of the period during which the alert triggered. `ctx.error` | String | The error message displayed if the trigger was unable to retrieve results or could not be evaluated, typically due to a compile error or null pointer exception. Null otherwise. `ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. Only available with query-level monitors. -`ctx.dedupedAlerts` | Object | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors. -`ctx.newAlerts` | Object | Newly created alerts. Only available with bucket-level monitors. -`ctx.completedAlerts` | Object | Alerts that are no longer ongoing. Only available with bucket-level monitors. -`bucket_keys` | String | Comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts[0].bucket_keys`. -`parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts[0].parent_bucket_path`. +`ctx.alerts` | Array | Newly created alerts. Includes `ctx.alerts.0.finding_ids` that triggered the alert, and `ctx.alerts.0.related_doc_ids` associated with the findings. Only available with document-level monitors. +`ctx.dedupedAlerts` | Array | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors. +`ctx.newAlerts` | Array | Newly created alerts. Only available with bucket-level monitors. +`ctx.completedAlerts` | Array | Alerts that are no longer ongoing. Only available with bucket-level monitors. +`bucket_keys` | String | Comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts.0.bucket_keys`. +`parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts.0.parent_bucket_path`. +`associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through `ctx.alerts.0.associated_queries`. +`sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket-level, and document-level monitors. Accessed through `ctx.newAlerts.0.sample_documents`, and `ctx.alerts.0.sample_documents`, respectively. + +#### `associated_queries`, and `sample_documents` variables + +Per bucket, and per document monitors support printing sample documents in notification messages; and per document monitors support printing the list of queries that triggered the creation of the finding associated with the alert. Each new alert that's generated during a monitor execution will be added to a list (i.e., `newAlerts` for per bucket monitors, and `alerts` for per document monitors) within the `ctx` variable. Each alert has its own list of `sample_documents`, and each per document monitor alert has its own list of `associated_queries`. The message template can be formatted to iterate through the list of alerts, and the list of `associated_queries`, and `sample_documents` for each alert. + +To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/). + +#### Sample documents variables + +Variable | Data type | Description +:--- | :--- | : --- +`_index` | String | The index containing the +`_id` | String | The document ID for the document in its index. +`_score` | Float | A positive 32-bit floating point number illustrating the relevance of the returned document. +`_source` | Object | The JSON payload of the sample document. + +##### Mustache template example + +```groovy +Alerts: +{{#ctx.alerts}} + RULES + {{#associated_queries}} + Name: {{name}} + Id: {{id}} + Tags: {{tags}} + ------------------------ + {{/associated_queries}} +{{/ctx.alerts}} +``` + +#### Associated queries variables + +Variable | Data type | Description +:--- | :--- | : --- +`id` | String | The ID for the document-level query. +`name` | String | The name configured for the document-level query. +`tags` | Array | An array of tags (each of type String) configured for the document-level query. + +##### Mustache template example + +**Note**: The `_source` object in this example is based on the `opensearch_dashboards_sample_data_ecommerce` index that's available on OpenSearch Dashboards. + +```groovy +Alerts +{{#ctx.alerts}} + Sample documents: + {{#sample_documents}} + Index: {{_index}} + Document ID: {{_id}} + + Order date: {{_source.order_date}} + Order ID: {{_source.order_id}} + Clothing category: {{_source.category}} + ----------------- + {{/sample_documents}} +{{/ctx.alerts}} +``` \ No newline at end of file From 6561e383dcb691d58e9a45cc060b18d618dab5d1 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 30 Apr 2024 13:48:48 -0500 Subject: [PATCH 02/12] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index 39d4c3936b..7ac0e44982 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -136,7 +136,7 @@ Variable | Data type | Description `ctx.dedupedAlerts` | Array | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors. `ctx.newAlerts` | Array | Newly created alerts. Only available with bucket-level monitors. `ctx.completedAlerts` | Array | Alerts that are no longer ongoing. Only available with bucket-level monitors. -`bucket_keys` | String | Comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts.0.bucket_keys`. +`bucket_keys` | String | A comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts.0.bucket_keys`. `parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts.0.parent_bucket_path`. `associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through `ctx.alerts.0.associated_queries`. `sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket-level, and document-level monitors. Accessed through `ctx.newAlerts.0.sample_documents`, and `ctx.alerts.0.sample_documents`, respectively. From 40f3722d592540c9fd936eea5e8c9372454df11e Mon Sep 17 00:00:00 2001 From: AWSHurneyt Date: Wed, 8 May 2024 09:50:33 -0700 Subject: [PATCH 03/12] Apply suggestions from code review Co-authored-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Signed-off-by: AWSHurneyt --- _observing-your-data/alerting/triggers.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index 7ac0e44982..e047d099cf 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -132,7 +132,7 @@ Variable | Data type | Description `ctx.periodEnd` | String | The end of the period during which the alert triggered. `ctx.error` | String | The error message displayed if the trigger was unable to retrieve results or could not be evaluated, typically due to a compile error or null pointer exception. Null otherwise. `ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. Only available with query-level monitors. -`ctx.alerts` | Array | Newly created alerts. Includes `ctx.alerts.0.finding_ids` that triggered the alert, and `ctx.alerts.0.related_doc_ids` associated with the findings. Only available with document-level monitors. +`ctx.alerts` | Array | Newly created alerts. Includes the `ctx.alerts.0.finding_ids` that triggered the alert and the `ctx.alerts.0.related_doc_ids` associated with the findings. Only available with document-level monitors. `ctx.dedupedAlerts` | Array | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors. `ctx.newAlerts` | Array | Newly created alerts. Only available with bucket-level monitors. `ctx.completedAlerts` | Array | Alerts that are no longer ongoing. Only available with bucket-level monitors. @@ -151,7 +151,7 @@ To learn more about security in the Alerting plugin, see [Alerting security](htt Variable | Data type | Description :--- | :--- | : --- -`_index` | String | The index containing the +`_index` | String | The index containing the sample document. `_id` | String | The document ID for the document in its index. `_score` | Float | A positive 32-bit floating point number illustrating the relevance of the returned document. `_source` | Object | The JSON payload of the sample document. @@ -181,7 +181,8 @@ Variable | Data type | Description ##### Mustache template example -**Note**: The `_source` object in this example is based on the `opensearch_dashboards_sample_data_ecommerce` index that's available on OpenSearch Dashboards. +The `_source` object in this example is based on the `opensearch_dashboards_sample_data_ecommerce` index that's available on OpenSearch Dashboards. +{: .note} ```groovy Alerts From 964ee981777dd9ea93672659b7c6288e68c154c2 Mon Sep 17 00:00:00 2001 From: AWSHurneyt Date: Wed, 8 May 2024 09:54:27 -0700 Subject: [PATCH 04/12] Revised draft. --- _observing-your-data/alerting/triggers.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index e047d099cf..92b900f89b 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -145,7 +145,8 @@ Variable | Data type | Description Per bucket, and per document monitors support printing sample documents in notification messages; and per document monitors support printing the list of queries that triggered the creation of the finding associated with the alert. Each new alert that's generated during a monitor execution will be added to a list (i.e., `newAlerts` for per bucket monitors, and `alerts` for per document monitors) within the `ctx` variable. Each alert has its own list of `sample_documents`, and each per document monitor alert has its own list of `associated_queries`. The message template can be formatted to iterate through the list of alerts, and the list of `associated_queries`, and `sample_documents` for each alert. -To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/). +An Alerting monitor executes using the permissions of the user that created it. Please be mindful of the Notifications plugin channel to which alert messages are sent, and the content of the message mustache template. To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/). +{: .note} #### Sample documents variables @@ -181,7 +182,7 @@ Variable | Data type | Description ##### Mustache template example -The `_source` object in this example is based on the `opensearch_dashboards_sample_data_ecommerce` index that's available on OpenSearch Dashboards. +The `_source` object in this example is based on the `opensearch_dashboards_sample_data_ecommerce` index that's available on OpenSearch Dashboards. In this example, the message template is accessing the `ctx.alerts` variable of a per document monitor. {: .note} ```groovy From dd6a4361c360fb290fc024280f6fa0512c8b6840 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Mon, 13 May 2024 14:44:12 -0500 Subject: [PATCH 05/12] Update _observing-your-data/alerting/triggers.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index 92b900f89b..65612eb434 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -136,7 +136,7 @@ Variable | Data type | Description `ctx.dedupedAlerts` | Array | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors. `ctx.newAlerts` | Array | Newly created alerts. Only available with bucket-level monitors. `ctx.completedAlerts` | Array | Alerts that are no longer ongoing. Only available with bucket-level monitors. -`bucket_keys` | String | A comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts.0.bucket_keys`. +`bucket_keys` | String | A comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through the `ctx.dedupedAlerts.0.bucket_keys` variable. `parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts.0.parent_bucket_path`. `associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through `ctx.alerts.0.associated_queries`. `sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket-level, and document-level monitors. Accessed through `ctx.newAlerts.0.sample_documents`, and `ctx.alerts.0.sample_documents`, respectively. From 0a59b93a86b7d322adcf9f063a0ef3003e9d57cc Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Mon, 13 May 2024 14:44:32 -0500 Subject: [PATCH 06/12] Update _observing-your-data/alerting/triggers.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index 65612eb434..495bd22b9c 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -138,7 +138,7 @@ Variable | Data type | Description `ctx.completedAlerts` | Array | Alerts that are no longer ongoing. Only available with bucket-level monitors. `bucket_keys` | String | A comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through the `ctx.dedupedAlerts.0.bucket_keys` variable. `parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts.0.parent_bucket_path`. -`associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through `ctx.alerts.0.associated_queries`. +`associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through the `ctx.alerts.0.associated_queries` variable. `sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket-level, and document-level monitors. Accessed through `ctx.newAlerts.0.sample_documents`, and `ctx.alerts.0.sample_documents`, respectively. #### `associated_queries`, and `sample_documents` variables From 4f60bbc7fff4dbd23f8e67122f155209fe251757 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Mon, 13 May 2024 14:44:59 -0500 Subject: [PATCH 07/12] Update _observing-your-data/alerting/triggers.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index 495bd22b9c..b02359533d 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -139,7 +139,7 @@ Variable | Data type | Description `bucket_keys` | String | A comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through the `ctx.dedupedAlerts.0.bucket_keys` variable. `parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts.0.parent_bucket_path`. `associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through the `ctx.alerts.0.associated_queries` variable. -`sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket-level, and document-level monitors. Accessed through `ctx.newAlerts.0.sample_documents`, and `ctx.alerts.0.sample_documents`, respectively. +`sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket-level, and document-level monitors. Accessed through `ctx.newAlerts.0.sample_documents` and `ctx.alerts.0.sample_documents` variables, respectively. #### `associated_queries`, and `sample_documents` variables From 2fdffaee4be14b5c44207c6591f83508f01679f4 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 14 May 2024 09:00:06 -0500 Subject: [PATCH 08/12] Update _observing-your-data/alerting/triggers.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index b02359533d..f6815d5c12 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -143,7 +143,7 @@ Variable | Data type | Description #### `associated_queries`, and `sample_documents` variables -Per bucket, and per document monitors support printing sample documents in notification messages; and per document monitors support printing the list of queries that triggered the creation of the finding associated with the alert. Each new alert that's generated during a monitor execution will be added to a list (i.e., `newAlerts` for per bucket monitors, and `alerts` for per document monitors) within the `ctx` variable. Each alert has its own list of `sample_documents`, and each per document monitor alert has its own list of `associated_queries`. The message template can be formatted to iterate through the list of alerts, and the list of `associated_queries`, and `sample_documents` for each alert. +Per bucket and per document monitors support printing sample documents in notification messages. Per document monitors support printing the list of queries that triggered the creation of the finding associated with the alert. When the monitor runs, the monitor adds each new alert that's generated into the within the `ctx` variables, for example, `newAlerts` for per bucket monitors and `alerts` for per document monitors. Each alert has its own list of `sample_documents` and each per document monitor alert has its own list of `associated_queries`. The message template can be formatted to iterate through the list of alerts, the list of `associated_queries`, and the `sample_documents` for each alert. An Alerting monitor executes using the permissions of the user that created it. Please be mindful of the Notifications plugin channel to which alert messages are sent, and the content of the message mustache template. To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/). {: .note} From 1983713dbbca8d6c13c9cfd79f678c368c7642e9 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 14 May 2024 09:48:19 -0500 Subject: [PATCH 09/12] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 24 +++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index f6815d5c12..83e86a9918 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -126,7 +126,7 @@ Variable | Data type | Description Variable | Data type | Description :--- | :--- | : --- -`ctx.results` | Array | An array with one element (`ctx.results.0`). Contains the query results. This variable is empty if the trigger was unable to retrieve results. See `ctx.error`. +`ctx.results` | Array | An array with one element (`ctx.results.0`). Contains the query results. This variable is empty if the trigger is unable to retrieve results. See `ctx.error`. `ctx.last_update_time` | Milliseconds | Unix epoch time of when the monitor was last updated. `ctx.periodStart` | String | Unix timestamp for the beginning of the period during which the alert was triggered. For example, if a monitor runs every 10 minutes, a period might begin at 10:40 and end at 10:50. `ctx.periodEnd` | String | The end of the period during which the alert triggered. @@ -139,22 +139,22 @@ Variable | Data type | Description `bucket_keys` | String | A comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through the `ctx.dedupedAlerts.0.bucket_keys` variable. `parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts.0.parent_bucket_path`. `associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through the `ctx.alerts.0.associated_queries` variable. -`sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket-level, and document-level monitors. Accessed through `ctx.newAlerts.0.sample_documents` and `ctx.alerts.0.sample_documents` variables, respectively. +`sample_documents` | Array | An array of sample documents that matched the monitor query. Only available with bucket- and document-level monitors. Accessed through the `ctx.newAlerts.0.sample_documents` and `ctx.alerts.0.sample_documents` variables, respectively. -#### `associated_queries`, and `sample_documents` variables +#### The `associated_queries` and `sample_documents` variables -Per bucket and per document monitors support printing sample documents in notification messages. Per document monitors support printing the list of queries that triggered the creation of the finding associated with the alert. When the monitor runs, the monitor adds each new alert that's generated into the within the `ctx` variables, for example, `newAlerts` for per bucket monitors and `alerts` for per document monitors. Each alert has its own list of `sample_documents` and each per document monitor alert has its own list of `associated_queries`. The message template can be formatted to iterate through the list of alerts, the list of `associated_queries`, and the `sample_documents` for each alert. +Per bucket and per document monitors support printing sample documents in notification messages. Per document monitors support printing the list of queries that triggered the creation of the finding associated with the alert. When the monitor runs, it adds each new alert to the `ctx` variables, for example, `newAlerts` for per bucket monitors and `alerts` for per document monitors. Each alert has its own list of `sample_documents`, and each per document monitor alert has its own list of `associated_queries`. The message template can be formatted to iterate through the list of alerts, the list of `associated_queries`, and the `sample_documents` for each alert. -An Alerting monitor executes using the permissions of the user that created it. Please be mindful of the Notifications plugin channel to which alert messages are sent, and the content of the message mustache template. To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/). +An Alerting monitor uses the permissions of the user that created it. Be mindful of the Notifications plugin channel to which alert messages are sent and the content of the message mustache template. To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/). {: .note} -#### Sample documents variables +#### Sample document variables Variable | Data type | Description :--- | :--- | : --- `_index` | String | The index containing the sample document. -`_id` | String | The document ID for the document in its index. -`_score` | Float | A positive 32-bit floating point number illustrating the relevance of the returned document. +`_id` | String | The sample document ID. +`_score` | Float | A positive 32-bit floating-point number illustrating the relevance of the returned document. `_source` | Object | The JSON payload of the sample document. ##### Mustache template example @@ -172,17 +172,17 @@ Alerts: {{/ctx.alerts}} ``` -#### Associated queries variables +#### Associated query variables Variable | Data type | Description :--- | :--- | : --- -`id` | String | The ID for the document-level query. -`name` | String | The name configured for the document-level query. +`id` | String | The ID of the document-level query. +`name` | String | The name of the document-level query. `tags` | Array | An array of tags (each of type String) configured for the document-level query. ##### Mustache template example -The `_source` object in this example is based on the `opensearch_dashboards_sample_data_ecommerce` index that's available on OpenSearch Dashboards. In this example, the message template is accessing the `ctx.alerts` variable of a per document monitor. +The `_source` object in this example is based on the `opensearch_dashboards_sample_data_ecommerce` index available in OpenSearch Dashboards. In this example, the message template is accessing the `ctx.alerts` variable of a per document monitor. {: .note} ```groovy From c697d1902aa82a343110e65e1149ddd1fc79700e Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 14 May 2024 09:53:36 -0500 Subject: [PATCH 10/12] Update _observing-your-data/alerting/triggers.md Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index 83e86a9918..e880d2b782 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -135,7 +135,7 @@ Variable | Data type | Description `ctx.alerts` | Array | Newly created alerts. Includes the `ctx.alerts.0.finding_ids` that triggered the alert and the `ctx.alerts.0.related_doc_ids` associated with the findings. Only available with document-level monitors. `ctx.dedupedAlerts` | Array | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors. `ctx.newAlerts` | Array | Newly created alerts. Only available with bucket-level monitors. -`ctx.completedAlerts` | Array | Alerts that are no longer ongoing. Only available with bucket-level monitors. +`ctx.completedAlerts` | Array | Completed or expired alerts. Only available with bucket-level monitors. `bucket_keys` | String | A comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through the `ctx.dedupedAlerts.0.bucket_keys` variable. `parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts.0.parent_bucket_path`. `associated_queries` | Array | An array of document-level monitor queries that triggered the creation of the finding associated with the alert. Only available with document-level monitors. Accessed through the `ctx.alerts.0.associated_queries` variable. From 2ce26c05b146555a1373c651f62eaa6f4c64e582 Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 14 May 2024 09:54:29 -0500 Subject: [PATCH 11/12] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index e880d2b782..3b5fe27873 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -133,7 +133,7 @@ Variable | Data type | Description `ctx.error` | String | The error message displayed if the trigger was unable to retrieve results or could not be evaluated, typically due to a compile error or null pointer exception. Null otherwise. `ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. Only available with query-level monitors. `ctx.alerts` | Array | Newly created alerts. Includes the `ctx.alerts.0.finding_ids` that triggered the alert and the `ctx.alerts.0.related_doc_ids` associated with the findings. Only available with document-level monitors. -`ctx.dedupedAlerts` | Array | Alerts that have been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless numbers of the same alert. Only available with bucket-level monitors. +`ctx.dedupedAlerts` | Array | Triggered alerts. OpenSearch keeps the existing alert to prevent the plugin from perpetually creating the same alert. Only available with bucket-level monitors. `ctx.newAlerts` | Array | Newly created alerts. Only available with bucket-level monitors. `ctx.completedAlerts` | Array | Completed or expired alerts. Only available with bucket-level monitors. `bucket_keys` | String | A comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through the `ctx.dedupedAlerts.0.bucket_keys` variable. From cf0f74056c40a12776356e13c024f26e15328e6f Mon Sep 17 00:00:00 2001 From: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> Date: Tue, 14 May 2024 10:01:46 -0500 Subject: [PATCH 12/12] Apply suggestions from code review Signed-off-by: Naarcha-AWS <97990722+Naarcha-AWS@users.noreply.github.com> --- _observing-your-data/alerting/triggers.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/triggers.md b/_observing-your-data/alerting/triggers.md index 3b5fe27873..06b49f17de 100644 --- a/_observing-your-data/alerting/triggers.md +++ b/_observing-your-data/alerting/triggers.md @@ -145,7 +145,7 @@ Variable | Data type | Description Per bucket and per document monitors support printing sample documents in notification messages. Per document monitors support printing the list of queries that triggered the creation of the finding associated with the alert. When the monitor runs, it adds each new alert to the `ctx` variables, for example, `newAlerts` for per bucket monitors and `alerts` for per document monitors. Each alert has its own list of `sample_documents`, and each per document monitor alert has its own list of `associated_queries`. The message template can be formatted to iterate through the list of alerts, the list of `associated_queries`, and the `sample_documents` for each alert. -An Alerting monitor uses the permissions of the user that created it. Be mindful of the Notifications plugin channel to which alert messages are sent and the content of the message mustache template. To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/). +An alerting monitor uses the permissions of the user that created it. Be mindful of the Notifications plugin channel to which alert messages are sent and the content of the message mustache template. To learn more about security in the Alerting plugin, see [Alerting security](https://opensearch.org/docs/latest/observing-your-data/alerting/security/). {: .note} #### Sample document variables