[DOC] Add backend documentation about configuring ISM notifications (#4210)
* Add new documentation page Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Add new documentation Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Writing Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Writing Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Fix code example format Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Copy editing Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Copy editing Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Spelling error Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Add console sentence Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Address tech review feedback Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Address doc review comments Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Address doc review changes Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Address doc review comments Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Address doc review feedback Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Address doc review feedback Signed-off-by: Melissa Vagi <vagimeli@amazon.com> * Add more info to notification settings Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Reword for clarity Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Implemented tech review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Update _im-plugin/notifications-settings.md Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update _im-plugin/notifications-settings.md Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update _im-plugin/notifications-settings.md Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update _im-plugin/notifications-settings.md Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update _im-plugin/notifications-settings.md Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update _im-plugin/notifications-settings.md Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Update _im-plugin/notifications-settings.md Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Doc review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> --------- Signed-off-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Fanit Kolchina <kolchfa@amazon.com> Co-authored-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Heather Halter <HDHALTER@AMAZON.COM>
This commit is contained in:
Melissa Vagi
GitHub
parent
1ae4a86f0c
commit
78297a1997
|
|
@ -0,0 +1,237 @@
|
|||
---
|
||||
layout: default
|
||||
title: Notification settings
|
||||
nav_order: 100
|
||||
---
|
||||
|
||||
# Notification settings
|
||||
|
||||
Introduced 2.8
|
||||
{: .label .label-purple }
|
||||
|
||||
You can use notification settings to configure notifications about long-running index operations. Set up automatic [notifications]({{site.url}}{{site.baseurl}}/observing-your-data/notifications/index/) when long-running index operations are complete by [using Notifications in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/dashboards/im-dashboards/notifications/) or through the API.
|
||||
|
||||
Configuring notification settings is useful for long-running index operations, such as `open`, `reindex`, `resize`, and `force merge`. When you send a request for those operations and set the `wait_for_completion` parameter to `false`, the operation returns immediately and the response contains a task ID. You can use that task ID to configure notifications for this operation.
|
||||
|
||||
## Configuring notification settings
|
||||
|
||||
You can configure long-running operation notifications through the API by using the `task_id` and `action_name` parameters:
|
||||
|
||||
- **One-time setting**: If you pass `task_id` in the `lron_config` object, the task runs one time and the setting is automatically deleted when the task ends. If you pass both `task_id` and `action_name`, `action_name` is ignored but may be useful to you for searching and debugging notification settings.
|
||||
- **Global, persistent setting**: If you pass `action_name` and not `task_id` in the `lron_config` object, the task is global and persistent and applies to all operations of this action type.
|
||||
|
||||
The following table lists the parameters for long-running index operation notifications.
|
||||
|
||||
| Parameter | Type | Description |
|
||||
| :--- | :--- | :--- |
|
||||
| `lron_config` | Object | Long-running index operation notification configuration. |
|
||||
| `task_id` | String | The task ID of the task that you want to be notified about. Optional. One of `task_id` and `action_name` must be specified.|
|
||||
| `action_name` | String | The operation type that you want to be notified about. Provide `action_name` but not `task_id` to be notified of all operations of this type. Supported values are `indices:data/write/reindex`, `indices:admin/resize`, `indices:admin/forcemerge`, and `indices:admin/open`. Optional. One of `task_id` and `action_name` must be specified. |
|
||||
| `lron_condition` | Object | Specifies which events you want to be notified about. Optional. If not provided, you'll be notified of both the operation success and failure. |
|
||||
| `lron_condition.success` | Boolean | Set this parameter to `true` to be notified when the operation succeeds. Optional. Default is `true`. |
|
||||
| `lron_condition.failure` | Boolean | Set this parameter to `true` to be notified when the operation fails or times out. Optional. Default is `true`. |
|
||||
| `channels` | Object | Supported communication channels include Amazon Chime, Amazon Simple Notification Service (Amazon SNS), Amazon Simple Email Service (Amazon SES), email through SMTP, Slack, and custom webhooks. If either `lron_condition.success` or `lron_condition.failure` is `true`, `channels` must contain at least one channel. Learn how to configure notification channels in [Notifications]({{site.url}}{{site.baseurl}}/observing-your-data/notifications/index/). |
|
||||
|
||||
## Create notification settings
|
||||
|
||||
The following example request sets up notifications on a failure of a reindex task:
|
||||
|
||||
```json
|
||||
POST /_plugins/_im/lron
|
||||
{
|
||||
"lron_config": {
|
||||
"task_id":"dQlcQ0hQS2mwF-AQ7icCMw:12354",
|
||||
"action_name":"indices:data/write/reindex",
|
||||
"lron_condition": {
|
||||
"success": false,
|
||||
"failure": true
|
||||
},
|
||||
"channels":[
|
||||
{"id":"channel1"},
|
||||
{"id":"channel2"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The preceding request results in the following response:
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "LRON:dQlcQ0hQS2mwF-AQ7icCMw:12354",
|
||||
"lron_config": {
|
||||
"lron_condition": {
|
||||
"success": false,
|
||||
"failure": true
|
||||
},
|
||||
"task_id": "dQlcQ0hQS2mwF-AQ7icCMw:12354",
|
||||
"action_name": "indices:data/write/reindex",
|
||||
"channels": [
|
||||
{
|
||||
"id": "channel1"
|
||||
},
|
||||
{
|
||||
"id": "channel2"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Notification setting ID
|
||||
|
||||
The response returns an ID for the notification setting in the `_id` field. You can use this ID to read, update, or delete this notification setting. For a global `lron_config`, the ID is in the form `LRON:<action_name>` (for example, `LRON:indices:data/write/reindex`).
|
||||
|
||||
The `action_name` may contain a slash character (`/`), which must be HTTP encoded as `%2F` if you use it the Dev Tools console. For example, `LRON:indices:data/write/reindex` becomes `LRON:indices:data%2Fwrite%2Freindex`.
|
||||
{: .important}
|
||||
|
||||
For a task `lron_config`, the ID is in the form `LRON:<task ID>`.
|
||||
|
||||
## Retrieve notification settings
|
||||
|
||||
The following examples retrieve the current configured notification settings.
|
||||
|
||||
Use the following request to retrieve a notification setting with the specified [notification setting ID](#notification-setting-id):
|
||||
|
||||
```json
|
||||
GET /_plugins/_im/lron/<lronID>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
For example, the following request retrieves the notification setting for the `reindex` operation:
|
||||
|
||||
```json
|
||||
{
|
||||
"lron_configs": [
|
||||
{
|
||||
"_id": "LRON:indices:data/write/reindex",
|
||||
"lron_config": {
|
||||
"lron_condition": {
|
||||
"success": false,
|
||||
"failure": true
|
||||
},
|
||||
"action_name": "indices:data/write/reindex",
|
||||
"channels": [
|
||||
{
|
||||
"id": "my_chime"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"total_number": 1
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
Use the following request to retrieve all notification settings:
|
||||
|
||||
```json
|
||||
GET /_plugins/_im/lron
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The response contains all configured notification settings with their IDs:
|
||||
|
||||
```json
|
||||
{
|
||||
"lron_configs": [
|
||||
{
|
||||
"_id": "LRON:indices:admin/open",
|
||||
"lron_config": {
|
||||
"lron_condition": {
|
||||
"success": false,
|
||||
"failure": false
|
||||
},
|
||||
"action_name": "indices:admin/open",
|
||||
"channels": []
|
||||
}
|
||||
},
|
||||
{
|
||||
"_id": "LRON:indices:data/write/reindex",
|
||||
"lron_config": {
|
||||
"lron_condition": {
|
||||
"success": false,
|
||||
"failure": true
|
||||
},
|
||||
"action_name": "indices:data/write/reindex",
|
||||
"channels": [
|
||||
{
|
||||
"id": "my_chime"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"total_number": 2
|
||||
}
|
||||
```
|
||||
|
||||
## Update notification settings
|
||||
|
||||
The following example modifies an existing notification setting with the specified [notification setting ID](#notification-setting-id):
|
||||
|
||||
```json
|
||||
PUT /_plugins/_im/lron/<lronID>
|
||||
{
|
||||
"lron_config": {
|
||||
"task_id":"dQlcQ0hQS2mwF-AQ7icCMw:12354",
|
||||
"action_name":"indices:data/write/reindex",
|
||||
"lron_condition": {
|
||||
"success": false,
|
||||
"failure": true
|
||||
},
|
||||
"channels":[
|
||||
{"id":"channel1"},
|
||||
{"id":"channel2"}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The response contains the updated setting:
|
||||
|
||||
```json
|
||||
{
|
||||
"_id": "LRON:dQlcQ0hQS2mwF-AQ7icCMw:12354",
|
||||
"lron_config": {
|
||||
"lron_condition": {
|
||||
"success": false,
|
||||
"failure": true
|
||||
},
|
||||
"task_id": "dQlcQ0hQS2mwF-AQ7icCMw:12354",
|
||||
"action_name": "indices:data/write/reindex",
|
||||
"channels": [
|
||||
{
|
||||
"id": "channel1"
|
||||
},
|
||||
{
|
||||
"id": "channel2"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Delete notification settings
|
||||
|
||||
The following example removes a notifications setting with the specified [notification setting ID](#notification-setting-id):
|
||||
|
||||
```json
|
||||
DELETE /_plugins/_im/lron/<lronID>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
For example, the following request deletes the notification setting for the `reindex` operation:
|
||||
|
||||
```json
|
||||
DELETE _plugins/_im/lron/LRON:indices:data%2Fwrite%2Freindex
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
## Next steps
|
||||
|
||||
- Learn more about the [ISM API]({{site.url}}{{site.baseurl}}/im-plugin/ism/api/).
|
||||
- Learn more about the [Notifications]({{site.url}}{{site.baseurl}}/observing-your-data/notifications/index/) application.
|
||||
Loading…
Reference in New Issue