Suppressions enable you to suspend alarm notifications for a set period of time. A single suppression can apply to any number of alarms. For example, you would use one suppression to suppress all alarm notifications during a scheduled maintenance period this week and another suppression for some expected downtime the following week. When creating a suppression, you specify the following:
- A timestamp at which to start the suppression (specified as milliseconds since the Unix epoch in UTC). You can use 0 to represent now.
- A timestamp at which to end the suppression (specify as milliseconds since the Unix epoch in UTC). You can use 0 to represent now.
- At least one of the following: a list of notification plans (specified by ID), a list of entities (specified by ID), a list of checks (specified by entityID:checkID), a list of alarms (specified by entityID:alarmID).
Attributes
Name | Description | Validation |
---|---|---|
alarms | A list of alarm IDs (e.g. “enFooBar:alAbc123”) for determining notification suppression. | Optional Array [String,Non-empty string] * Array or object with number of items between 0 and 512 |
checks | A list of check IDs (e.g. “enFooBar:chAbc123”) for determining notification suppression. | Optional Array [String,Non-empty string] * Array or object with number of items between 0 and 512 |
end_time | The Unix timestamp in milliseconds that the suppression will end. Specify 0 to use the current time. | Optional Integer |
entities | A list of entity IDs for determining notification suppression. | Optional Array [String,Non-empty string] * Array or object with number between 0 and 512 |
label | A friendly label for a suppression. | Optional String between 1 and 255 characters long |
notification_plans | A list of notification plan IDs for determining notification suppression. | Optional Array [String,Non-empty string] * Array or object with number of items between 0 and 512 |
start_time | The Unix timestamp in milliseconds that the suppression will start. Specify 0 to use the current time. | Optional Integer |
Use the following suppressions API operations to create, view, update, and manage suppression templates.
- Create suppression
- List suppressions
- Get a suppression by ID
- Update a suppression
- Delete suppression
Create suppression
POST /suppressions
Creates a new suppression.
Specify the characteristics for the suppression using a valid set of parameters from the suppressions attributes table.
The different lists (notification_plans, entities, checks, and alarms) represent the different levels at which suppressions can be defined. When creating a suppression, carefully consider which scopes you want to use in order to avoid accidentally suppressing an alarm you did not mean to.
Note
When creating a suppression, the start_time can only be set to 0 or a time in the future. There is some wiggle room allocated to account for the time it takes to receive and process a request, meaning that if the start_time is less than 60 seconds in the past, it will be considered to be now instead of causing a validation error. If you want the suppression to begin immediately, set the start_time to 0.
The following table shows the possible response codes for this operation:
Response Code | Name | Description |
---|---|---|
201 | OK | The ‘Location’ header contains a link to the newly created suppression. |
400 | Bad request | The system received an invalid value in a request. |
401 | Unauthorized | The system received a request from a user that is not authenticated. |
403 | Forbidden | The system received a request that the user is not authorized to make. |
500 | Internal Server Error | An unexpected condition was encountered. |
503 | Service Unavailable | The system is experiencing heavy load or another system failure. |
The following table shows the header parameters for the request:
Name | Type | Description |
---|---|---|
X-Auth-Token | String (Required) | A valid authentication token with administrative access. For details, see Get your credentials |
Example: Suppress notifications for alarms on check ch123 on entity en123 using the notification plan npfooBar
{
"notification_plans": ["npfooBar"],
"checks": ["en123:ch123"],
"start_time": 1378492433027,
"end_time": 1378492433027
}
Example: Suppress notifications for entity en123 for all notification plans
{
"entities": ["en123"],
"checks": ["en123:ch123"],
"start_time": 1378492433027,
"end_time": 1378492433027
}
Example: Suppress only check ch123 on entity en123 for all notification plans
{
"checks": ["en123:ch123"],
"start_time": 1378492433027,
"end_time": 1378492433027
}
Example: Suppress all notifications for entity enMonkey and notifications for check ch123 on entity en123 for all notification plans
{
"entities": ["enMonkey"],
"checks": ["en123:ch123"],
"start_time": 1378492433027,
"end_time": 1378492433027
}
Example: Suppress all notifications for notification plan npTechnical
{
"notification_plans": ["npTechnical"],
"start_time": 1378492433027,
"end_time": 1378492433027
}
Example: Suppress alarm al123 on entity en123 and alarm alBaz on entity enMonkey for the notification plan npTechnical
{
"notification_plans": ["npTechnical"],
"alarms": ["en123:al123", "enMonkey:alBaz"],
"start_time": 1378492433027,
"end_time": 1378492433027
}
This operation does not return a response body.
List suppressions
GET /suppressions
Lists the suppressions. Use /supressions?id=supressionOneId & id=supressionTwoId
to filter the results to only include information about the specified suppressions.
This operation can be paginated. For information, see Paginated collections.
The following table shows the possible response codes for this operation:
Response Code | Name | Description |
---|---|---|
200 | OK | Request completed. |
401 | Unauthorized | The system received a request from a user that is not authenticated. |
403 | Forbidden | The system received a request that the user is not authorized to make. |
500 | Internal Server Error | An unexpected condition was encountered. |
503 | Service Unavailable | The system is experiencing heavy load or another system failure. |
The following table shows the header parameters for the request:
Name | Type | Description |
---|---|---|
X-Auth-Token | String (Required) | A valid authentication token with administrative access. For details, see Get your credentials |
Note
This operation does not accept a request body.
Example List Suppressions: JSON response
{
"values": [
{
"id": "spAAAAA",
"notification_plans": ['npfooBar'],
"entities": [],
"checks": ['en123:ch123'],
"alarms": [],
"start_time": 1378492433027,
"end_time": 1378492433027
}
],
"metadata": {
"count": 1,
"limit": 50,
"marker": null,
"next_marker": null,
"next_href": null
}
}
Get a suppression by ID
GET /suppressions/{suppressionId}
This operation returns the suppression specified by the suppressionId
.
The following table shows the possible response codes for this operation:
Response Code | Name | Description |
---|---|---|
200 | OK | Request completed. |
401 | Unauthorized | The system received a request from a user that is not authenticated. |
403 | Forbidden | The system received a request that the user is not authorized to make. |
404 | Not Found | The URL, entity, or account requested is not found in the system. |
500 | Internal Server Error | An unexpected condition was encountered. |
503 | Service Unavailable | The system is experiencing heavy load or another system failure. |
The following table shows the header parameters for the request:
Name | Type | Description |
---|---|---|
X-Auth-Token | String (Required) | A valid authentication token with administrative access. For details, see Get your credentials |
Note
This operation does not accept a request body.
Example Get suppression by ID: JSON response
{
"id": "spAAAAA",
"notification_plans": ['npfooBar'],
"entities": [],
"checks": ['en123:ch123'],
"alarms": [],
"start_time": 1378492433027,
"end_time": 1378492433027
}
Update a suppression
PUT /suppressions/{suppressionId}
Updates the suppression specified by the suppressionId
.
You can complete partial updates for a suppression. When you submit the request only include values for the attributes you want to update. The values on omitted parameters are not updated. Note that updating a list completely replaces the previous list. Refer to the suppressions attributes table.
Note
Keep the following points in mind when updating a suppression:
- Until the start_time, you can modify any field on the suppression; however, after that time has passed and the suppression has begun only the end_time can be updated.
- The end_time can only be set to 0 or a time in the future. As with the start_time, there is an allowance of 60 seconds made to account for the time it takes to receive and process a request. This means that if the provided end_time is less than 60 seconds in the past, it will be considered to be now instead of causing a validation error. If you want the suppression to end immediately, set the end_time to 0.
The following table shows the possible response codes for this operation:
Response Code | Name | Description |
---|---|---|
204 | No Content | The server has fulfilled the request. Does not return a response body. |
400 | Bad request | The system received an invalid value in a request. |
401 | Unauthorized | The system received a request from a user that is not authenticated. |
403 | Forbidden | The system received a request that the user is not authorized to make. |
404 | Not Found | The URL, entity, or account requested is not found in the system. |
500 | Internal Server Error | An unexpected condition was encountered. |
503 | Service Unavailable | The system is experiencing heavy load or another system failure. |
The following table shows the header parameters for the request:
Name | Type | Description |
---|---|---|
X-Auth-Token | String (Required) | A valid authentication token with administrative access. For details, see Get your credentials |
Example Update suppression: JSON request
{
"entities": ["en234"],
"end_time": 1378495433027
}
This operation does not return a response body.
Delete suppression
DELETE /suppressions/{suppressionId}
Delete a suppression from your account.
Note
You can delete a suppression at any point, even while it is active. If an active suppression is deleted, it ends immediately.
The following table shows the possible response codes for this operation:
Response Code | Name | Description |
---|---|---|
204 | No Content | The server has fulfilled the request. Does not return a response body. |
401 | Unauthorized | The system received a request from a user that is not authenticated. |
403 | Forbidden | The system received a request that the user is not authorized to make. |
404 | Not Found | The URL, entity, or account requested is not found in the system. |
500 | Internal Server Error | An unexpected condition was encountered. |
503 | Service Unavailable | The system is experiencing heavy load or another system failure. |
The following table shows the header parameters for the request:
Name | Type | Description |
---|---|---|
X-Auth-Token | String (Required) | A valid authentication token with administrative access. For details, see Get your credentials |
Note
This operation does not accept a request body.
This operation does not return a response body.