Alerts APIs

Create an Alert Definition

Required Permissions

You must have the Create Alert Definition permission to perform this operation.

Description

Create an alert definition. Send a JSON request that includes the AlertDefinition fields. You will receive a response with the alert definition ID.

Headers

Authorization: Bearer <JWT Token>
Accept: application/json;api-version=0.14

API

/api/alert-definitions

Method

POST

Required Parameters


Name	Description
name `string`	Name of the alert definition.
description `string`	Alert definition description.
deviceTemplateIds	List of device template IDs.
properties	Property value based on which the alert is triggered.
metrics `string`	List of metrics the alert definition depends on.
triggerCount `integer`	Number of times metric must exceed threshold to trigger.
recommendation `string`	Recommended actions when alerts are triggered.
symptoms `array`	The alert definition symptom. lambda: Alert condition. alertSeverity: CRITICAL WARNING INFO NORMAL
alertTemplate `string`	Alert template: `THRESHOLD`
notificationDefinitionId `string`	Notification definition ID.
savedSearchIds	List of saved search IDs.

Input Example

{
  "name": "ABC Alert",
  "description": "High CPU Alert",
  "deviceTemplateIds": [
    "Dell5K",
    "Dell6K",
    "Dell7K"
  ],
  "savedSearchIds": [],
  "metrics": [
    "CPU"
  ],
  "triggerCount": 1,
  "cancelCount": 1,
  "recommendation": "Offload some processes from this machine",
  "duration": 1,
  "isRealTime": true,
  "symptoms": [
    {
      "lambda": "\"CPU(INT64)\" >= 90",
      "alertSeverity": "CRITICAL"
    },
    {
      "lambda": "\"CPU(INT64)\" >= 70",
      "alertSeverity": "WARNING"
    }
  ],
  "alertTemplate": "THRESHOLD",
  "notificationId": "12"
}

Response Example

{
  "alertDefId": "0f70d96a-36b3-47c3-ab34-339bd3f697bd"
}

Get Details of an Alert Definition

Required Permissions: You must have the View Alert Definition permission to perform this operation.
Description: Get the details of an alert definition.
API: /api/alert-definitions/{alert_def_id}

Method

GET

Required Parameters


Name	Description
alert_def_id `string`	Alert definition ID created by the service.

Response

{
  "lastUpdatedTime": "string",
  "alertDef": {
    "name": "string",
    "triggerCount": 0,
    "symptoms": [
      {
        "lambda": "string",
        "alertSeverity": "UNKNOWN_SEVERITY"
      }
    ],
    "metrics": [
      "string"
    ],
    "notificationId": "string",
    "recommendation": "string",
    "alertTemplate": "UNKNOWN_TEMPLATE",
    "deviceTemplateId": "string",
    "description": "string"
  },
  "lastUpdatedBy": "string",
  "updateVersion": 0,
  "createdBy": "string",
  "createdTime": "string",
  "alertDefId": "string"
}

Update an Alert Definition

Required Permissions: You must have the Edit Alert Definition permission to perform this operation.
Description: Update the fields of an alert definition. Send a JSON request that includes all the fields of AlertDefinition, including non-updated fields. Missing fields will overwrite the existing values with default values. You will get a response with the alert definition ID.
API: /api/alert-definitions/{alert_def_id}

Method

PUT

Required Parameters


Name	Description
name `string`	Name of the alert definition.
description `string`	Alert definition description.
deviceTemplateIds	List of device template IDs.
properties	Property value based on which the alert is triggered.
metrics `string`	List of metrics the alert definition depends on.
triggerCount `integer`	Number of times metric must exceed threshold to trigger.
recommendation `string`	Recommended actions when alerts are triggered.
symptoms `array`	The alert definition symptom. lambda: Alert condition. alertSeverity: CRITICAL WARNING INFO NORMAL
alertTemplate `string`	Alert template: `THRESHOLD`
notificationDefinitionId `string`	Notification definition ID.
savedSearchIds	List of saved search IDs.

Input Example

{
  "name": "ABC Alert",
  "description": "High CPU Alert",
  "deviceTemplateIds": [
    "Dell5K",
    "Dell6K",
    "Dell7K"
  ],
  "savedSearchIds": [],
  "metrics": [
    "CPU"
  ],
  "triggerCount": 1,
  "cancelCount": 1,
  "recommendation": "Offload some processes from this machine",
  "duration": 1,
  "isRealTime": true,
  "symptoms": [
    {
      "lambda": "\"CPU(INT64)\" >= 90",
      "alertSeverity": "CRITICAL"
    },
    {
      "lambda": "\"CPU(INT64)\" >= 70",
      "alertSeverity": "WARNING"
    }
  ],
  "alertTemplate": "THRESHOLD",
  "notificationId": "12"
}

Response

{
  "alertDefId": "string"
}

Delete an Alert Definition

Required Permissions: You must have the Delete Alert Definition permission to perform this operation.
Description: Delete an alert definition. The system cancels all active alerts that use this definition.
API: /api/alert-definitions/{alert_def_id}

Method

DELETE

Required Parameters


Name	Description
`alert_def_id` `string`	Alert definition ID created by the service.

Response

{}

Get a List of Alert Definitions

Required Permissions: You must have the View Alert Definition permission to perform this operation.
Description: Get a list of alert definitions that satisfies the optional search parameters.
API: /api/alert-definitions

Method

GET

Optional Parameters


Name	Description
name `string`	Name of the alert definition.
deviceTemplateId `string`	Device template ID.
deviceId `string`	Device ID.
symptoms `array`	The alert definition symptom. lambda: Alert condition. alertSeverity: CRITICAL WARNING INFO NORMAL
alertTemplate `string`	Alert template: `THRESHOLD` `OFFLINE`
page.number `int32`	Page number.
page.size `int32`	Page size.

Response

{
  "alertDefInfos": [
    {
      "lastUpdatedTime": "string",
      "alertDef": {
        "name": "string",
        "triggerCount": 0,
        "symptoms": [
          {
            "lambda": "string",
            "alertSeverity": "UNKNOWN_SEVERITY"
          }
        ],
        "metrics": [
          "string"
        ],
        "notificationId": "string",
        "recommendation": "string",
        "alertTemplate": "UNKNOWN_TEMPLATE",
        "deviceTemplateId": "string",
        "description": "string"
      },
      "lastUpdatedBy": "string",
      "updateVersion": 0,
      "createdBy": "string",
      "createdTime": "string",
      "alertDefId": "string"
    }
  ],
  "page": {
    "totalPages": "string",
    "totalElements": "string",
    "page": 0,
    "pageSize": 0
  }
}

Get Alert Details

Required Permissions: You must have the View Alert permission to perform this operation.
Description: Get details of an alert.
API: /api/alerts/{alert_id}

Method

GET

Required Parameters


Name	Description
`alert_id` `string`	Alert ID created by the service.

Response

{
  "lastUpdatedTime": "string",
  "alertId": "string",
  "triggers": [
    {
      "valueInt64": "0",
      "timeMs": "string",
      "metric": "string",
      "valueDouble": 0.0
    }
  ],
  "alertSeverity": "UNKNOWN_SEVERITY",
  "state": "UNKNOWN_ALERTSTATE",
  "lastUpdatedBy": "string",
  "updateVersion": 0,
  "createdBy": "string",
  "createdTime": "string",
  "userAcknowledged": "string",
  "alertDefId": "string",
  "alertDefName": "string"
}

Changing the Alert State

Required Permissions: You must have the Edit Alert permission to perform this operation.
Description: Update the alert state from Active to Acknowledged.
Note: You cannot revert an alert from Acknowledged state to Active state.
API: /api/alerts/{alert_id}

Method

PUT

Required Parameters


Name	Description
`alert_id` `string`	Alert ID created by the service.
`state` `string`	The alert state: `ACTIVE` `ACKNOWLEDGED`

Input Example

{
  "state": "ACTIVE"
}

Response

{
  "alertId": "string"
}

Get a List of Alerts

Required Permissions: You must have the View Alert permission to perform this operation.
Description: Get a list of alerts that satisfy certain search parameters.
API: /api/alerts

Method

GET

Optional Parameters


Name	Description
`alert_def_id` `string`	Alert definition ID.
`alert_def_name` `string`	Alert definition name.
last_updated_time_start_ms `int64`	Last updated start time (UNIX Epoc time with millisecond precision).
last_updated_time_end_ms `int64`	Last updated end time.
symptoms `array`	The alert definition symptom. lambda: Alert condition. alertSeverity: CRITICAL WARNING INFO NORMAL
`state` `string`	The alert state: `ACTIVE` `ACKNOWLEDGED`
page.number `int32`	Page number.
page.size `int32`	Page size.

Response

{
  "page": {
    "totalPages": "string",
    "totalElements": "string",
    "page": 0,
    "pageSize": 0
  },
  "alertInfos": [
    {
      "lastUpdatedTime": "string",
      "alertId": "string",
      "triggers": [
        {
          "valueInt64": "string",
          "timeMs": "string",
          "metric": "string",
          "valueBoolean": true,
          "valueString": "string",
          "valueDouble": 0
        }
      ],
      "alertSeverity": "UNKNOWN_SEVERITY",
      "state": "UNKNOWN_ALERTSTATE",
      "lastUpdatedBy": "string",
      "updateVersion": 0,
      "createdBy": "string",
      "createdTime": "string",
      "userAcknowledged": "string",
      "alertDefId": "string",
      "alertDefName": "string"
    }
  ]

Get Alert Trigger History

Required Permissions: You must have the View Alert permission to perform this operation.
Description: Get a list of alert trigger/cancel/acknowledge history of a device for an alert definition.
API: /api/alerts/{alert_id}/trigger-history

Method

GET

Required Parameters


Name	Description
`alert_id` `string`	Alert ID.

Response


message AlertTriggerHistory {
   // the detailed alert triggered/cancelled/acknowledged record
   repeated Trigger triggers = 1;
}
// trigger details
message Trigger {
   // metric name
   string metric = 1;
   // timestamp in milliseconds
   int64 time_ms = 2;
   // metric value (four data types) when the alert is triggered: string, int64, double or boolean
   oneof value {
      string value_string = 3;
      int64 value_int64 = 4;
      double value_double = 5;
      bool value_boolean = 6;
   }
  AlertState state = 7;   
   // the username who creates the trigger record
   string userName = 8;
  // severity level when the alert is triggered, added for multi-level alert support
   Severity severity = 9;  //    
};