From 678439086951271d57213532ae86b85363888116 Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Mon, 10 Jun 2024 19:03:31 -0700 Subject: [PATCH 01/48] alerting comments first documentation rough draft Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/api.md | 143 ++++++++++++++++++++++ _observing-your-data/alerting/comments.md | 21 ++++ _observing-your-data/alerting/settings.md | 59 +++++---- 3 files changed, 198 insertions(+), 25 deletions(-) create mode 100644 _observing-your-data/alerting/comments.md diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 6b95196b11..02d5bbc897 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -2075,4 +2075,147 @@ POST _plugins/_alerting/destinations/email_groups/_search } } ``` + +## Create comment (Experimental) + +#### Request + +```json +POST _plugins/_alerting/comments/ +{ + "content": "sample comment" +} +``` + +#### Example response + +```json +{ + "_id": "0U6aBJABVWc3FrmWer9s", + "_seq_no": 7, + "_primary_term": 2, + "comment": { + "entity_id": "vCZkA5ABWTh3kzuBEL_9", + "entity_type": "alert", + "content": "sample comment", + "created_time": 1718064151148, + "last_updated_time": null, + "user": "admin" + } +} +``` + +## Update comment (Experimental) + +#### Request + +```json +PUT _plugins/_alerting/comments/ +{ + "content": "sample updated comment" +} +``` + +#### Example response + +```json +{ + "_id": "0U6aBJABVWc3FrmWer9s", + "_seq_no": 8, + "_primary_term": 3, + "comment": { + "entity_id": "vCZkA5ABWTh3kzuBEL_9", + "entity_type": "alert", + "content": "sample updated comment", + "created_time": 1718064151148, + "last_updated_time": 1718064745485, + "user": "admin" + } +} +``` + +## Search comments (Experimental) + +#### Request + +```json +GET _plugins/_alerting/comments/_search +{ + "query": { + "match_all" : {} + } +} +``` + +#### Example response + +```json +{ + "took": 14, + "timed_out": false, + "_shards": { + "total": 1, + "successful": 1, + "skipped": 0, + "failed": 0 + }, + "hits": { + "total": { + "value": 2, + "relation": "eq" + }, + "max_score": 1, + "hits": [ + { + "_index": ".opensearch-alerting-comments-history-2024.06.10-1", + "_id": "xE5tBJABVWc3FrmWRL5i", + "_version": 1, + "_seq_no": 3, + "_primary_term": 2, + "_score": 1, + "_source": { + "entity_id": "vCZkA5ABWTh3kzuBEL_9", + "entity_type": "alert", + "content": "a different sample comment", + "created_time": 1718061188191, + "last_updated_time": null, + "user": "admin" + } + }, + { + "_index": ".opensearch-alerting-comments-history-2024.06.10-1", + "_id": "0U6aBJABVWc3FrmWer9s", + "_version": 3, + "_seq_no": 9, + "_primary_term": 3, + "_score": 1, + "_source": { + "entity_id": "vCZkA5ABWTh3kzuBEL_9", + "entity_type": "alert", + "content": "sample updated comment", + "created_time": 1718064151148, + "last_updated_time": 1718064745485, + "user": "admin" + } + } + ] + } +} +``` + +## Delete comment (Experimental) + +#### Request + +```json +DELETE _plugins/_alerting/comments/ +``` + +#### Example response + +```json +{ + "_id": "0U6aBJABVWc3FrmWer9s" +} +``` --- diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md new file mode 100644 index 0000000000..9f4ce03014 --- /dev/null +++ b/_observing-your-data/alerting/comments.md @@ -0,0 +1,21 @@ +--- +layout: default +title: Comments +nav_order: 1 +parent: Alerting +has_children: false +redirect_from: + - /monitoring-plugins/alerting/comments/ +--- + +# Comments (Experimental) + +When an alert is generated, add comments to your Alert to share insights into its root cause, and facilitate its resolution. + +## Enabling Comments + +Comments for the Alerting plugin is disabled by default because it is currently an experimental feature. To enable it, set the `plugins.alerting.comments_enabled` setting to "true". + +## Security + +The author of a comment is only displayed when the Security plugin is installed. If the Security plugin is not installed, comments can still be posted to Alerts, but authors will be displayed as `Unknown`. \ No newline at end of file diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 78d076a0e3..008ee5970f 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -34,29 +34,38 @@ We don't recommend changing these settings; the defaults should work well for mo All settings are available using the OpenSearch `_cluster/settings` API. None require a restart, and all can be marked `persistent` or `transient`. To learn more about static and dynamic settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/). -Setting | Default | Description -:--- | :--- | :--- -`plugins.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running. -`plugins.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs. -`plugins.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin. -`plugins.alerting.action_throttle_max_value` | 24h | The maximum amount of time you can set for action throttling. By default, this value displays as 1440 minutes in OpenSearch Dashboards. -`plugins.alerting.input_timeout` | 30s | How long the monitor can take to issue the search request. -`plugins.alerting.bulk_timeout` | 120s | How long the monitor can write alerts to the alert index. -`plugins.alerting.alert_backoff_count` | 3 | The number of retries for writing alerts before the operation fails. -`plugins.alerting.alert_backoff_millis` | 50ms | The amount of time to wait between retries---increases exponentially after each failed retry. -`plugins.alerting.alert_history_rollover_period` | 12h | How frequently to check whether the `.opendistro-alerting-alert-history-write` alias should roll over to a new history index and whether the Alerting plugin should delete any history indexes. -`plugins.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry. -`plugins.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted. -`plugins.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create. -`plugins.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opendistro-alert-history-` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days). -`plugins.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opendistro-alert-history-` index before creating a new index. -`plugins.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-` indexes. -`plugins.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indexes before automatically deleting them. +Setting | Default | Description +:--- |:-------------------------------------------------------------| :--- +`plugins.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running. +`plugins.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs. +`plugins.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin. +`plugins.alerting.action_throttle_max_value` | 24h | The maximum amount of time you can set for action throttling. By default, this value displays as 1440 minutes in OpenSearch Dashboards. +`plugins.alerting.input_timeout` | 30s | How long the monitor can take to issue the search request. +`plugins.alerting.bulk_timeout` | 120s | How long the monitor can write alerts to the alert index. +`plugins.alerting.alert_backoff_count` | 3 | The number of retries for writing alerts before the operation fails. +`plugins.alerting.alert_backoff_millis` | 50ms | The amount of time to wait between retries---increases exponentially after each failed retry. +`plugins.alerting.alert_history_rollover_period` | 12h | How frequently to check whether the `.opendistro-alerting-alert-history-write` alias should roll over to a new history index and whether the Alerting plugin should delete any history indexes. +`plugins.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry. +`plugins.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted. +`plugins.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create. +`plugins.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opendistro-alert-history-` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days). +`plugins.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opendistro-alert-history-` index before creating a new index. +`plugins.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-` indexes. +`plugins.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indexes before automatically deleting them. `plugins.alerting.destination.allow_list` | ["chime", "slack", "custom_webhook", "email", "test_action"] | The list of allowed destinations. If you don't want to allow users to a certain type of destination, you can remove it from this list, but we recommend leaving this setting as-is. -`plugins.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/). -`plugins.alerting.cross_cluster_monitoring_enabled` | "false" | Toggles whether cluster metrics monitors support running against remote clusters. -`plugins.scheduled_jobs.sweeper.period` | 5m | The alerting feature uses its "job sweeper" component to periodically check for new or updated jobs. This setting is the rate at which the sweeper checks to see if any jobs (monitors) have changed and need to be rescheduled. -`plugins.scheduled_jobs.sweeper.page_size` | 100 | The page size for the sweeper. You shouldn't need to change this value. -`plugins.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry. -`plugins.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error. -`plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs. +`plugins.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/). +`plugins.alerting.cross_cluster_monitoring_enabled` | "false" | Toggles whether cluster metrics monitors support running against remote clusters. +`plugins.scheduled_jobs.sweeper.period` | 5m | The alerting feature uses its "job sweeper" component to periodically check for new or updated jobs. This setting is the rate at which the sweeper checks to see if any jobs (monitors) have changed and need to be rescheduled. +`plugins.scheduled_jobs.sweeper.page_size` | 100 | The page size for the sweeper. You shouldn't need to change this value. +`plugins.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry. +`plugins.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error. +`plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs. +`plugins.alerting.comments_enabled` | "false" | Whether comments for the alerting plugin is enabled or not. +`plugins.alerting.comments_history_enabled` | "true" | Whether to create more than one `.opensearch-alerting-comments-history-` indexes. All comments are stored in history indexes, and disabling this setting causes there to only be one comments history index regardless of the number of existing comments. This subjects all comments to automatic deletion depending on the other `comments_history` settings. It is recommended to keep this setting enabled. +`plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. +`plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in the `.opensearch-alerting-comments-history-` index before creating a new index. If the number of comments in this time period does not exceed comments_history_max_docs, the alerting plugin creates one comments history index per period (e.g. one index every 30 days). +`plugins.alerting.comments_history_rollover_period` | 12h | How frequently to check whether the .opensearch-alerting-comments-history-write alias should roll over to a new history index and whether the alerting plugin should delete any comments history indexes. +`plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comments history indexes before automatically deleting them. +`plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. +`plugins.alerting.max_comments_per_alert` | 500 | The maximum number of comments that can be posted on an alert. +`plugins.alerting.max_comments_per_notification` | 3 | The maximum number of comments per alert to include in the `ctx` mustache template variable for alert notifications. \ No newline at end of file From c889fab845fefffad8f449668e18c8e90f4f9ce9 Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Mon, 10 Jun 2024 19:35:03 -0700 Subject: [PATCH 02/48] formatting and styling changes Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/api.md | 8 ++-- _observing-your-data/alerting/comments.md | 4 +- _observing-your-data/alerting/settings.md | 52 +++++++++++------------ 3 files changed, 32 insertions(+), 32 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 02d5bbc897..ca132670f5 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -2076,7 +2076,7 @@ POST _plugins/_alerting/destinations/email_groups/_search } ``` -## Create comment (Experimental) +## Create comment (experimental) #### Request @@ -2105,7 +2105,7 @@ POST _plugins/_alerting/comments/ } ``` -## Update comment (Experimental) +## Update comment (experimental) #### Request @@ -2134,7 +2134,7 @@ PUT _plugins/_alerting/comments/ } ``` -## Search comments (Experimental) +## Search comments (experimental) #### Request @@ -2203,7 +2203,7 @@ GET _plugins/_alerting/comments/_search } ``` -## Delete comment (Experimental) +## Delete comment (experimental) #### Request diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index 9f4ce03014..d28f5eedea 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -8,11 +8,11 @@ redirect_from: - /monitoring-plugins/alerting/comments/ --- -# Comments (Experimental) +# Comments (experimental) When an alert is generated, add comments to your Alert to share insights into its root cause, and facilitate its resolution. -## Enabling Comments +## Enabling comments Comments for the Alerting plugin is disabled by default because it is currently an experimental feature. To enable it, set the `plugins.alerting.comments_enabled` setting to "true". diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 008ee5970f..6d756f3f59 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -36,35 +36,35 @@ All settings are available using the OpenSearch `_cluster/settings` API. None re Setting | Default | Description :--- |:-------------------------------------------------------------| :--- -`plugins.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running. -`plugins.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs. -`plugins.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin. -`plugins.alerting.action_throttle_max_value` | 24h | The maximum amount of time you can set for action throttling. By default, this value displays as 1440 minutes in OpenSearch Dashboards. -`plugins.alerting.input_timeout` | 30s | How long the monitor can take to issue the search request. -`plugins.alerting.bulk_timeout` | 120s | How long the monitor can write alerts to the alert index. -`plugins.alerting.alert_backoff_count` | 3 | The number of retries for writing alerts before the operation fails. -`plugins.alerting.alert_backoff_millis` | 50ms | The amount of time to wait between retries---increases exponentially after each failed retry. -`plugins.alerting.alert_history_rollover_period` | 12h | How frequently to check whether the `.opendistro-alerting-alert-history-write` alias should roll over to a new history index and whether the Alerting plugin should delete any history indexes. -`plugins.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry. -`plugins.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted. -`plugins.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create. -`plugins.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opendistro-alert-history-` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days). -`plugins.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opendistro-alert-history-` index before creating a new index. -`plugins.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-` indexes. -`plugins.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indexes before automatically deleting them. +`plugins.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running. +`plugins.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs. +`plugins.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin. +`plugins.alerting.action_throttle_max_value` | 24h | The maximum amount of time you can set for action throttling. By default, this value displays as 1440 minutes in OpenSearch Dashboards. +`plugins.alerting.input_timeout` | 30s | How long the monitor can take to issue the search request. +`plugins.alerting.bulk_timeout` | 120s | How long the monitor can write alerts to the alert index. +`plugins.alerting.alert_backoff_count` | 3 | The number of retries for writing alerts before the operation fails. +`plugins.alerting.alert_backoff_millis` | 50ms | The amount of time to wait between retries---increases exponentially after each failed retry. +`plugins.alerting.alert_history_rollover_period` | 12h | How frequently to check whether the `.opendistro-alerting-alert-history-write` alias should roll over to a new history index and whether the Alerting plugin should delete any history indexes. +`plugins.alerting.move_alerts_backoff_millis` | 250 | The amount of time to wait between retries---increases exponentially after each failed retry. +`plugins.alerting.move_alerts_backoff_count` | 3 | The number of retries for moving alerts to a deleted state after their monitor or trigger has been deleted. +`plugins.alerting.monitor.max_monitors` | 1000 | The maximum number of monitors users can create. +`plugins.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opendistro-alert-history-` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days). +`plugins.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opendistro-alert-history-` index before creating a new index. +`plugins.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-` indexes. +`plugins.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indexes before automatically deleting them. `plugins.alerting.destination.allow_list` | ["chime", "slack", "custom_webhook", "email", "test_action"] | The list of allowed destinations. If you don't want to allow users to a certain type of destination, you can remove it from this list, but we recommend leaving this setting as-is. -`plugins.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/). -`plugins.alerting.cross_cluster_monitoring_enabled` | "false" | Toggles whether cluster metrics monitors support running against remote clusters. -`plugins.scheduled_jobs.sweeper.period` | 5m | The alerting feature uses its "job sweeper" component to periodically check for new or updated jobs. This setting is the rate at which the sweeper checks to see if any jobs (monitors) have changed and need to be rescheduled. -`plugins.scheduled_jobs.sweeper.page_size` | 100 | The page size for the sweeper. You shouldn't need to change this value. -`plugins.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry. -`plugins.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error. -`plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs. -`plugins.alerting.comments_enabled` | "false" | Whether comments for the alerting plugin is enabled or not. +`plugins.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/). +`plugins.alerting.cross_cluster_monitoring_enabled` | "false" | Toggles whether cluster metrics monitors support running against remote clusters. +`plugins.scheduled_jobs.sweeper.period` | 5m | The alerting feature uses its "job sweeper" component to periodically check for new or updated jobs. This setting is the rate at which the sweeper checks to see if any jobs (monitors) have changed and need to be rescheduled. +`plugins.scheduled_jobs.sweeper.page_size` | 100 | The page size for the sweeper. You shouldn't need to change this value. +`plugins.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry. +`plugins.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error. +`plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs. +`plugins.alerting.comments_enabled` | "false" | Whether comments for the Alerting plugin is enabled or not. `plugins.alerting.comments_history_enabled` | "true" | Whether to create more than one `.opensearch-alerting-comments-history-` indexes. All comments are stored in history indexes, and disabling this setting causes there to only be one comments history index regardless of the number of existing comments. This subjects all comments to automatic deletion depending on the other `comments_history` settings. It is recommended to keep this setting enabled. `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. -`plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in the `.opensearch-alerting-comments-history-` index before creating a new index. If the number of comments in this time period does not exceed comments_history_max_docs, the alerting plugin creates one comments history index per period (e.g. one index every 30 days). -`plugins.alerting.comments_history_rollover_period` | 12h | How frequently to check whether the .opensearch-alerting-comments-history-write alias should roll over to a new history index and whether the alerting plugin should delete any comments history indexes. +`plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in the `.opensearch-alerting-comments-history-` index before creating a new index. If the number of comments in this time period does not exceed comments_history_max_docs, the Alerting plugin creates one comments history index per period (e.g. one index every 30 days). +`plugins.alerting.comments_history_rollover_period` | 12h | How frequently to check whether the .opensearch-alerting-comments-history-write alias should roll over to a new history index and whether the Alerting plugin should delete any comments history indexes. `plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comments history indexes before automatically deleting them. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. `plugins.alerting.max_comments_per_alert` | 500 | The maximum number of comments that can be posted on an alert. From c8fd5028dee816ca1120438a057d362e205b3582 Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Mon, 10 Jun 2024 19:38:21 -0700 Subject: [PATCH 03/48] more formatting changes Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 6d756f3f59..ca7c3e4299 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -34,8 +34,8 @@ We don't recommend changing these settings; the defaults should work well for mo All settings are available using the OpenSearch `_cluster/settings` API. None require a restart, and all can be marked `persistent` or `transient`. To learn more about static and dynamic settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/). -Setting | Default | Description -:--- |:-------------------------------------------------------------| :--- +Setting | Default | Description +:--- |:--- | :--- `plugins.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running. `plugins.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs. `plugins.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin. From 8353cb0b8d1630ff2f98c2a24bd1c28d0ff3b9eb Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Mon, 10 Jun 2024 19:39:49 -0700 Subject: [PATCH 04/48] more spacing changes Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index ca7c3e4299..510702ace5 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -35,7 +35,7 @@ We don't recommend changing these settings; the defaults should work well for mo All settings are available using the OpenSearch `_cluster/settings` API. None require a restart, and all can be marked `persistent` or `transient`. To learn more about static and dynamic settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/). Setting | Default | Description -:--- |:--- | :--- +:--- | :--- | :--- `plugins.scheduled_jobs.enabled` | true | Whether the alerting plugin is enabled or not. If disabled, all monitors immediately stop running. `plugins.alerting.index_timeout` | 60s | The timeout for creating monitors and destinations using the REST APIs. `plugins.alerting.request_timeout` | 10s | The timeout for miscellaneous requests from the plugin. From 3b6f9a3eb712942cdf9b2a015a0ca22501e0b76c Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Mon, 10 Jun 2024 19:53:03 -0700 Subject: [PATCH 05/48] added not about rbac and added some links Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/comments.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index d28f5eedea..f925f5671f 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -14,8 +14,14 @@ When an alert is generated, add comments to your Alert to share insights into it ## Enabling comments -Comments for the Alerting plugin is disabled by default because it is currently an experimental feature. To enable it, set the `plugins.alerting.comments_enabled` setting to "true". +Comments for the Alerting plugin is disabled by default because it is currently an experimental feature. To enable it, set the `plugins.alerting.comments_enabled` setting to "true" using the [cluster settings API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). ## Security -The author of a comment is only displayed when the Security plugin is installed. If the Security plugin is not installed, comments can still be posted to Alerts, but authors will be displayed as `Unknown`. \ No newline at end of file +### Displaying comment authors + +The author of a comment is only displayed when the Security plugin is installed. If the Security plugin is not installed, comments can still be posted to Alerts, but authors will be displayed as `Unknown`. + +### Role-based access control + +Comments inherit the backend roles of the Alert it is attached to, which inherits from the Monitor that generated the Alert. For more details, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). From a9d7dde89edd74e2b7c088fbbebc1b8d79ec5de0 Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Tue, 11 Jun 2024 12:28:12 -0700 Subject: [PATCH 06/48] removing comments history enabled setting Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/settings.md | 1 - 1 file changed, 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 510702ace5..83321fdbfc 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -61,7 +61,6 @@ Setting | Default | Description `plugins.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error. `plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs. `plugins.alerting.comments_enabled` | "false" | Whether comments for the Alerting plugin is enabled or not. -`plugins.alerting.comments_history_enabled` | "true" | Whether to create more than one `.opensearch-alerting-comments-history-` indexes. All comments are stored in history indexes, and disabling this setting causes there to only be one comments history index regardless of the number of existing comments. This subjects all comments to automatic deletion depending on the other `comments_history` settings. It is recommended to keep this setting enabled. `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. `plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in the `.opensearch-alerting-comments-history-` index before creating a new index. If the number of comments in this time period does not exceed comments_history_max_docs, the Alerting plugin creates one comments history index per period (e.g. one index every 30 days). `plugins.alerting.comments_history_rollover_period` | 12h | How frequently to check whether the .opensearch-alerting-comments-history-write alias should roll over to a new history index and whether the Alerting plugin should delete any comments history indexes. From ee44f1e44d146c2f2f05b1b7b7417a71e9c08c1a Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Fri, 14 Jun 2024 10:19:33 -0600 Subject: [PATCH 07/48] Update comments.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/comments.md | 23 ++++++++++------------- 1 file changed, 10 insertions(+), 13 deletions(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index f925f5671f..788e00c7b7 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -1,27 +1,24 @@ --- layout: default -title: Comments -nav_order: 1 +title: Adding comments +nav_order: 35 parent: Alerting has_children: false redirect_from: - /monitoring-plugins/alerting/comments/ --- -# Comments (experimental) +# Adding comments -When an alert is generated, add comments to your Alert to share insights into its root cause, and facilitate its resolution. +This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](). +{: .warning} -## Enabling comments +When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting plugins.alerting.comments_enabled to "true" using the [cluster settings API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). -Comments for the Alerting plugin is disabled by default because it is currently an experimental feature. To enable it, set the `plugins.alerting.comments_enabled` setting to "true" using the [cluster settings API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). +## Viewing comment authors -## Security +If the Security plugin is installed, the author of a comment is displayed. Otherwise, comments on alerts are shown as `Unknown`. -### Displaying comment authors +## Assigning permissions -The author of a comment is only displayed when the Security plugin is installed. If the Security plugin is not installed, comments can still be posted to Alerts, but authors will be displayed as `Unknown`. - -### Role-based access control - -Comments inherit the backend roles of the Alert it is attached to, which inherits from the Monitor that generated the Alert. For more details, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). +Comment permissions inherit from the Alert's backend roles, which in turn inherit from the generating Monitor. For more details, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). From e67935bfa3647343670cbd31530118173c2f911f Mon Sep 17 00:00:00 2001 From: toepkerd <120457569+toepkerd@users.noreply.github.com> Date: Fri, 14 Jun 2024 15:21:07 -0700 Subject: [PATCH 08/48] Update _observing-your-data/alerting/api.md Update Update comment API description Co-authored-by: Melissa Vagi Signed-off-by: toepkerd <120457569+toepkerd@users.noreply.github.com> --- _observing-your-data/alerting/api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index ca132670f5..8f2bf937ec 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -2105,7 +2105,9 @@ POST _plugins/_alerting/comments/ } ``` -## Update comment (experimental) +## Update comment +This is an experimental feature and is not recommended for use in a production environment. +{: .warning} #### Request From 48c408288f92b63c798ebbb29d939fee4cc6450d Mon Sep 17 00:00:00 2001 From: toepkerd <120457569+toepkerd@users.noreply.github.com> Date: Fri, 14 Jun 2024 15:23:23 -0700 Subject: [PATCH 09/48] Update _observing-your-data/alerting/api.md Update Delete comment API description Co-authored-by: Melissa Vagi Signed-off-by: toepkerd <120457569+toepkerd@users.noreply.github.com> --- _observing-your-data/alerting/api.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 8f2bf937ec..8ad36a7bf4 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -2205,7 +2205,9 @@ GET _plugins/_alerting/comments/_search } ``` -## Delete comment (experimental) +## Delete comment +This is an experimental feature and is not recommended for use in a production environment. +{: .warning} #### Request From b2ee3236a27e5db0f95c30aebe892887a432ab24 Mon Sep 17 00:00:00 2001 From: toepkerd <120457569+toepkerd@users.noreply.github.com> Date: Fri, 14 Jun 2024 15:23:44 -0700 Subject: [PATCH 10/48] Update _observing-your-data/alerting/settings.md Updated comments_enabled setting description Co-authored-by: Melissa Vagi Signed-off-by: toepkerd <120457569+toepkerd@users.noreply.github.com> --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 83321fdbfc..29c6c14b2d 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -60,7 +60,7 @@ Setting | Default | Description `plugins.scheduled_jobs.sweeper.backoff_millis` | 50ms | The amount of time the sweeper waits between retries---increases exponentially after each failed retry. `plugins.scheduled_jobs.sweeper.retry_count` | 3 | The total number of times the sweeper should retry before throwing an error. `plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs. -`plugins.alerting.comments_enabled` | "false" | Whether comments for the Alerting plugin is enabled or not. +`plugins.alerting.comments_enabled` | `false` | Enables or disables comments for the Alerting plugin. `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. `plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in the `.opensearch-alerting-comments-history-` index before creating a new index. If the number of comments in this time period does not exceed comments_history_max_docs, the Alerting plugin creates one comments history index per period (e.g. one index every 30 days). `plugins.alerting.comments_history_rollover_period` | 12h | How frequently to check whether the .opensearch-alerting-comments-history-write alias should roll over to a new history index and whether the Alerting plugin should delete any comments history indexes. From e646f26e9a1b174c216c3898f3b8abfed005a540 Mon Sep 17 00:00:00 2001 From: toepkerd <120457569+toepkerd@users.noreply.github.com> Date: Fri, 14 Jun 2024 15:24:20 -0700 Subject: [PATCH 11/48] Update _observing-your-data/alerting/settings.md Updated comments_history_max_age setting description Co-authored-by: Melissa Vagi Signed-off-by: toepkerd <120457569+toepkerd@users.noreply.github.com> --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 29c6c14b2d..4cdc389e8e 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -62,7 +62,7 @@ Setting | Default | Description `plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs. `plugins.alerting.comments_enabled` | `false` | Enables or disables comments for the Alerting plugin. `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. -`plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in the `.opensearch-alerting-comments-history-` index before creating a new index. If the number of comments in this time period does not exceed comments_history_max_docs, the Alerting plugin creates one comments history index per period (e.g. one index every 30 days). +`plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in a `.opensearch-alerting-comments-history-` index before creating a new one. If the number of comments in this time period does not exceed `comments_history_max_docs`, one index is created per period (for example, one every 30 days). `plugins.alerting.comments_history_rollover_period` | 12h | How frequently to check whether the .opensearch-alerting-comments-history-write alias should roll over to a new history index and whether the Alerting plugin should delete any comments history indexes. `plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comments history indexes before automatically deleting them. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. From d8cabe5ee7f67053f328bb66bc8bd04a0c2f2b72 Mon Sep 17 00:00:00 2001 From: toepkerd <120457569+toepkerd@users.noreply.github.com> Date: Fri, 14 Jun 2024 15:24:47 -0700 Subject: [PATCH 12/48] Update _observing-your-data/alerting/settings.md Update comments_history_rollover_period setting description Co-authored-by: Melissa Vagi Signed-off-by: toepkerd <120457569+toepkerd@users.noreply.github.com> --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 4cdc389e8e..c785c50df0 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -63,7 +63,7 @@ Setting | Default | Description `plugins.alerting.comments_enabled` | `false` | Enables or disables comments for the Alerting plugin. `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. `plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in a `.opensearch-alerting-comments-history-` index before creating a new one. If the number of comments in this time period does not exceed `comments_history_max_docs`, one index is created per period (for example, one every 30 days). -`plugins.alerting.comments_history_rollover_period` | 12h | How frequently to check whether the .opensearch-alerting-comments-history-write alias should roll over to a new history index and whether the Alerting plugin should delete any comments history indexes. +`plugins.alerting.comments_history_rollover_period` | 12h | How often to check if the `.opensearch-alerting-comments-history-write` alias should roll over to a new index and delete old comment history indexes. `plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comments history indexes before automatically deleting them. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. `plugins.alerting.max_comments_per_alert` | 500 | The maximum number of comments that can be posted on an alert. From 2e856a249bed57dd53ad36ba41d1813656acd1ec Mon Sep 17 00:00:00 2001 From: toepkerd <120457569+toepkerd@users.noreply.github.com> Date: Fri, 14 Jun 2024 15:25:22 -0700 Subject: [PATCH 13/48] Update _observing-your-data/alerting/settings.md Update comments_history_retention_period setting description Co-authored-by: Melissa Vagi Signed-off-by: toepkerd <120457569+toepkerd@users.noreply.github.com> --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index c785c50df0..d6c38ecf62 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -64,7 +64,7 @@ Setting | Default | Description `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. `plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in a `.opensearch-alerting-comments-history-` index before creating a new one. If the number of comments in this time period does not exceed `comments_history_max_docs`, one index is created per period (for example, one every 30 days). `plugins.alerting.comments_history_rollover_period` | 12h | How often to check if the `.opensearch-alerting-comments-history-write` alias should roll over to a new index and delete old comment history indexes. -`plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comments history indexes before automatically deleting them. +`plugins.alerting.comments_history_retention_period` | 60d | The time to keep comment history indexes before automatic deletion. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. `plugins.alerting.max_comments_per_alert` | 500 | The maximum number of comments that can be posted on an alert. `plugins.alerting.max_comments_per_notification` | 3 | The maximum number of comments per alert to include in the `ctx` mustache template variable for alert notifications. \ No newline at end of file From 4075e8ef7893cb737c9cd35faeda81a890f29be7 Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Fri, 14 Jun 2024 15:41:24 -0700 Subject: [PATCH 14/48] minor edits and dead link fix attempt Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/comments.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index 788e00c7b7..8a7e6a4a48 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -10,10 +10,12 @@ redirect_from: # Adding comments -This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](). +This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/6999). {: .warning} -When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting plugins.alerting.comments_enabled to "true" using the [cluster settings API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). +When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to "true" using the [cluster settings API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). + +Comments can be accessed via the alerts table view by clicking on the text bubble icon within an alert's row. From there, comments can be added, edited, and deleted. An alerting comments API is also available for programmatic comments management. For details, see the [Alerting API](({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/)). ## Viewing comment authors @@ -21,4 +23,4 @@ If the Security plugin is installed, the author of a comment is displayed. Other ## Assigning permissions -Comment permissions inherit from the Alert's backend roles, which in turn inherit from the generating Monitor. For more details, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). +Comment permissions inherit from the Alert's backend roles, which in turn inherit from the generating Monitor. For more details, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/). From 52a100ec2b7db1ddd401fc1a7c7a6aeba12b1044 Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Fri, 14 Jun 2024 15:51:16 -0700 Subject: [PATCH 15/48] misc edits Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/comments.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index 8a7e6a4a48..7426788fc3 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -15,7 +15,7 @@ This is an experimental feature and is not recommended for use in a production e When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to "true" using the [cluster settings API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). -Comments can be accessed via the alerts table view by clicking on the text bubble icon within an alert's row. From there, comments can be added, edited, and deleted. An alerting comments API is also available for programmatic comments management. For details, see the [Alerting API](({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/)). +Comments can be accessed via the alerts table view by clicking on the text bubble icon within an alert's row. From there, comments can be added, edited, and deleted. An alerting comments API is also available for programmatic comments management. For details, see the [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). ## Viewing comment authors @@ -23,4 +23,4 @@ If the Security plugin is installed, the author of a comment is displayed. Other ## Assigning permissions -Comment permissions inherit from the Alert's backend roles, which in turn inherit from the generating Monitor. For more details, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/). +Comment permissions inherit from the Alert's backend roles, which in turn inherit from the generating Monitor. For more details, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). From 1015d27e1ac5ce6cc305d264c157d533a75d5689 Mon Sep 17 00:00:00 2001 From: Dennis Toepker Date: Fri, 14 Jun 2024 15:55:01 -0700 Subject: [PATCH 16/48] minor edit Signed-off-by: Dennis Toepker --- _observing-your-data/alerting/comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index 7426788fc3..561b7fad58 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -15,7 +15,7 @@ This is an experimental feature and is not recommended for use in a production e When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to "true" using the [cluster settings API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). -Comments can be accessed via the alerts table view by clicking on the text bubble icon within an alert's row. From there, comments can be added, edited, and deleted. An alerting comments API is also available for programmatic comments management. For details, see the [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). +Comments can be accessed through the alerts table view by clicking on the text bubble icon within an alert's row. From there, comments can be added, edited, and deleted. An alerting comments API is also available for programmatic comments management. For details, see the [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). ## Viewing comment authors From 566e49e78c606a25f84f208665c4d7409f2b0955 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 11:23:22 -0600 Subject: [PATCH 17/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 8ad36a7bf4..a01b123c74 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -2076,7 +2076,9 @@ POST _plugins/_alerting/destinations/email_groups/_search } ``` -## Create comment (experimental) +## Create comment +This is an experimental feature and is not recommended for use in a production environment. +{: .warning} #### Request @@ -2136,7 +2138,9 @@ PUT _plugins/_alerting/comments/ } ``` -## Search comments (experimental) +## Search comments +This is an experimental feature and is not recommended for use in a production environment. +{: .warning} #### Request From 1a212ff25e3367a6260cebb63fa95401ae67be0b Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 11:26:02 -0600 Subject: [PATCH 18/48] Update _observing-your-data/alerting/comments.md Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index 561b7fad58..e417dc2070 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -13,7 +13,7 @@ redirect_from: This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/6999). {: .warning} -When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to "true" using the [cluster settings API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). +When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to `true` using the [` _cluster/settings` API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). Comments can be accessed through the alerts table view by clicking on the text bubble icon within an alert's row. From there, comments can be added, edited, and deleted. An alerting comments API is also available for programmatic comments management. For details, see the [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). From d02daffbd33058d57c8ab665111a9d4d6ab93a95 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 14:48:59 -0600 Subject: [PATCH 19/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 382 +++++++++++++++++++++++++-- 1 file changed, 360 insertions(+), 22 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index a01b123c74..93ce06213d 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -26,10 +26,16 @@ Use the Alerting API to programmatically create, update, and manage monitors and ## Create a query-level monitor -Query-level monitors run the query and check whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level monitors and bucket-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). +Query-level monitors run the query and check whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level and bucket-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). #### Example request +
+   +    Example request +   +  {: .text-delta} + ```json POST _plugins/_alerting/monitors { @@ -92,6 +98,9 @@ POST _plugins/_alerting/monitors }] } ``` +{% include copy-curl.html %} + +
If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape your quotes: @@ -102,6 +111,7 @@ If you use a custom webhook for your destination and need to embed JSON in the m } } ``` +{% include copy-curl.html %} Optionally, to specify a backend role, you can add the `rbac_roles` parameter and backend role names to the bottom of your create monitor request. @@ -109,6 +119,12 @@ Optionally, to specify a backend role, you can add the `rbac_roles` parameter an The following request creates a query-level monitor and provides two backend roles, `role1` and `role2`. The section at the bottom of the request shows the line that specifies the roles with this syntax: `"rbac_roles": ["role1", "role2"]`. +
+   +    Example request +   +  {: .text-delta} + ```json POST _plugins/_alerting/monitors { @@ -172,10 +188,17 @@ POST _plugins/_alerting/monitors "rbac_roles": ["role1", "role2"] } ``` +{% include copy-curl.html %} + +
To learn more about using backend roles to limit access, see [(Advanced) Limit access by backend role]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/#advanced-limit-access-by-backend-role). -#### Example response +
+   +    Example response +   +  {: .text-delta} ```json { @@ -253,6 +276,9 @@ To learn more about using backend roles to limit access, see [(Advanced) Limit a } } ``` +{% include copy-curl.html %} + +
If you want to specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. @@ -260,6 +286,12 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th #### Example request +
+   +    Demo +   +  {: .text-delta} + ```json { "type": "monitor", @@ -321,8 +353,11 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th }] } ``` +{% include copy-curl.html %} + +
-For a full list of time zone names, refer to [Wikipedia](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). The Alerting plugin uses the Java [TimeZone](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/TimeZone.html) class to convert a [`ZoneId`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/ZoneId.html) to a valid time zone. +For a full list of time zone names, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). The Alerting plugin uses the Java [TimeZone](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/TimeZone.html) class to convert a [`ZoneId`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/ZoneId.html) to a valid time zone. --- @@ -330,6 +365,13 @@ For a full list of time zone names, refer to [Wikipedia](https://en.wikipedia.or Bucket-level monitors categorize results into buckets separated by fields. The monitor then runs your script with each bucket's results and evaluates whether to trigger an alert. For more information about bucket-level and query-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). +#### Example request +
+   +    Example request +   +  {: .text-delta} + ```json POST _plugins/_alerting/monitors { @@ -444,8 +486,18 @@ POST _plugins/_alerting/monitors ] } ``` +{% include copy-curl.html %} + +
#### Example response + +
+   +    Example response +   +  {: .text-delta} + ```json { "_id" : "Dfxr63sBwex6DxEhHV5N", @@ -584,6 +636,12 @@ POST _plugins/_alerting/monitors } } ``` +{% include copy-curl.html %} + +
+ +--- + ## Document-level monitors Introduced 2.0 {: .label .label-purple } @@ -601,17 +659,18 @@ To retrieve any available findings, send a GET request without any path paramete ```json GET /_plugins/_alerting/findings/_search? ``` - +{% include copy-curl.html %} To retrieve metadata for an individual document finding entry, you can search for the finding by its `findingId` as follows: ```json GET /_plugins/_alerting/findings/_search?findingId=gKQhj8WJit3BxjGfiOXC ``` +{% include copy-curl.html %} The response returns the number of individual finding entries in the `total_findings` field. -To get more specific results in a findings search, you can use any of the optional path parameters that are defined in the following table: +To get more specific results in a findings search, you can use any of the optional path parameters that are defined in the following table. Path parameter | Description | Usage :--- | :--- : :--- @@ -627,7 +686,7 @@ Path parameter | Description | Usage You can create a document-level monitor with a POST request that provides the monitor details in the request body. At a minimum, you need to provide the following details: specify the queries or combinations by tag with the `inputs` field, a valid trigger condition, and provide the notification message in the `action` field. -The following table shows the syntax to use for each trigger option: +The following table shows the syntax to use for each trigger option. Trigger options | Definition | Syntax :--- | :--- : :--- @@ -637,7 +696,11 @@ Query by ID | Creates alerts for documents that were returned by the identified #### Example request -The following example shows how to create a document-level monitor: +
+   +    Example request +   +  {: .text-delta} ```json POST _plugins/_alerting/monitors @@ -722,11 +785,15 @@ POST _plugins/_alerting/monitors } ``` +{% include copy-curl.html %} + +
### Limitations If you run a document-level query while the index is getting reindexed, the API response will not return the reindexed results. To get updates, wait until the reindexing process completes, then rerun the query. -{: .tip} + +--- ## Update monitor @@ -734,6 +801,12 @@ When updating a monitor, you can optionally include `seq_no` and `primary_term` #### Request +
+   +    Example request +   +  {: .text-delta} + ```json PUT _plugins/_alerting/monitors/ { @@ -839,9 +912,19 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 "last_update_time": 1551466639295 } ``` +{% include copy-curl.html %} + +
+ #### Example response +
+   +    Example response +   +  {: .text-delta} + ```json { "_id": "Q9aXOmkBC25HCRGmzfw-", @@ -900,20 +983,26 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 } } ``` +{% include copy-curl.html %} - +
--- -## Get monitor - -#### Request +## GET monitor request ``` GET _plugins/_alerting/monitors/ ``` +{% include copy-curl.html %} #### Example response +
+   +    Example response +   +  {: .text-delta} + ```json { "_id": "Q9aXOmkBC25HCRGmzfw-", @@ -972,7 +1061,9 @@ GET _plugins/_alerting/monitors/ } } ``` +{% include copy-curl.html %} +
--- @@ -988,9 +1079,16 @@ GET _plugins/_alerting/stats/ GET _plugins/_alerting//stats GET _plugins/_alerting//stats/ ``` +{% include copy-curl.html %} #### Example response +
+   +    Example response +   +  {: .text-delta} + ```json { "_nodes": { @@ -1161,20 +1259,27 @@ GET _plugins/_alerting//stats/ } } ``` +{% include copy-curl.html %} +
--- -## Delete monitor - -#### Request +## DELETE monitor request ``` DELETE _plugins/_alerting/monitors/ ``` +{% include copy-curl.html %} #### Example response +
+   +    Example response +   +  {: .text-delta} + ```json { "_index": ".opensearch-scheduled-jobs", @@ -1191,13 +1296,13 @@ DELETE _plugins/_alerting/monitors/ "_primary_term": 1 } ``` +{% include copy-curl.html %} +
--- -## Search monitors - -#### Request +## Search monitors request ```json GET _plugins/_alerting/monitors/_search @@ -1209,9 +1314,16 @@ GET _plugins/_alerting/monitors/_search } } ``` +{% include copy-curl.html %} #### Example response +
+   +    Example response +   +  {: .text-delta} + ```json { "took": 17, @@ -1288,7 +1400,9 @@ GET _plugins/_alerting/monitors/_search } } ``` +{% include copy-curl.html %} +
--- @@ -1296,15 +1410,21 @@ GET _plugins/_alerting/monitors/_search You can add the optional `?dryrun=true` parameter to the URL to show the results of a run without actions sending any message. - #### Request ```json POST _plugins/_alerting/monitors//_execute ``` +{% include copy-curl.html %} #### Example response +
+   +    Example response +   +  {: .text-delta} + ```json { "monitor_name": "logs", @@ -1321,6 +1441,9 @@ POST _plugins/_alerting/monitors//_execute } } ``` +{% include copy-curl.html %} + +
--- @@ -1350,9 +1473,16 @@ The following table lists the available path parameters. All path parameters are ```json GET _plugins/_alerting/monitors/alerts ``` +{% include copy-curl.html %} #### Response +
+   +    Response +   +  {: .text-delta} + ```json { "alerts": [ @@ -1406,6 +1536,9 @@ GET _plugins/_alerting/monitors/alerts "totalAlerts": 1 } ``` +{% include copy-curl.html %} + +
--- @@ -1413,7 +1546,6 @@ GET _plugins/_alerting/monitors/alerts [After getting your alerts](#get-alerts), you can acknowledge any number of active alerts in one call. If the alert is already in an ERROR, COMPLETED, or ACKNOWLEDGED state, it appears in the `failed` array. - #### Request ```json @@ -1422,9 +1554,16 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts "alerts": ["eQURa3gBKo1jAh6qUo49"] } ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "success": [ @@ -1433,6 +1572,9 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts "failed": [] } ``` +{% include copy-curl.html %} + +
--- @@ -1489,9 +1631,16 @@ POST _plugins/_alerting/destinations // The email_account_id and email_group_id will be the document IDs of the email_account and email_group you have created. ``` +{% include copy-curl.html %} #### Example response +
+   +    Example response +   +  {: .text-delta} + ```json { "_id": "nO-yFmkB8NzS6aXjJdiI", @@ -1508,7 +1657,9 @@ POST _plugins/_alerting/destinations } } ``` +{% include copy-curl.html %} +
--- @@ -1537,9 +1688,16 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term } } ``` +{% include copy-curl.html %} #### Example response +
+   +    Demo +   +  {: .text-delta} + ```json { "_id": "pe-1FmkB8NzS6aXjqvVY", @@ -1556,7 +1714,8 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term } } ``` - +{% include copy-curl.html %} +
--- @@ -1569,9 +1728,16 @@ Retrieve one destination. ```json GET _plugins/_alerting/destinations/ ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "totalDestinations": 1, @@ -1601,7 +1767,9 @@ GET _plugins/_alerting/destinations/ ] } ``` +{% include copy-curl.html %} +
--- @@ -1614,9 +1782,16 @@ Retrieve all destinations. ```json GET _plugins/_alerting/destinations ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "totalDestinations": 1, @@ -1646,7 +1821,9 @@ GET _plugins/_alerting/destinations ] } ``` +{% include copy-curl.html %} +
--- @@ -1657,9 +1834,16 @@ GET _plugins/_alerting/destinations ``` DELETE _plugins/_alerting/destinations/ ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_index": ".opendistro-alerting-config", @@ -1677,6 +1861,10 @@ DELETE _plugins/_alerting/destinations/ "_primary_term": 1 } ``` +{% include copy-curl.html %} + +
+ --- ## Create email account @@ -1692,8 +1880,15 @@ POST _plugins/_alerting/destinations/email_accounts "method": "ssl" } ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_id" : "email_account_id", @@ -1710,12 +1905,16 @@ POST _plugins/_alerting/destinations/email_accounts } } ``` +{% include copy-curl.html %} + +
## Update email account When updating an email account, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing email account or the email account doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). #### Request + ```json PUT _plugins/_alerting/destinations/email_accounts/ { @@ -1735,7 +1934,16 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= "method": "ssl" } ``` +{% include copy-curl.html %} + #### Example response + +
+   +    Demo +   +  {: .text-delta} + ```json { "_id" : "email_account_id", @@ -1752,6 +1960,9 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= } } ``` +{% include copy-curl.html %} + +
## Get email account @@ -1766,7 +1977,16 @@ GET _plugins/_alerting/destinations/email_accounts/ "method": "ssl" } ``` +{% include copy-curl.html %} + #### Example response + +
+   +    Response +   +  {: .text-delta} + ```json { "_id" : "email_account_id", @@ -1783,6 +2003,9 @@ GET _plugins/_alerting/destinations/email_accounts/ } } ``` +{% include copy-curl.html %} + +
## Delete email account @@ -1790,8 +2013,16 @@ GET _plugins/_alerting/destinations/email_accounts/ ``` DELETE _plugins/_alerting/destinations/email_accounts/ ``` +{% include copy-curl.html %} + #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_index" : ".opendistro-alerting-config", @@ -1809,6 +2040,9 @@ DELETE _plugins/_alerting/destinations/email_accounts/ "_primary_term" : 2 } ``` +{% include copy-curl.html %} + +
## Search email account @@ -1829,9 +2063,16 @@ POST _plugins/_alerting/destinations/email_accounts/_search } } ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "took" : 8, @@ -1873,6 +2114,9 @@ POST _plugins/_alerting/destinations/email_accounts/_search } } ``` +{% include copy-curl.html %} + +
--- @@ -1889,9 +2133,16 @@ POST _plugins/_alerting/destinations/email_groups }] } ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_id" : "email_group_id", @@ -1909,6 +2160,9 @@ POST _plugins/_alerting/destinations/email_groups } } ``` +{% include copy-curl.html %} + +
## Update email group @@ -1933,8 +2187,16 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i }] } ``` +{% include copy-curl.html %} + #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_id" : "email_group_id", @@ -1952,6 +2214,9 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i } } ``` +{% include copy-curl.html %} + +
## Get email group @@ -1965,8 +2230,16 @@ GET _plugins/_alerting/destinations/email_groups/ }] } ``` +{% include copy-curl.html %} + #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_id" : "email_group_id", @@ -1984,15 +2257,27 @@ GET _plugins/_alerting/destinations/email_groups/ } } ``` +{% include copy-curl.html %} + +
## Delete email group #### Request + ``` DELETE _plugins/_alerting/destinations/email_groups/ ``` +{% include copy-curl.html %} + #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_index" : ".opendistro-alerting-config", @@ -2010,6 +2295,9 @@ DELETE _plugins/_alerting/destinations/email_groups/ "_primary_term" : 2 } ``` +{% include copy-curl.html %} + +
## Search email group @@ -2030,9 +2318,16 @@ POST _plugins/_alerting/destinations/email_groups/_search } } ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "took" : 7, @@ -2075,6 +2370,9 @@ POST _plugins/_alerting/destinations/email_groups/_search } } ``` +{% include copy-curl.html %} + +
## Create comment This is an experimental feature and is not recommended for use in a production environment. @@ -2088,9 +2386,16 @@ POST _plugins/_alerting/comments/ "content": "sample comment" } ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_id": "0U6aBJABVWc3FrmWer9s", @@ -2106,6 +2411,9 @@ POST _plugins/_alerting/comments/ } } ``` +{% include copy-curl.html %} + +
## Update comment This is an experimental feature and is not recommended for use in a production environment. @@ -2119,9 +2427,16 @@ PUT _plugins/_alerting/comments/ "content": "sample updated comment" } ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_id": "0U6aBJABVWc3FrmWer9s", @@ -2137,6 +2452,9 @@ PUT _plugins/_alerting/comments/ } } ``` +{% include copy-curl.html %} + +
## Search comments This is an experimental feature and is not recommended for use in a production environment. @@ -2152,9 +2470,17 @@ GET _plugins/_alerting/comments/_search } } ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + + ```json { "took": 14, @@ -2208,6 +2534,9 @@ GET _plugins/_alerting/comments/_search } } ``` +{% include copy-curl.html %} + +
## Delete comment This is an experimental feature and is not recommended for use in a production environment. @@ -2218,12 +2547,21 @@ This is an experimental feature and is not recommended for use in a production e ```json DELETE _plugins/_alerting/comments/ ``` +{% include copy-curl.html %} #### Example response +
+   +    Response +   +  {: .text-delta} + ```json { "_id": "0U6aBJABVWc3FrmWer9s" } ``` ---- +{% include copy-curl.html %} + +
From 50c576d23c3f16ec339dc373edc509508fcf4763 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 15:03:30 -0600 Subject: [PATCH 20/48] Update comments.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/comments.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index e417dc2070..efb655ad95 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -13,14 +13,14 @@ redirect_from: This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/6999). {: .warning} -When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to `true` using the [` _cluster/settings` API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). +When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to `true` using the [`cluster/settings` API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). -Comments can be accessed through the alerts table view by clicking on the text bubble icon within an alert's row. From there, comments can be added, edited, and deleted. An alerting comments API is also available for programmatic comments management. For details, see the [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). +Comments can be accessed through the alerts table view by selecting on the comment icon within an alert's row. From there, comments can be added, edited, and deleted. An Alerting Comments API is also available for programmatic comments management. For details, see the [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). ## Viewing comment authors -If the Security plugin is installed, the author of a comment is displayed. Otherwise, comments on alerts are shown as `Unknown`. +If the Security plugin is installed, the comment's author is displayed. Otherwise, `Unknown` is displayed. ## Assigning permissions -Comment permissions inherit from the Alert's backend roles, which in turn inherit from the generating Monitor. For more details, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). +Comment permissions are determined by the backend roles associated with the alert. These backend roles are inherited from the monitor that generated the alert. For more details on how to limit access based on backend roles, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). From 295635e7387a9f72154bc441fab2a58ed621f523 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 15:09:08 -0600 Subject: [PATCH 21/48] Update api.md format request and response examples to expand Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 93ce06213d..4fb6cde970 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -11,31 +11,15 @@ redirect_from: Use the Alerting API to programmatically create, update, and manage monitors and alerts. For APIs that support the composite monitor specifically, see [Managing composite monitors with the API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/composite-monitors/#managing-composite-monitors-with-the-api). ---- - -
- - Table of contents - - {: .text-delta } -- TOC -{:toc} -
- ---- - ## Create a query-level monitor Query-level monitors run the query and check whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level and bucket-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). -#### Example request -
       Example request      {: .text-delta} - ```json POST _plugins/_alerting/monitors { @@ -99,7 +83,6 @@ POST _plugins/_alerting/monitors } ``` {% include copy-curl.html %} -
If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape your quotes: From 7442adb9ce6b3a93346115e03a09bd13eb389023 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 15:36:34 -0600 Subject: [PATCH 22/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 346 +-------------------------- 1 file changed, 13 insertions(+), 333 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 4fb6cde970..e97dc65dc1 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -15,11 +15,7 @@ Use the Alerting API to programmatically create, update, and manage monitors and Query-level monitors run the query and check whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level and bucket-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). -
-   -    Example request -   -  {: .text-delta} +#### Example request ```json POST _plugins/_alerting/monitors { @@ -83,7 +79,6 @@ POST _plugins/_alerting/monitors } ``` {% include copy-curl.html %} -
If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape your quotes: @@ -98,16 +93,11 @@ If you use a custom webhook for your destination and need to embed JSON in the m Optionally, to specify a backend role, you can add the `rbac_roles` parameter and backend role names to the bottom of your create monitor request. -#### Example request +The following request creates a query-level monitor and provides two backend roles, `role1` and `role2`. The section at the bottom of the request shows the line that specifies the roles with this syntax: `"rbac_roles": ["role1", "role2"]`. -The following request creates a query-level monitor and provides two backend roles, `role1` and `role2`. The section at the bottom of the request shows the line that specifies the roles with this syntax: `"rbac_roles": ["role1", "role2"]`. - -
-   -    Example request -   -  {: .text-delta} +To learn about using backend roles to limit access, see [(Advanced) Limit access by backend role]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/#advanced-limit-access-by-backend-role). +#### Example request ```json POST _plugins/_alerting/monitors { @@ -173,16 +163,7 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} -
- -To learn more about using backend roles to limit access, see [(Advanced) Limit access by backend role]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/#advanced-limit-access-by-backend-role). - -
-   -    Example response -   -  {: .text-delta} - +#### Example response ```json { "_id": "vd5k2GsBlQ5JUWWFxhsP", @@ -261,20 +242,11 @@ To learn more about using backend roles to limit access, see [(Advanced) Limit a ``` {% include copy-curl.html %} -
- -If you want to specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. +To specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. The following example creates a monitor that runs at 12:10 PM Pacific Time on the 1st day of every month. #### Example request - -
-   -    Demo -   -  {: .text-delta} - ```json { "type": "monitor", @@ -338,23 +310,15 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th ``` {% include copy-curl.html %} -
- For a full list of time zone names, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). The Alerting plugin uses the Java [TimeZone](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/TimeZone.html) class to convert a [`ZoneId`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/ZoneId.html) to a valid time zone. --- ## Bucket-level monitors -Bucket-level monitors categorize results into buckets separated by fields. The monitor then runs your script with each bucket's results and evaluates whether to trigger an alert. For more information about bucket-level and query-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). +Bucket-level monitors categorize results into buckets separated by fields. The monitor then runs the script with each bucket's results and evaluates whether to trigger an alert. For more information about bucket-level and query-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). #### Example request -
-   -    Example request -   -  {: .text-delta} - ```json POST _plugins/_alerting/monitors { @@ -471,16 +435,7 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} -
- #### Example response - -
-   -    Example response -   -  {: .text-delta} - ```json { "_id" : "Dfxr63sBwex6DxEhHV5N", @@ -621,8 +576,6 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} -
- --- ## Document-level monitors @@ -678,13 +631,6 @@ Query by name | Creates alerts for documents matched or returned by the named qu Query by ID | Creates alerts for documents that were returned by the identified query. | `query[id=]` #### Example request - -
-   -    Example request -   -  {: .text-delta} - ```json POST _plugins/_alerting/monitors { @@ -770,8 +716,6 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} -
- ### Limitations If you run a document-level query while the index is getting reindexed, the API response will not return the reindexed results. To get updates, wait until the reindexing process completes, then rerun the query. @@ -783,13 +727,6 @@ If you run a document-level query while the index is getting reindexed, the API When updating a monitor, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing monitor or the monitor doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). #### Request - -
-   -    Example request -   -  {: .text-delta} - ```json PUT _plugins/_alerting/monitors/ { @@ -897,17 +834,7 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 ``` {% include copy-curl.html %} -
- - #### Example response - -
-   -    Example response -   -  {: .text-delta} - ```json { "_id": "Q9aXOmkBC25HCRGmzfw-", @@ -968,24 +895,17 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 ``` {% include copy-curl.html %} -
--- -## GET monitor request +## GET monitor +#### Request ``` GET _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} #### Example response - -
-   -    Example response -   -  {: .text-delta} - ```json { "_id": "Q9aXOmkBC25HCRGmzfw-", @@ -1046,8 +966,6 @@ GET _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} -
- --- ## Monitor stats @@ -1055,7 +973,6 @@ GET _plugins/_alerting/monitors/ Returns statistics about the alerting feature. Use `_plugins/_alerting/stats` to find node IDs and metrics. Then you can drill down using those values. #### Request - ```json GET _plugins/_alerting/stats GET _plugins/_alerting/stats/ @@ -1065,13 +982,6 @@ GET _plugins/_alerting//stats/ {% include copy-curl.html %} #### Example response - -
-   -    Example response -   -  {: .text-delta} - ```json { "_nodes": { @@ -1244,25 +1154,17 @@ GET _plugins/_alerting//stats/ ``` {% include copy-curl.html %} -
- --- -## DELETE monitor request +## DELETE monitor +#### Request ``` DELETE _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} #### Example response - -
-   -    Example response -   -  {: .text-delta} - ```json { "_index": ".opensearch-scheduled-jobs", @@ -1281,12 +1183,11 @@ DELETE _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} -
- --- -## Search monitors request +## Search monitors +#### Request ```json GET _plugins/_alerting/monitors/_search { @@ -1300,13 +1201,6 @@ GET _plugins/_alerting/monitors/_search {% include copy-curl.html %} #### Example response - -
-   -    Example response -   -  {: .text-delta} - ```json { "took": 17, @@ -1385,8 +1279,6 @@ GET _plugins/_alerting/monitors/_search ``` {% include copy-curl.html %} -
- --- ## Run monitor @@ -1394,20 +1286,12 @@ GET _plugins/_alerting/monitors/_search You can add the optional `?dryrun=true` parameter to the URL to show the results of a run without actions sending any message. #### Request - ```json POST _plugins/_alerting/monitors//_execute ``` {% include copy-curl.html %} #### Example response - -
-   -    Example response -   -  {: .text-delta} - ```json { "monitor_name": "logs", @@ -1426,8 +1310,6 @@ POST _plugins/_alerting/monitors//_execute ``` {% include copy-curl.html %} -
- --- ## Get alerts @@ -1452,20 +1334,12 @@ The following table lists the available path parameters. All path parameters are | `workflowIds` | String | Allows for monitoring the status of chained alerts from multiple workflows within a single dashboard. Available in OpenSearch 2.9 or later. #### Request - ```json GET _plugins/_alerting/monitors/alerts ``` {% include copy-curl.html %} #### Response - -
-   -    Response -   -  {: .text-delta} - ```json { "alerts": [ @@ -1521,8 +1395,6 @@ GET _plugins/_alerting/monitors/alerts ``` {% include copy-curl.html %} -
- --- ## Acknowledge alert @@ -1530,7 +1402,6 @@ GET _plugins/_alerting/monitors/alerts [After getting your alerts](#get-alerts), you can acknowledge any number of active alerts in one call. If the alert is already in an ERROR, COMPLETED, or ACKNOWLEDGED state, it appears in the `failed` array. #### Request - ```json POST _plugins/_alerting/monitors//_acknowledge/alerts { @@ -1540,13 +1411,6 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "success": [ @@ -1557,14 +1421,11 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts ``` {% include copy-curl.html %} -
- --- ## Create destination #### Requests - ```json POST _plugins/_alerting/destinations { @@ -1617,13 +1478,6 @@ POST _plugins/_alerting/destinations {% include copy-curl.html %} #### Example response - -
-   -    Example response -   -  {: .text-delta} - ```json { "_id": "nO-yFmkB8NzS6aXjJdiI", @@ -1642,8 +1496,6 @@ POST _plugins/_alerting/destinations ``` {% include copy-curl.html %} -
- --- ## Update destination @@ -1651,7 +1503,6 @@ POST _plugins/_alerting/destinations When updating a destination, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing destination or the destination doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). #### Request - ```json PUT _plugins/_alerting/destinations/ { @@ -1674,13 +1525,6 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term {% include copy-curl.html %} #### Example response - -
-   -    Demo -   -  {: .text-delta} - ```json { "_id": "pe-1FmkB8NzS6aXjqvVY", @@ -1698,7 +1542,6 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term } ``` {% include copy-curl.html %} -
--- @@ -1707,20 +1550,12 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term Retrieve one destination. #### Requests - ```json GET _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "totalDestinations": 1, @@ -1752,8 +1587,6 @@ GET _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} -
- --- ## Get destinations @@ -1761,20 +1594,12 @@ GET _plugins/_alerting/destinations/ Retrieve all destinations. #### Requests - ```json GET _plugins/_alerting/destinations ``` {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "totalDestinations": 1, @@ -1806,27 +1631,17 @@ GET _plugins/_alerting/destinations ``` {% include copy-curl.html %} -
- --- ## Delete destination #### Request - ``` DELETE _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_index": ".opendistro-alerting-config", @@ -1846,8 +1661,6 @@ DELETE _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} -
- --- ## Create email account @@ -1866,12 +1679,6 @@ POST _plugins/_alerting/destinations/email_accounts {% include copy-curl.html %} #### Example response -
-   -    Response -   -  {: .text-delta} - ```json { "_id" : "email_account_id", @@ -1890,14 +1697,11 @@ POST _plugins/_alerting/destinations/email_accounts ``` {% include copy-curl.html %} -
- ## Update email account When updating an email account, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing email account or the email account doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). #### Request - ```json PUT _plugins/_alerting/destinations/email_accounts/ { @@ -1920,13 +1724,6 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= {% include copy-curl.html %} #### Example response - -
-   -    Demo -   -  {: .text-delta} - ```json { "_id" : "email_account_id", @@ -1945,8 +1742,6 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= ``` {% include copy-curl.html %} -
- ## Get email account #### Request @@ -1963,13 +1758,6 @@ GET _plugins/_alerting/destinations/email_accounts/ {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_id" : "email_account_id", @@ -1988,8 +1776,6 @@ GET _plugins/_alerting/destinations/email_accounts/ ``` {% include copy-curl.html %} -
- ## Delete email account #### Request @@ -1999,13 +1785,6 @@ DELETE _plugins/_alerting/destinations/email_accounts/ {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_index" : ".opendistro-alerting-config", @@ -2025,12 +1804,9 @@ DELETE _plugins/_alerting/destinations/email_accounts/ ``` {% include copy-curl.html %} -
- ## Search email account #### Request - ```json POST _plugins/_alerting/destinations/email_accounts/_search { @@ -2049,13 +1825,6 @@ POST _plugins/_alerting/destinations/email_accounts/_search {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "took" : 8, @@ -2099,14 +1868,11 @@ POST _plugins/_alerting/destinations/email_accounts/_search ``` {% include copy-curl.html %} -
- --- ## Create email group #### Request - ```json POST _plugins/_alerting/destinations/email_groups { @@ -2119,13 +1885,6 @@ POST _plugins/_alerting/destinations/email_groups {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_id" : "email_group_id", @@ -2145,14 +1904,11 @@ POST _plugins/_alerting/destinations/email_groups ``` {% include copy-curl.html %} -
- ## Update email group When updating an email group, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing email group or the email group doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). #### Request - ```json PUT _plugins/_alerting/destinations/email_groups/ { @@ -2173,13 +1929,6 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_id" : "email_group_id", @@ -2199,8 +1948,6 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i ``` {% include copy-curl.html %} -
- ## Get email group #### Request @@ -2216,13 +1963,6 @@ GET _plugins/_alerting/destinations/email_groups/ {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_id" : "email_group_id", @@ -2242,25 +1982,15 @@ GET _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} -
- ## Delete email group #### Request - ``` DELETE _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_index" : ".opendistro-alerting-config", @@ -2280,12 +2010,9 @@ DELETE _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} -
- ## Search email group #### Request - ```json POST _plugins/_alerting/destinations/email_groups/_search { @@ -2304,13 +2031,6 @@ POST _plugins/_alerting/destinations/email_groups/_search {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "took" : 7, @@ -2355,14 +2075,11 @@ POST _plugins/_alerting/destinations/email_groups/_search ``` {% include copy-curl.html %} -
- ## Create comment This is an experimental feature and is not recommended for use in a production environment. {: .warning} #### Request - ```json POST _plugins/_alerting/comments/ { @@ -2372,13 +2089,6 @@ POST _plugins/_alerting/comments/ {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_id": "0U6aBJABVWc3FrmWer9s", @@ -2413,13 +2123,6 @@ PUT _plugins/_alerting/comments/ {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_id": "0U6aBJABVWc3FrmWer9s", @@ -2437,14 +2140,11 @@ PUT _plugins/_alerting/comments/ ``` {% include copy-curl.html %} -
- ## Search comments This is an experimental feature and is not recommended for use in a production environment. {: .warning} #### Request - ```json GET _plugins/_alerting/comments/_search { @@ -2456,14 +2156,6 @@ GET _plugins/_alerting/comments/_search {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - - ```json { "took": 14, @@ -2519,32 +2211,20 @@ GET _plugins/_alerting/comments/_search ``` {% include copy-curl.html %} -
- ## Delete comment This is an experimental feature and is not recommended for use in a production environment. {: .warning} #### Request - ```json DELETE _plugins/_alerting/comments/ ``` {% include copy-curl.html %} #### Example response - -
-   -    Response -   -  {: .text-delta} - ```json { "_id": "0U6aBJABVWc3FrmWer9s" } ``` {% include copy-curl.html %} - -
From c97bda9e3b6ba80036d72baf20d4bb395b6ec781 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 16:16:03 -0600 Subject: [PATCH 23/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 18 +++++++++++++++++- 1 file changed, 17 insertions(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index e97dc65dc1..3caef325b0 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -15,6 +15,12 @@ Use the Alerting API to programmatically create, update, and manage monitors and Query-level monitors run the query and check whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level and bucket-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). +
+ + Select to expand example request + + {: .text-delta} + #### Example request ```json POST _plugins/_alerting/monitors @@ -80,8 +86,16 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} -If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape your quotes: +
+ +If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape your quotes. +
+ + Select to expand example request + + {: .text-delta} + ```json { "message_template": { @@ -91,6 +105,8 @@ If you use a custom webhook for your destination and need to embed JSON in the m ``` {% include copy-curl.html %} +
+ Optionally, to specify a backend role, you can add the `rbac_roles` parameter and backend role names to the bottom of your create monitor request. The following request creates a query-level monitor and provides two backend roles, `role1` and `role2`. The section at the bottom of the request shows the line that specifies the roles with this syntax: `"rbac_roles": ["role1", "role2"]`. From fb2dbf275c1350e38047bab9c6d5df2d779550d1 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 16:40:14 -0600 Subject: [PATCH 24/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 20 +++++++++++++++++--- 1 file changed, 17 insertions(+), 3 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 3caef325b0..a45ef37100 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -109,10 +109,14 @@ If you use a custom webhook for your destination and need to embed JSON in the m Optionally, to specify a backend role, you can add the `rbac_roles` parameter and backend role names to the bottom of your create monitor request. -The following request creates a query-level monitor and provides two backend roles, `role1` and `role2`. The section at the bottom of the request shows the line that specifies the roles with this syntax: `"rbac_roles": ["role1", "role2"]`. - -To learn about using backend roles to limit access, see [(Advanced) Limit access by backend role]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/#advanced-limit-access-by-backend-role). +The following request creates a query-level monitor and provides two backend roles, `role1` and `role2`. The section at the bottom of the request shows the line that specifies the roles with this syntax: `"rbac_roles": ["role1", "role2"]`. To learn about using backend roles to limit access, see [(Advanced) Limit access by backend role]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/#advanced-limit-access-by-backend-role). +
+ + Select to expand example request + + {: .text-delta} + #### Example request ```json POST _plugins/_alerting/monitors @@ -179,6 +183,14 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} +
+ +
+ + Select to expand example request + + {: .text-delta} + #### Example response ```json { @@ -258,6 +270,8 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} +
+ To specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. The following example creates a monitor that runs at 12:10 PM Pacific Time on the 1st day of every month. From 3f513e6c39147a9fe135c30dee402abcb8d9b9ba Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 20:09:12 -0600 Subject: [PATCH 25/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 262 ++++++++++++++++++++++++--- 1 file changed, 236 insertions(+), 26 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index a45ef37100..621e711dab 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -15,12 +15,6 @@ Use the Alerting API to programmatically create, update, and manage monitors and Query-level monitors run the query and check whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level and bucket-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). -
- - Select to expand example request - - {: .text-delta} - #### Example request ```json POST _plugins/_alerting/monitors @@ -86,16 +80,9 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} -
If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape your quotes. - -
- - Select to expand example request - - {: .text-delta} - + ```json { "message_template": { @@ -105,18 +92,11 @@ If you use a custom webhook for your destination and need to embed JSON in the m ``` {% include copy-curl.html %} -
Optionally, to specify a backend role, you can add the `rbac_roles` parameter and backend role names to the bottom of your create monitor request. The following request creates a query-level monitor and provides two backend roles, `role1` and `role2`. The section at the bottom of the request shows the line that specifies the roles with this syntax: `"rbac_roles": ["role1", "role2"]`. To learn about using backend roles to limit access, see [(Advanced) Limit access by backend role]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/#advanced-limit-access-by-backend-role). - -
- - Select to expand example request - - {: .text-delta} - + #### Example request ```json POST _plugins/_alerting/monitors @@ -183,11 +163,9 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} -
-
- Select to expand example request + Select to expand example response {: .text-delta} @@ -272,6 +250,7 @@ POST _plugins/_alerting/monitors
+ To specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. The following example creates a monitor that runs at 12:10 PM Pacific Time on the 1st day of every month. @@ -340,6 +319,7 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th ``` {% include copy-curl.html %} + For a full list of time zone names, see [List of tz database time zones](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). The Alerting plugin uses the Java [TimeZone](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/TimeZone.html) class to convert a [`ZoneId`](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/time/ZoneId.html) to a valid time zone. --- @@ -465,6 +445,13 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} + +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -606,6 +593,8 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} +
+ --- ## Document-level monitors @@ -660,6 +649,7 @@ Tag | Creates alerts for documents that match a multiple query with this tag app Query by name | Creates alerts for documents matched or returned by the named query. | `query[name=]` Query by ID | Creates alerts for documents that were returned by the identified query. | `query[id=]` + #### Example request ```json POST _plugins/_alerting/monitors @@ -746,6 +736,7 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} + ### Limitations If you run a document-level query while the index is getting reindexed, the API response will not return the reindexed results. To get updates, wait until the reindexing process completes, then rerun the query. @@ -756,7 +747,7 @@ If you run a document-level query while the index is getting reindexed, the API When updating a monitor, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing monitor or the monitor doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). -#### Request +#### Example request ```json PUT _plugins/_alerting/monitors/ { @@ -864,6 +855,13 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 ``` {% include copy-curl.html %} + +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -925,6 +923,8 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 ``` {% include copy-curl.html %} +
+ --- ## GET monitor @@ -935,6 +935,12 @@ GET _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -996,6 +1002,8 @@ GET _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} +
+ --- ## Monitor stats @@ -1011,6 +1019,12 @@ GET _plugins/_alerting//stats/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1184,6 +1198,8 @@ GET _plugins/_alerting//stats/ ``` {% include copy-curl.html %} +
+ --- ## DELETE monitor @@ -1194,6 +1210,12 @@ DELETE _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1213,6 +1235,8 @@ DELETE _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} +
+ --- ## Search monitors @@ -1230,6 +1254,12 @@ GET _plugins/_alerting/monitors/_search ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1309,6 +1339,8 @@ GET _plugins/_alerting/monitors/_search ``` {% include copy-curl.html %} +
+ --- ## Run monitor @@ -1321,6 +1353,12 @@ POST _plugins/_alerting/monitors//_execute ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1340,6 +1378,8 @@ POST _plugins/_alerting/monitors//_execute ``` {% include copy-curl.html %} +
+ --- ## Get alerts @@ -1369,6 +1409,13 @@ GET _plugins/_alerting/monitors/alerts ``` {% include copy-curl.html %} + +
+ + Select to expand example response + + {: .text-delta} + #### Response ```json { @@ -1425,6 +1472,8 @@ GET _plugins/_alerting/monitors/alerts ``` {% include copy-curl.html %} +
+ --- ## Acknowledge alert @@ -1440,6 +1489,13 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts ``` {% include copy-curl.html %} + +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1451,6 +1507,8 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts ``` {% include copy-curl.html %} +
+ --- ## Create destination @@ -1507,6 +1565,12 @@ POST _plugins/_alerting/destinations ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1526,6 +1590,8 @@ POST _plugins/_alerting/destinations ``` {% include copy-curl.html %} +
+ --- ## Update destination @@ -1554,6 +1620,13 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term ``` {% include copy-curl.html %} + +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1573,6 +1646,8 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term ``` {% include copy-curl.html %} +
+ --- ## Get destination @@ -1585,6 +1660,12 @@ GET _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1617,6 +1698,8 @@ GET _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} +
+ --- ## Get destinations @@ -1629,6 +1712,12 @@ GET _plugins/_alerting/destinations ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1661,6 +1750,8 @@ GET _plugins/_alerting/destinations ``` {% include copy-curl.html %} +
+ --- ## Delete destination @@ -1671,6 +1762,12 @@ DELETE _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1691,6 +1788,8 @@ DELETE _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} +
+ --- ## Create email account @@ -1708,6 +1807,12 @@ POST _plugins/_alerting/destinations/email_accounts ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1727,6 +1832,8 @@ POST _plugins/_alerting/destinations/email_accounts ``` {% include copy-curl.html %} +
+ ## Update email account When updating an email account, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing email account or the email account doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). @@ -1753,6 +1860,12 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1772,6 +1885,8 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= ``` {% include copy-curl.html %} +
+ ## Get email account #### Request @@ -1787,6 +1902,12 @@ GET _plugins/_alerting/destinations/email_accounts/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1806,6 +1927,8 @@ GET _plugins/_alerting/destinations/email_accounts/ ``` {% include copy-curl.html %} +
+ ## Delete email account #### Request @@ -1814,6 +1937,12 @@ DELETE _plugins/_alerting/destinations/email_accounts/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1834,6 +1963,8 @@ DELETE _plugins/_alerting/destinations/email_accounts/ ``` {% include copy-curl.html %} +
+ ## Search email account #### Request @@ -1854,6 +1985,12 @@ POST _plugins/_alerting/destinations/email_accounts/_search ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1898,6 +2035,8 @@ POST _plugins/_alerting/destinations/email_accounts/_search ``` {% include copy-curl.html %} +
+ --- ## Create email group @@ -1914,6 +2053,12 @@ POST _plugins/_alerting/destinations/email_groups ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1934,6 +2079,8 @@ POST _plugins/_alerting/destinations/email_groups ``` {% include copy-curl.html %} +
+ ## Update email group When updating an email group, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing email group or the email group doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). @@ -1958,6 +2105,12 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -1978,6 +2131,8 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i ``` {% include copy-curl.html %} +
+ ## Get email group #### Request @@ -1992,6 +2147,12 @@ GET _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -2012,6 +2173,8 @@ GET _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} +
+ ## Delete email group #### Request @@ -2020,6 +2183,12 @@ DELETE _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -2040,6 +2209,8 @@ DELETE _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} +
+ ## Search email group #### Request @@ -2060,6 +2231,12 @@ POST _plugins/_alerting/destinations/email_groups/_search ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -2105,6 +2282,8 @@ POST _plugins/_alerting/destinations/email_groups/_search ``` {% include copy-curl.html %} +
+ ## Create comment This is an experimental feature and is not recommended for use in a production environment. {: .warning} @@ -2118,6 +2297,12 @@ POST _plugins/_alerting/comments/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -2152,6 +2337,12 @@ PUT _plugins/_alerting/comments/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -2170,6 +2361,8 @@ PUT _plugins/_alerting/comments/ ``` {% include copy-curl.html %} +
+ ## Search comments This is an experimental feature and is not recommended for use in a production environment. {: .warning} @@ -2185,6 +2378,12 @@ GET _plugins/_alerting/comments/_search ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -2241,6 +2440,8 @@ GET _plugins/_alerting/comments/_search ``` {% include copy-curl.html %} +
+ ## Delete comment This is an experimental feature and is not recommended for use in a production environment. {: .warning} @@ -2251,6 +2452,12 @@ DELETE _plugins/_alerting/comments/ ``` {% include copy-curl.html %} +
+ + Select to expand example response + + {: .text-delta} + #### Example response ```json { @@ -2258,3 +2465,6 @@ DELETE _plugins/_alerting/comments/ } ``` {% include copy-curl.html %} + +
+ From 6257d1c65072abfd8efc6c48d7db4026e6f20026 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Mon, 17 Jun 2024 20:32:22 -0600 Subject: [PATCH 26/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 83 ++++++++++++++++++---------- 1 file changed, 53 insertions(+), 30 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 621e711dab..a8ff6a4027 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -163,6 +163,7 @@ POST _plugins/_alerting/monitors ``` {% include copy-curl.html %} +
Select to expand example response @@ -251,9 +252,7 @@ POST _plugins/_alerting/monitors
-To specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. - -The following example creates a monitor that runs at 12:10 PM Pacific Time on the 1st day of every month. +To specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. The following example creates a monitor that runs at 12:10 PM Pacific Time on the 1st day of every month. #### Example request ```json @@ -929,12 +928,13 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 ## GET monitor -#### Request +#### Example request ``` GET _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -1010,7 +1010,7 @@ GET _plugins/_alerting/monitors/ Returns statistics about the alerting feature. Use `_plugins/_alerting/stats` to find node IDs and metrics. Then you can drill down using those values. -#### Request +#### Example request ```json GET _plugins/_alerting/stats GET _plugins/_alerting/stats/ @@ -1019,6 +1019,7 @@ GET _plugins/_alerting//stats/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -1204,12 +1205,13 @@ GET _plugins/_alerting//stats/ ## DELETE monitor -#### Request +#### Example request ``` DELETE _plugins/_alerting/monitors/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -1241,7 +1243,7 @@ DELETE _plugins/_alerting/monitors/ ## Search monitors -#### Request +#### Example request ```json GET _plugins/_alerting/monitors/_search { @@ -1254,6 +1256,7 @@ GET _plugins/_alerting/monitors/_search ``` {% include copy-curl.html %} +
Select to expand example response @@ -1347,12 +1350,13 @@ GET _plugins/_alerting/monitors/_search You can add the optional `?dryrun=true` parameter to the URL to show the results of a run without actions sending any message. -#### Request +#### Example request ```json POST _plugins/_alerting/monitors//_execute ``` {% include copy-curl.html %} +
Select to expand example response @@ -1403,7 +1407,7 @@ The following table lists the available path parameters. All path parameters are | `monitorId` | String | Filters by monitor ID. | `workflowIds` | String | Allows for monitoring the status of chained alerts from multiple workflows within a single dashboard. Available in OpenSearch 2.9 or later. -#### Request +#### Example request ```json GET _plugins/_alerting/monitors/alerts ``` @@ -1416,7 +1420,7 @@ GET _plugins/_alerting/monitors/alerts {: .text-delta} -#### Response +#### Example response ```json { "alerts": [ @@ -1480,7 +1484,7 @@ GET _plugins/_alerting/monitors/alerts [After getting your alerts](#get-alerts), you can acknowledge any number of active alerts in one call. If the alert is already in an ERROR, COMPLETED, or ACKNOWLEDGED state, it appears in the `failed` array. -#### Request +#### Example request ```json POST _plugins/_alerting/monitors//_acknowledge/alerts { @@ -1496,6 +1500,7 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts
{: .text-delta} + #### Example response ```json { @@ -1513,7 +1518,7 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts ## Create destination -#### Requests +#### Example request ```json POST _plugins/_alerting/destinations { @@ -1565,6 +1570,7 @@ POST _plugins/_alerting/destinations ``` {% include copy-curl.html %} +
Select to expand example response @@ -1598,7 +1604,7 @@ POST _plugins/_alerting/destinations When updating a destination, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing destination or the destination doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). -#### Request +#### Example request ```json PUT _plugins/_alerting/destinations/ { @@ -1654,12 +1660,13 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term Retrieve one destination. -#### Requests +#### Exampe request ```json GET _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -1706,12 +1713,13 @@ GET _plugins/_alerting/destinations/ Retrieve all destinations. -#### Requests +#### Example request ```json GET _plugins/_alerting/destinations ``` {% include copy-curl.html %} +
Select to expand example response @@ -1756,12 +1764,13 @@ GET _plugins/_alerting/destinations ## Delete destination -#### Request +#### Example request ``` DELETE _plugins/_alerting/destinations/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -1794,7 +1803,7 @@ DELETE _plugins/_alerting/destinations/ ## Create email account -#### Request +#### Example request ```json POST _plugins/_alerting/destinations/email_accounts { @@ -1807,6 +1816,7 @@ POST _plugins/_alerting/destinations/email_accounts ``` {% include copy-curl.html %} +
Select to expand example response @@ -1838,7 +1848,7 @@ POST _plugins/_alerting/destinations/email_accounts When updating an email account, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing email account or the email account doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). -#### Request +#### Example request ```json PUT _plugins/_alerting/destinations/email_accounts/ { @@ -1860,6 +1870,7 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= ``` {% include copy-curl.html %} +
Select to expand example response @@ -1889,7 +1900,7 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= ## Get email account -#### Request +#### Example request ```json GET _plugins/_alerting/destinations/email_accounts/ { @@ -1902,6 +1913,7 @@ GET _plugins/_alerting/destinations/email_accounts/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -1931,12 +1943,13 @@ GET _plugins/_alerting/destinations/email_accounts/ ## Delete email account -#### Request +#### Example request ``` DELETE _plugins/_alerting/destinations/email_accounts/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -1967,7 +1980,7 @@ DELETE _plugins/_alerting/destinations/email_accounts/ ## Search email account -#### Request +#### Example request ```json POST _plugins/_alerting/destinations/email_accounts/_search { @@ -1985,6 +1998,7 @@ POST _plugins/_alerting/destinations/email_accounts/_search ``` {% include copy-curl.html %} +
Select to expand example response @@ -2041,7 +2055,7 @@ POST _plugins/_alerting/destinations/email_accounts/_search ## Create email group -#### Request +#### Example request ```json POST _plugins/_alerting/destinations/email_groups { @@ -2053,6 +2067,7 @@ POST _plugins/_alerting/destinations/email_groups ``` {% include copy-curl.html %} +
Select to expand example response @@ -2085,7 +2100,7 @@ POST _plugins/_alerting/destinations/email_groups When updating an email group, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing email group or the email group doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). -#### Request +#### Example request ```json PUT _plugins/_alerting/destinations/email_groups/ { @@ -2105,6 +2120,7 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i ``` {% include copy-curl.html %} +
Select to expand example response @@ -2135,7 +2151,7 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i ## Get email group -#### Request +#### Example request ```json GET _plugins/_alerting/destinations/email_groups/ { @@ -2147,6 +2163,7 @@ GET _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -2177,12 +2194,13 @@ GET _plugins/_alerting/destinations/email_groups/ ## Delete email group -#### Request +#### Example request ``` DELETE _plugins/_alerting/destinations/email_groups/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -2213,7 +2231,7 @@ DELETE _plugins/_alerting/destinations/email_groups/ ## Search email group -#### Request +#### Example request ```json POST _plugins/_alerting/destinations/email_groups/_search { @@ -2231,6 +2249,7 @@ POST _plugins/_alerting/destinations/email_groups/_search ``` {% include copy-curl.html %} +
Select to expand example response @@ -2288,7 +2307,7 @@ POST _plugins/_alerting/destinations/email_groups/_search This is an experimental feature and is not recommended for use in a production environment. {: .warning} -#### Request +#### Example request ```json POST _plugins/_alerting/comments/ { @@ -2297,6 +2316,7 @@ POST _plugins/_alerting/comments/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -2327,7 +2347,7 @@ POST _plugins/_alerting/comments/ This is an experimental feature and is not recommended for use in a production environment. {: .warning} -#### Request +#### Example request ```json PUT _plugins/_alerting/comments/ @@ -2337,6 +2357,7 @@ PUT _plugins/_alerting/comments/ ``` {% include copy-curl.html %} +
Select to expand example response @@ -2367,7 +2388,7 @@ PUT _plugins/_alerting/comments/ This is an experimental feature and is not recommended for use in a production environment. {: .warning} -#### Request +#### Example request ```json GET _plugins/_alerting/comments/_search { @@ -2378,6 +2399,7 @@ GET _plugins/_alerting/comments/_search ``` {% include copy-curl.html %} +
Select to expand example response @@ -2446,12 +2468,13 @@ GET _plugins/_alerting/comments/_search This is an experimental feature and is not recommended for use in a production environment. {: .warning} -#### Request +#### Example request ```json DELETE _plugins/_alerting/comments/ ``` {% include copy-curl.html %} +
Select to expand example response From b8da713c9ca2bf9bf9dc856a37efcb89533d832f Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:38:19 -0600 Subject: [PATCH 27/48] Update _observing-your-data/alerting/api.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index a8ff6a4027..419d860785 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -13,7 +13,7 @@ Use the Alerting API to programmatically create, update, and manage monitors and ## Create a query-level monitor -Query-level monitors run the query and check whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level and bucket-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). +Query-level monitors run the query and determine whether or not the results should trigger an alert. Query-level monitors can only trigger one alert at a time. For more information about query-level and bucket-level monitors, see [Creating monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/). #### Example request ```json From aa2bc9518db4b030c3ac5656ff490a208a5b1978 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:38:31 -0600 Subject: [PATCH 28/48] Update _observing-your-data/alerting/api.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 419d860785..442534b665 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -81,7 +81,7 @@ POST _plugins/_alerting/monitors {% include copy-curl.html %} -If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape your quotes. +If you use a custom webhook for your destination and need to embed JSON in the message body, be sure to escape the quotation marks: ```json { From c7fda092beba9f994c50cf6c1aa07706d0e43c93 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:38:46 -0600 Subject: [PATCH 29/48] Update _observing-your-data/alerting/api.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 442534b665..928886848f 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -252,7 +252,7 @@ POST _plugins/_alerting/monitors
-To specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. The following example creates a monitor that runs at 12:10 PM Pacific Time on the 1st day of every month. +To specify a time zone, you can do so by including a [cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) with a time zone name in the `schedule` section of your request. The following example creates a monitor that runs at 12:10 PM Pacific Time on the first day of each month. #### Example request ```json From f5e69504f28baa4b72c1df15c154ed514f4e4493 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:38:53 -0600 Subject: [PATCH 30/48] Update _observing-your-data/alerting/api.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 928886848f..25e801c83b 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -624,7 +624,7 @@ GET /_plugins/_alerting/findings/_search?findingId=gKQhj8WJit3BxjGfiOXC The response returns the number of individual finding entries in the `total_findings` field. -To get more specific results in a findings search, you can use any of the optional path parameters that are defined in the following table. +To get more specific results in a findings search, you can use any of the optional path parameters defined in the following table. Path parameter | Description | Usage :--- | :--- : :--- From 8ac09193d43586455f27272f2fa160be8752283b Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:38:59 -0600 Subject: [PATCH 31/48] Update _observing-your-data/alerting/api.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 25e801c83b..47795bc654 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -640,7 +640,7 @@ Path parameter | Description | Usage You can create a document-level monitor with a POST request that provides the monitor details in the request body. At a minimum, you need to provide the following details: specify the queries or combinations by tag with the `inputs` field, a valid trigger condition, and provide the notification message in the `action` field. -The following table shows the syntax to use for each trigger option. +The following table provides the syntax to use for each trigger option. Trigger options | Definition | Syntax :--- | :--- : :--- From 85e54b6da1c2a2a2f8d98acc9bab3a1c86574d73 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:39:19 -0600 Subject: [PATCH 32/48] Update _observing-your-data/alerting/settings.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index d6c38ecf62..e4fa3560b8 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -62,7 +62,7 @@ Setting | Default | Description `plugins.scheduled_jobs.request_timeout` | 10s | The timeout for the request that sweeps shards for jobs. `plugins.alerting.comments_enabled` | `false` | Enables or disables comments for the Alerting plugin. `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. -`plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in a `.opensearch-alerting-comments-history-` index before creating a new one. If the number of comments in this time period does not exceed `comments_history_max_docs`, one index is created per period (for example, one every 30 days). +`plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in an `.opensearch-alerting-comments-history-` index before creating a new one. If the number of comments in the specified time period does not exceed `comments_history_max_docs`, then 1 index is created per period (for example, 1 every 30 days). `plugins.alerting.comments_history_rollover_period` | 12h | How often to check if the `.opensearch-alerting-comments-history-write` alias should roll over to a new index and delete old comment history indexes. `plugins.alerting.comments_history_retention_period` | 60d | The time to keep comment history indexes before automatic deletion. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. From a6a29b46aeadc367ec0fd02d8dbd7153641da69a Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:39:26 -0600 Subject: [PATCH 33/48] Update _observing-your-data/alerting/settings.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index e4fa3560b8..c3410f472c 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -64,7 +64,7 @@ Setting | Default | Description `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. `plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in an `.opensearch-alerting-comments-history-` index before creating a new one. If the number of comments in the specified time period does not exceed `comments_history_max_docs`, then 1 index is created per period (for example, 1 every 30 days). `plugins.alerting.comments_history_rollover_period` | 12h | How often to check if the `.opensearch-alerting-comments-history-write` alias should roll over to a new index and delete old comment history indexes. -`plugins.alerting.comments_history_retention_period` | 60d | The time to keep comment history indexes before automatic deletion. +`plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comment history indexes before automatic deletion. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. `plugins.alerting.max_comments_per_alert` | 500 | The maximum number of comments that can be posted on an alert. `plugins.alerting.max_comments_per_notification` | 3 | The maximum number of comments per alert to include in the `ctx` mustache template variable for alert notifications. \ No newline at end of file From b29454d2fc2c6d93bac422679df0c9fbbec5b0b7 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:39:42 -0600 Subject: [PATCH 34/48] Update _observing-your-data/alerting/settings.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index c3410f472c..9b096aa04c 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -67,4 +67,4 @@ Setting | Default | Description `plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comment history indexes before automatic deletion. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. `plugins.alerting.max_comments_per_alert` | 500 | The maximum number of comments that can be posted on an alert. -`plugins.alerting.max_comments_per_notification` | 3 | The maximum number of comments per alert to include in the `ctx` mustache template variable for alert notifications. \ No newline at end of file +`plugins.alerting.max_comments_per_notification` | 3 | The maximum number of comments per alert to include in the `ctx` Mustache template variable for alert notifications. \ No newline at end of file From 96fd6f08e8308d6f90a8129fcb912cc2b3712573 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:40:00 -0600 Subject: [PATCH 35/48] Update _observing-your-data/alerting/comments.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index efb655ad95..3c89c7f257 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -13,7 +13,7 @@ redirect_from: This is an experimental feature and is not recommended for use in a production environment. For updates on the progress of the feature or if you want to leave feedback, see the associated [GitHub issue](https://github.com/opensearch-project/OpenSearch-Dashboards/issues/6999). {: .warning} -When an alert is generated, add comments to share insights into its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to `true` using the [`cluster/settings` API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). +When an alert is generated, add comments to share information about its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to `true` using the [`cluster/settings` API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). Comments can be accessed through the alerts table view by selecting on the comment icon within an alert's row. From there, comments can be added, edited, and deleted. An Alerting Comments API is also available for programmatic comments management. For details, see the [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). From 0968ba6fbb37faa92b0db7a5638eb9265f1f146a Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:40:39 -0600 Subject: [PATCH 36/48] Update _observing-your-data/alerting/settings.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/settings.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 9b096aa04c..7734691cbf 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -63,7 +63,7 @@ Setting | Default | Description `plugins.alerting.comments_enabled` | `false` | Enables or disables comments for the Alerting plugin. `plugins.alerting.comments_history_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-` index before creating a new index. `plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in an `.opensearch-alerting-comments-history-` index before creating a new one. If the number of comments in the specified time period does not exceed `comments_history_max_docs`, then 1 index is created per period (for example, 1 every 30 days). -`plugins.alerting.comments_history_rollover_period` | 12h | How often to check if the `.opensearch-alerting-comments-history-write` alias should roll over to a new index and delete old comment history indexes. +`plugins.alerting.comments_history_rollover_period` | 12h | How often to determine whether the `.opensearch-alerting-comments-history-write` alias should roll over to a new index and delete old comment history indexes. `plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comment history indexes before automatic deletion. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. `plugins.alerting.max_comments_per_alert` | 500 | The maximum number of comments that can be posted on an alert. From d24204c77e2263315215f4bef26bee7db68434bc Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:41:11 -0600 Subject: [PATCH 37/48] Update _observing-your-data/alerting/comments.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index 3c89c7f257..1c75d8ea4e 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -15,7 +15,7 @@ This is an experimental feature and is not recommended for use in a production e When an alert is generated, add comments to share information about its root cause and facilitate resolution. Comments are enabled by setting `plugins.alerting.comments_enabled` to `true` using the [`cluster/settings` API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/settings/). -Comments can be accessed through the alerts table view by selecting on the comment icon within an alert's row. From there, comments can be added, edited, and deleted. An Alerting Comments API is also available for programmatic comments management. For details, see the [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). +Comments can be accessed through the alerts table view by selecting the comment icon within an alert's row. From there, comments can be added, edited, or deleted. An Alerting Comments API is also available for programmatic comment management. For more information, see [Alerting API]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/api/). ## Viewing comment authors From 316d50c59882af66169dec4ce73b537f7b462923 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:41:29 -0600 Subject: [PATCH 38/48] Update _observing-your-data/alerting/comments.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index 1c75d8ea4e..e0f60c02e1 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -19,7 +19,7 @@ Comments can be accessed through the alerts table view by selecting the comment ## Viewing comment authors -If the Security plugin is installed, the comment's author is displayed. Otherwise, `Unknown` is displayed. +If the Security plugin is installed, then the comment's author is displayed. Otherwise, `Unknown` is displayed. ## Assigning permissions From 4b4b1b3a9233cfa9c62df353b52dc2bb91879a55 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:41:45 -0600 Subject: [PATCH 39/48] Update _observing-your-data/alerting/comments.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/comments.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/comments.md b/_observing-your-data/alerting/comments.md index e0f60c02e1..fb0630685c 100644 --- a/_observing-your-data/alerting/comments.md +++ b/_observing-your-data/alerting/comments.md @@ -23,4 +23,4 @@ If the Security plugin is installed, then the comment's author is displayed. Oth ## Assigning permissions -Comment permissions are determined by the backend roles associated with the alert. These backend roles are inherited from the monitor that generated the alert. For more details on how to limit access based on backend roles, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). +Comment permissions are determined by the backend roles associated with the alert. These backend roles are inherited from the monitor that generated the alert. For more information about how to limit access based on backend roles, see [Limit access by backend role]({{site.url}}{{site.baseurl}}/observing-your-data/alerting/security/#advanced-limit-access-by-backend-role). From 584cea12cf13199a55e6a9b2eb628bd4eac74cc2 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:55:45 -0600 Subject: [PATCH 40/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 47795bc654..436abb62e8 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -928,6 +928,8 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 ## GET monitor +To retrieve the details of a specific monitor, you can use the GET monitor API endpoint. + #### Example request ``` GET _plugins/_alerting/monitors/ @@ -1205,6 +1207,8 @@ GET _plugins/_alerting//stats/ ## DELETE monitor +To delete a monitor, you can send a DELETE request to the following endpoint. + #### Example request ``` DELETE _plugins/_alerting/monitors/ @@ -1243,6 +1247,8 @@ DELETE _plugins/_alerting/monitors/ ## Search monitors +The search monitors functionality allows you to query and retrieve information about existing monitors based on specific criteria, such as the monitor name. + #### Example request ```json GET _plugins/_alerting/monitors/_search @@ -1482,7 +1488,7 @@ GET _plugins/_alerting/monitors/alerts ## Acknowledge alert -[After getting your alerts](#get-alerts), you can acknowledge any number of active alerts in one call. If the alert is already in an ERROR, COMPLETED, or ACKNOWLEDGED state, it appears in the `failed` array. +[After getting your alerts](#get-alerts), you can acknowledge any number of active alerts in one call. If the alert is already in an `ERROR`, `COMPLETED`, or `ACKNOWLEDGED` state, it appears in the `failed` array. #### Example request ```json @@ -2384,7 +2390,7 @@ PUT _plugins/_alerting/comments/
-## Search comments +## Search comment This is an experimental feature and is not recommended for use in a production environment. {: .warning} From 68a332280790670b080d62e44c8e211e6df2beb5 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 13:58:21 -0600 Subject: [PATCH 41/48] Update settings.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/settings.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_observing-your-data/alerting/settings.md b/_observing-your-data/alerting/settings.md index 7734691cbf..c7eefe528b 100644 --- a/_observing-your-data/alerting/settings.md +++ b/_observing-your-data/alerting/settings.md @@ -51,7 +51,7 @@ Setting | Default | Description `plugins.alerting.alert_history_max_age` | 30d | The oldest document to store in the `.opendistro-alert-history-` index before creating a new index. If the number of alerts in this time period does not exceed `alert_history_max_docs`, alerting creates one history index per period (e.g. one index every 30 days). `plugins.alerting.alert_history_max_docs` | 1000 | The maximum number of alerts to store in the `.opendistro-alert-history-` index before creating a new index. `plugins.alerting.alert_history_enabled` | true | Whether to create `.opendistro-alerting-alert-history-` indexes. -`plugins.alerting.alert_history_retention_period` | 60d | The amount of time to keep history indexes before automatically deleting them. +`plugins.alerting.alert_history_retention_period` | 60d | The amount of time to store history indexes before automatically deleting them. `plugins.alerting.destination.allow_list` | ["chime", "slack", "custom_webhook", "email", "test_action"] | The list of allowed destinations. If you don't want to allow users to a certain type of destination, you can remove it from this list, but we recommend leaving this setting as-is. `plugins.alerting.filter_by_backend_roles` | "false" | Restricts access to monitors by backend role. See [Alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/). `plugins.alerting.cross_cluster_monitoring_enabled` | "false" | Toggles whether cluster metrics monitors support running against remote clusters. @@ -67,4 +67,4 @@ Setting | Default | Description `plugins.alerting.comments_history_retention_period` | 60d | The amount of time to keep comment history indexes before automatic deletion. `plugins.alerting.max_comment_character_length` | 2000 | The maximum character length of a comment. `plugins.alerting.max_comments_per_alert` | 500 | The maximum number of comments that can be posted on an alert. -`plugins.alerting.max_comments_per_notification` | 3 | The maximum number of comments per alert to include in the `ctx` Mustache template variable for alert notifications. \ No newline at end of file +`plugins.alerting.max_comments_per_notification` | 3 | The maximum number of comments per alert to include in the `ctx` Mustache template variable for alert notifications. From 61c7718114935b259bac52804964d5389b6b9c24 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 14:30:38 -0600 Subject: [PATCH 42/48] Update api.md Signed-off-by: Melissa Vagi Added text to address stacked headings issue Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 37 ++++++++++++++++++++++++---- 1 file changed, 32 insertions(+), 5 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 436abb62e8..8687d46a6f 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -637,8 +637,7 @@ Path parameter | Description | Usage ### Create a document-level monitor -You can create a document-level monitor with a POST request that provides the monitor details in the request body. -At a minimum, you need to provide the following details: specify the queries or combinations by tag with the `inputs` field, a valid trigger condition, and provide the notification message in the `action` field. +You can create a document-level monitor with a POST request that provides the monitor details in the request body. At a minimum, you need to provide the following details: specify the queries or combinations by tag with the `inputs` field, a valid trigger condition, and provide the notification message in the `action` field. The following table provides the syntax to use for each trigger option. @@ -744,7 +743,7 @@ If you run a document-level query while the index is getting reindexed, the API ## Update monitor -When updating a monitor, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing monitor or the monitor doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). +When updating a monitor, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers do not match the existing monitor or the monitor doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). #### Example request ```json @@ -1524,6 +1523,8 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts ## Create destination +Define and configure various destinations for receiving alert notifications. These destinations can be of different types, such as Slack, custom webhooks, or email, and are used to specify where and how alerts should be delivered. + #### Example request ```json POST _plugins/_alerting/destinations @@ -1608,7 +1609,7 @@ POST _plugins/_alerting/destinations ## Update destination -When updating a destination, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers don't match the existing destination or the destination doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). +When updating a destination, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers do not match the existing destination or the destination doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). #### Example request ```json @@ -1666,7 +1667,7 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term Retrieve one destination. -#### Exampe request +#### Example request ```json GET _plugins/_alerting/destinations/ ``` @@ -1770,6 +1771,8 @@ GET _plugins/_alerting/destinations ## Delete destination +To remove a specific destination from the alerting system, you can use the delete destination API endpoint. + #### Example request ``` DELETE _plugins/_alerting/destinations/ @@ -1809,6 +1812,8 @@ DELETE _plugins/_alerting/destinations/ ## Create email account +To set up a new email account for sending alert notifications, you can use the create email account API endpoint. + #### Example request ```json POST _plugins/_alerting/destinations/email_accounts @@ -1906,6 +1911,8 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= ## Get email account +You can retrieve the details of a specific email account configured for alerting purposes by using the GET email account API endpoint. + #### Example request ```json GET _plugins/_alerting/destinations/email_accounts/ @@ -1949,6 +1956,8 @@ GET _plugins/_alerting/destinations/email_accounts/ ## Delete email account +If you need to remove an existing email account configuration from the alerting system, you can use the DELETE email account API endpoint. + #### Example request ``` DELETE _plugins/_alerting/destinations/email_accounts/ @@ -1986,6 +1995,8 @@ DELETE _plugins/_alerting/destinations/email_accounts/ ## Search email account +The search email account functionality allows you to retrieve information about the configured email accounts used for email-based alerting by sending a search request to the designated API endpoint. + #### Example request ```json POST _plugins/_alerting/destinations/email_accounts/_search @@ -2061,6 +2072,8 @@ POST _plugins/_alerting/destinations/email_accounts/_search ## Create email group +To define a new group of email recipients for alerts, you can use the create email group API endpoint. + #### Example request ```json POST _plugins/_alerting/destinations/email_groups @@ -2157,6 +2170,8 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i ## Get email group +To retrieve the details of a specific email group destination, you can make a GET request to the `_plugins/_alerting/destinations/email_groups/` endpoint, passing the ID of the email group you want to fetch. + #### Example request ```json GET _plugins/_alerting/destinations/email_groups/ @@ -2200,6 +2215,8 @@ GET _plugins/_alerting/destinations/email_groups/ ## Delete email group +To remove an existing email group from the list of destinations for alerts, you can use the DELETE email group API endpoint. + #### Example request ``` DELETE _plugins/_alerting/destinations/email_groups/ @@ -2237,6 +2254,8 @@ DELETE _plugins/_alerting/destinations/email_groups/ ## Search email group +The search email group functionality allows you to query and retrieve information about existing email groups used for alerting purposes, enabling you to filter and sort the results based on various criteria. + #### Example request ```json POST _plugins/_alerting/destinations/email_groups/_search @@ -2313,6 +2332,8 @@ POST _plugins/_alerting/destinations/email_groups/_search This is an experimental feature and is not recommended for use in a production environment. {: .warning} +The Create Comment API allows you to add comments to a specific alert, providing additional context or notes related to that alert. + #### Example request ```json POST _plugins/_alerting/comments/ @@ -2353,6 +2374,8 @@ POST _plugins/_alerting/comments/ This is an experimental feature and is not recommended for use in a production environment. {: .warning} +The Update Comment API allows you to modify the content of a previously added comment associated with an alert. + #### Example request ```json @@ -2394,6 +2417,8 @@ PUT _plugins/_alerting/comments/ This is an experimental feature and is not recommended for use in a production environment. {: .warning} +The Search Comment API allows you to query and retrieve existing comments associated with alerts. + #### Example request ```json GET _plugins/_alerting/comments/_search @@ -2474,6 +2499,8 @@ GET _plugins/_alerting/comments/_search This is an experimental feature and is not recommended for use in a production environment. {: .warning} +The Delete Comment API allows you to remove a specific comment associated with an alert. + #### Example request ```json DELETE _plugins/_alerting/comments/ From aee2f5b817ac32f127f8d468c6275cadb6482464 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 15:06:48 -0600 Subject: [PATCH 43/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 44 ++++++++++++++-------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 8687d46a6f..af9a5926ca 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -925,9 +925,9 @@ PUT _plugins/_alerting/monitors/?if_seq_no=3&if_primary_term=1 --- -## GET monitor +## Get monitor -To retrieve the details of a specific monitor, you can use the GET monitor API endpoint. +Retrieve the details of a specific monitor using the following request. #### Example request ``` @@ -1204,9 +1204,9 @@ GET _plugins/_alerting//stats/ --- -## DELETE monitor +## Delete monitor -To delete a monitor, you can send a DELETE request to the following endpoint. +Delete a monitor using the following request. #### Example request ``` @@ -1246,7 +1246,7 @@ DELETE _plugins/_alerting/monitors/ ## Search monitors -The search monitors functionality allows you to query and retrieve information about existing monitors based on specific criteria, such as the monitor name. +Query and retrieve information about existing monitors based on specific criteria, such as the monitor name, using the following request. #### Example request ```json @@ -1393,7 +1393,7 @@ POST _plugins/_alerting/monitors//_execute ## Get alerts -Returns an array of all alerts. +Return an array of all alerts. #### Path parameters @@ -1523,7 +1523,7 @@ POST _plugins/_alerting/monitors//_acknowledge/alerts ## Create destination -Define and configure various destinations for receiving alert notifications. These destinations can be of different types, such as Slack, custom webhooks, or email, and are used to specify where and how alerts should be delivered. +Define and configure various destinations for receiving alert notifications using the following request. These destinations can be of different types, such as Slack, custom webhooks, or email, and are used to specify where and how alerts should be delivered. #### Example request ```json @@ -1665,7 +1665,7 @@ PUT _plugins/_alerting/destinations/?if_seq_no=3&if_primary_term ## Get destination -Retrieve one destination. +Retrieve one destination using the following request. #### Example request ```json @@ -1718,7 +1718,7 @@ GET _plugins/_alerting/destinations/ ## Get destinations -Retrieve all destinations. +Retrieve all destinations using the following request. #### Example request ```json @@ -1771,7 +1771,7 @@ GET _plugins/_alerting/destinations ## Delete destination -To remove a specific destination from the alerting system, you can use the delete destination API endpoint. +Remove a specific destination from the alerting system using the following request. #### Example request ``` @@ -1812,7 +1812,7 @@ DELETE _plugins/_alerting/destinations/ ## Create email account -To set up a new email account for sending alert notifications, you can use the create email account API endpoint. +Set up a new email account for sending alert notifications using the following request. #### Example request ```json @@ -1911,7 +1911,7 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= ## Get email account -You can retrieve the details of a specific email account configured for alerting purposes by using the GET email account API endpoint. +Retrieve the details of a specific email account configured for alerting purposes by using the following request. #### Example request ```json @@ -1956,7 +1956,7 @@ GET _plugins/_alerting/destinations/email_accounts/ ## Delete email account -If you need to remove an existing email account configuration from the alerting system, you can use the DELETE email account API endpoint. +Remove an existing email account configuration from the alerting system using the following request. #### Example request ``` @@ -1995,7 +1995,7 @@ DELETE _plugins/_alerting/destinations/email_accounts/ ## Search email account -The search email account functionality allows you to retrieve information about the configured email accounts used for email-based alerting by sending a search request to the designated API endpoint. +Retrieve information about the configured email accounts used for email-based alerting using the following request. #### Example request ```json @@ -2072,7 +2072,7 @@ POST _plugins/_alerting/destinations/email_accounts/_search ## Create email group -To define a new group of email recipients for alerts, you can use the create email group API endpoint. +Define a new group of email recipients for alerts using the following request. #### Example request ```json @@ -2170,7 +2170,7 @@ PUT _plugins/_alerting/destinations/email_groups/?if_seq_no=16&i ## Get email group -To retrieve the details of a specific email group destination, you can make a GET request to the `_plugins/_alerting/destinations/email_groups/` endpoint, passing the ID of the email group you want to fetch. +Retrieve the details of a specific email group destination using the following request, passing the ID of the email group you want to fetch. #### Example request ```json @@ -2215,7 +2215,7 @@ GET _plugins/_alerting/destinations/email_groups/ ## Delete email group -To remove an existing email group from the list of destinations for alerts, you can use the DELETE email group API endpoint. +Remove an existing email group from the list of destinations for alerts using the following request. #### Example request ``` @@ -2254,7 +2254,7 @@ DELETE _plugins/_alerting/destinations/email_groups/ ## Search email group -The search email group functionality allows you to query and retrieve information about existing email groups used for alerting purposes, enabling you to filter and sort the results based on various criteria. +Query and retrieve information about existing email groups used for alerting purposes, enabling you to filter and sort the results based on various criteria. An example is shown in the following request. #### Example request ```json @@ -2332,7 +2332,7 @@ POST _plugins/_alerting/destinations/email_groups/_search This is an experimental feature and is not recommended for use in a production environment. {: .warning} -The Create Comment API allows you to add comments to a specific alert, providing additional context or notes related to that alert. +Add comments to a specific alert, providing additional context or notes related to that alert using the following request. #### Example request ```json @@ -2374,7 +2374,7 @@ POST _plugins/_alerting/comments/ This is an experimental feature and is not recommended for use in a production environment. {: .warning} -The Update Comment API allows you to modify the content of a previously added comment associated with an alert. +Modify the content of a previously added comment associated with an alert using the following request. #### Example request @@ -2417,7 +2417,7 @@ PUT _plugins/_alerting/comments/ This is an experimental feature and is not recommended for use in a production environment. {: .warning} -The Search Comment API allows you to query and retrieve existing comments associated with alerts. +Query and retrieve existing comments associated with alerts using the following request. #### Example request ```json @@ -2499,7 +2499,7 @@ GET _plugins/_alerting/comments/_search This is an experimental feature and is not recommended for use in a production environment. {: .warning} -The Delete Comment API allows you to remove a specific comment associated with an alert. +Remove a specific comment associated with an alert using the following request. #### Example request ```json From 49ea8ccc33332175d03f3b5f613c173ab2a056ac Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Tue, 18 Jun 2024 15:08:07 -0600 Subject: [PATCH 44/48] Update _observing-your-data/alerting/api.md Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index af9a5926ca..737e7c5217 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -743,7 +743,7 @@ If you run a document-level query while the index is getting reindexed, the API ## Update monitor -When updating a monitor, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers do not match the existing monitor or the monitor doesn't exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). +When updating a monitor, you can optionally include `seq_no` and `primary_term` as URL parameters. If these numbers do not match the existing monitor or the monitor does not exist, the Alerting plugin throws an error. OpenSearch increments the version number and the sequence number automatically (see the example response). #### Example request ```json From a5f6b500bc7de627986b253fb06b16992f855365 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Wed, 19 Jun 2024 09:00:57 -0600 Subject: [PATCH 45/48] Update api.md Signed-off-by: Melissa Vagi Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 737e7c5217..80c36e2588 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -1911,7 +1911,7 @@ PUT _plugins/_alerting/destinations/email_accounts/?if_seq_no= ## Get email account -Retrieve the details of a specific email account configured for alerting purposes by using the following request. +Retrieve the details of a specific email account configured for alerting purposes using the following request. #### Example request ```json From e99c2545b10d8ed9923ea4dbbe9365300433389c Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Wed, 19 Jun 2024 09:02:00 -0600 Subject: [PATCH 46/48] Update _observing-your-data/alerting/api.md Co-authored-by: Nathan Bower Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/api.md b/_observing-your-data/alerting/api.md index 80c36e2588..d25323084a 100644 --- a/_observing-your-data/alerting/api.md +++ b/_observing-your-data/alerting/api.md @@ -2332,7 +2332,7 @@ POST _plugins/_alerting/destinations/email_groups/_search This is an experimental feature and is not recommended for use in a production environment. {: .warning} -Add comments to a specific alert, providing additional context or notes related to that alert using the following request. +Add comments to a specific alert, providing additional context or notes related to that alert, using the following request. #### Example request ```json From b54e5c179658815dd2721a7284283596a8b4cf94 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Wed, 19 Jun 2024 12:38:55 -0600 Subject: [PATCH 47/48] Fix broken link Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/cron.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/cron.md b/_observing-your-data/alerting/cron.md index b37d13e576..c595d29871 100644 --- a/_observing-your-data/alerting/cron.md +++ b/_observing-your-data/alerting/cron.md @@ -63,4 +63,4 @@ Every three hours on the first day of every other month: ## API -For an example of how to use a custom cron expression in an API call, see the [create monitor API operation]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/api#request-1). +For an example of how to use a custom cron expression in an API call, see the [create monitor API operation]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/api/). From 7991b4194d5db0af8c5b6fa7afd674d9b1ca59d7 Mon Sep 17 00:00:00 2001 From: Melissa Vagi Date: Wed, 19 Jun 2024 12:47:32 -0600 Subject: [PATCH 48/48] Fix broken link Signed-off-by: Melissa Vagi --- _observing-your-data/alerting/cron.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_observing-your-data/alerting/cron.md b/_observing-your-data/alerting/cron.md index c595d29871..11a91609dd 100644 --- a/_observing-your-data/alerting/cron.md +++ b/_observing-your-data/alerting/cron.md @@ -63,4 +63,4 @@ Every three hours on the first day of every other month: ## API -For an example of how to use a custom cron expression in an API call, see the [create monitor API operation]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/api/). +For an example of how to use a custom cron expression in an API call, see the [create monitor API operation]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/api/#example-request-2).