Add doc for alerting comments

_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/<alert-id>
+{
+  "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/<comment-id>
+{
+  "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/<comment-id>
+```
+
+#### Example response
+
+```json
+{
+  "_id": "0U6aBJABVWc3FrmWer9s"
+}
+```
 ---

_observing-your-data/alerting/comments.md

@@ -0,0 +1,24 @@
+---
+layout: default
+title: Adding comments
+nav_order: 35
+parent: Alerting
+has_children: false
+redirect_from:
+  - /monitoring-plugins/alerting/comments/
+---
+
+# 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](<insert-issue-link>).    
+{: .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/).
+
+## Viewing comment authors
+
+If the Security plugin is installed, the author of a comment is displayed. Otherwise, comments on alerts are shown as `Unknown`.
+
+## 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).

_observing-your-data/alerting/settings.md

@@ -60,3 +60,11 @@
 `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_max_docs` | 1000 | The maximum number of comments to store in the `.opensearch-alerting-comments-history-<date>` index before creating a new index.
+`plugins.alerting.comments_history_max_age` | 30d | The oldest document to store in the `.opensearch-alerting-comments-history-<date>` 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.