Creating an alert definition

Analyzer detail view classifies metrics into two types: configuration metrics and performance metrics. Configuration metrics do not change frequently such as resources Status, Capacity, and so on. Performance metrics change frequently such as IOPS, response time, and so on. You can create an alert definition for critical parameters of the configuration and performance metrics.

Refer to, Hitachi Ops Center Analyzer Detail View Metrics Reference Guide for a list of the configuration metrics for which you can create an alert definition.

You can create multiple alert definitions through a single request.

Note: After creating a new alert definition, it is attached to the associated resource when the data is imported. However, the actual evaluation of the alert definition does not begin until the next data is imported.

If the owner of an alert definition is deleted, then the alert definition ownership is transferred to the built-in administrator user. (The user name for the built-in administrator account is admin.)

Request line

POST baseURL/alertapi.do?action=createAlertDef

Request payload is an array of alert definition JSON objects.

Request body

[
  {
    "name":"",
    "metric":"",
    "resource_mql":"",
    "resource_type":"",
    "resources":[
      {
        "signature":"",
        "threshold":[
          
        ]
      },
      {
        "signature":""
      }
    ],
    "severity":"",
    "condition":"",
    "default_threshold":[
      
    ],
    "criteria":{
      "type":"",
      "m":,
      "n":,
      "n_unit":""
    },
    "monitoring_window":{
      "from":"",
      "to":""
    },
    "subscription":{
      "email":{
        "id":[
          "",
          ""
        ],
        "damping":""
      },
      "syslog":{
        "server":[
          "",
          ""
        ]
      },
      "snmp":{
        "manager”: [
          "hostname",
          "IP"
         ]
      }
    }
  }
]

Request example

POST /alertapi.do?action=createAlertDef

[
  {
    "name":"Production VMs High CPU Usage",
    "metric":"cpuUsage",
    "resource_mql":"ldev[=type rx virtual]",
    "resource_type":"ldev",
    "resources":[
      {
        "signature":"XXXXX",
        "threshold":[
          90
        ]
      },
      {
        "signature":"XXXXX"
      }
    ],
    "severity":"critical",
    "condition":"gt",
    "default_threshold":[
      80
    ],
    "criteria":{
      "type":"m/n",
      "m":3,
      "n":5,
      "n_unit":"minutes"
    },
    "monitoring_window":{
      "from":"08:00",
      "to":"17:59"
    },
    "subscription":{
      "email":{
        "id":[
          "xxx",
          "yyy"
        ],
        "damping":"no_damping"
      },
      "syslog":{
        "server":[
          "hostname:portNo:TCP",
          "IP:portNo:UDP"
        ]
      },
      "snmp":{
        "manager”: [
          "hostname",
          "IP"
         ]
        }
      }
    }
  }
]

Request example of the configuration metrics with string value (`having` condition)

POST /alertapi.do?action=createAlertDef

[
  {
    "name": "test_string_10",
    "severity": "critical",
    "resource_type": "raidPool",
    "metric": "dataSaving",
    "condition": "having",
    "default_threshold": [
      "Compression"
    ],
    "resources": [
      {
        "signature": "raidPool#421358-14"
      }
    ]
  }
]
Response JSON:
{
  "created": [
    {
      "name": "test_string_10",
      "id": 57
    }
  ]
}

Request parameters

Note: In the following table, if a parameter is specified in the a:b format, then it means field b of JSON object a.

Parameter	Type	Description
name	String	Name of the alert. Alphanumeric, underscore (_), space characters are allowed Name must be must be unique across all alert definitions with maximum length of 100 characters.
metric	String	Attribute ID on which the alert is created. Valid attribute ID, must be present in AttributeDef and associated with resources for which the alert is to be created. Dynamic attribute is not supported.
condition	String	Alert condition: `gt` for greater than, `lt` for less than, and `bt` for between. Alert condition for string metric: If the metric type is string, then you must provide the condition as `having`.
default_threshold	Float[ ]	Threshold for which condition is to be evaluated. This value can be overridden by the value in the resource object. For the `bt` condition, two values must be specified in the array. The first value in the array is lower bound and the second one is upper bound. Both these values are inclusive in violation computation. Float: Maximum value = Java Float.Max value i.e., +3.4028235 E 38. Minimum value = Java Float.Min value i.e., - 3.4028235 E 38.
default_threshold (for `having` condition)	String	The threshold field for having condition supports alphanumeric, hyphen (-), underscore (_) , comma (,), colon (:), at (@), slash (/), dot (.), and space.
criteria	Object	Criteria to determine the alert condition violation. Note: The `criteria` parameter is not required while setting the alert definition for configuration metric.
criteria:type	String	Type of criteria. Default value is `m/n`. Only supported option is `m/n` m = number of samples n = duration
criteria:m	Integer	Number of samples (threshold violations). Value of M in `m/n` criteria. 0 < m <= samples in N time window.
criteria:n	Integer	Length of a time-window. Value of N in `m/n` criteria.
criteria:n_unit	String	(Optional) Unit of time-window N. 0 < n <= 60 minutes
resource_mql	String	(Optional) MQL for resource selection. It is useful for setting alerts on a tree node for all nodes of a certain type. You do not have to maintain a list of resources because the Analyzer detail view transparently manages the additions and deletions. The resource MQL is run every time a configuration import occurs, and alert definitions are attached to the newly added resources matching MQL only on configuration import.
resource_type	String	(Optional) A valid resource type value . This is useful if you want to apply an alert on all resources.
resources	Object[ ]	(Optional) Array of resource objects on which alert is to be defined. All resources should be of the following type: `resource_type`.
resources:signature	String	Signature of a resource.
resources:threshold	Float[ ]	(Optional) Resource specific threshold of the alert. This overrides the `default_threshold`. Float: Max value = Java Float.Max value i.e., +3.4028235 E 38. Min value = Java Float.Min value i.e., -3.4028235 E 38.
resources:threshold (for `having` condition)	String	(Optional) Resource specific threshold of the alert. This overrides the `default_threshold`. The threshold field for having condition supports alphanumeric, hyphen (-), underscore (_) , comma (,), colon (:), at (@), slash (/), dot (.), and space.
severity	String	(Optional) Severity of the alert: warning or critical Default: critical
monitoring_window	Object	(Optional) Restrict alert evaluation to certain hours of the day. This can be specified in half hour increments. Both `from` and `to` values are inclusive. Alert monitoring window is based on UTC timezone. Be sure to select the appropriate time window. If applicable, also consider the Daylight Saving Time. For example, if the Analyzer detail view UI timezone is set to Pacific Time (GMT-08:00) and you want to add alert for time window 9:00 AM to 7:00 PM, then set alert `monitoring_window:from` and `monitoring_window:to` as 05:00 PM to 03:00 AM, respectively. Note: The `monitoring_window` parameter is not required while setting the alert definition for configuration metric.
monitoring_window:from	String	(Optional) Start time of the monitoring window. The time specification must be in HH:MM format. Valid values for HH range from 00 to 23, and valid values for MM are 00 and 30.
monitoring_window:to	String	(Optional) End time of the monitoring window. The time specification must be in HH:MM format. Valid values for HH range from 00 to 23, and valid values for MM are 29 and 59.
subscription	Object[ ]	(Optional) Details of the alert subscription, that describes how you want to subscribe the alert notification. For example, email, snmp, or syslog.
subscription:email:id	String[ ]	(Optional) Array of email IDs.
subscription:email:damping	String	(Optional) Specify if you want to send individual violation or in a group. (no_damping, state_change, hourly_gist, daily_gist)
subscription:snmp:manager	String	IP addresses or host names of SNMP Managers. <host>: Either host name or IP address of the SNMP Manager.
syslog:server	String[ ]	(Optional) Array of IP address or host name of the Syslog server. Array of strings, each representing a server in “<host>:<port number>:<protocol>” format. `<host>`: Either hostname or IP address of the syslog server. `<port number>`: Valid port number. `<protocol>`: TCP or UDP.

Response body

On successful alert creation, ID is generated and is returned in response. This ID acts as a primary key for further API calls.

{
  "created":[
    {
      "id":1,
      "name":"Sample AlertDef One"
    }
  ]
}

Response example with an error

{
  "created":[
    {
      "id":1,
      "name":"Sample AlertDef One"
    }
  ],
  "failed":[
    {
      "reason":"Attribute definition with id:[unknownAttribute] does not exist.",
      "name":"Sample AlertDef Two",
      "code":"A1020008"
    }
  ]
}

Status codes

Status code	Message	Description
277	PARTIAL OK	Request completed successfully with some failures. Check the response body for details.
500	SERVER ERROR	API operation request failed. Check the response body for details.

Response codes

The following table lists the alert API response codes that might be generated through the standard API. If an error response is not listed, examine the HTTP status codes to determine the best method for addressing the issue.

Response code	Message	Condition
A1020003	Mandatory parameter {name} is not specified.	Alert name is not specified.
A1020003	Mandatory parameter {metric} is not specified .	Metric is not specified.
A1020008	Attribute definition with id:[unknownAttribute] does not exist.	Specified metric does not exist.
A1020004	At least one of {resource_type, resource_mql} parameters must be specified.	Parameters `resource_type` and `resource_mql` are not specified.
A1020009	Resource definition with type:[unknownResourceType] does not exist.	Specified `resource_type` does not exist.
A102000A	Resource definition with type [vm] does not contain [diskMaxTotalLatency] metric.	Specified resource type does not contain the given metric.
A1020003	Mandatory parameter {condition} is not specified.	Condition is not specified.
A1020003	Mandatory parameter {criteria} not specified.	Criteria is not specified.
A1020006	Invalid {criteria} is specified.	Criteria:m, Criteria:n are not specified.
A1010003	Mandatory parameter {default_threshold} is not specified.	Parameter `default_threshold` is not specified
A1020006	Invalid {condition} is specified.	Invalid condition is specified.
A1020006	Invalid {resource_mql} is specified.	Invalid `resource_mql` is specified.
A1010007	Invalid {threshold} specified for resource [vm#vm1].	Invalid threshold is specified for any resource.
A104000C	Failed to add resource [vm#vm10] as resource does not exist.	Resource does not exist for the specified resource signature.
A1010006	Invalid {monitoring_window} is specified.	Invalid value is specified for monitoring window.
A1010005	Invalid {emailIds} specified [yyy, abc@@gmail.com].	Invalid value is specified for email IDs.
A1010006	Invalid {damping} specified.	Invalid value is specified for email damping.
A1010005	Invalid {sysLogServer} specified [hostName].	Invalid Syslog server details.
A1020018	Resource [ldev#sig2] is not present.	Resource on which you want to apply the alert definition and alert definition does not exist.
A1020019	Found unknown properties [resource, unknownKey].	Unknown key is specified.
A1020021	Invalid attribute specified [attribute_id].	Specified attribute is of the scalar type and cannot generate an alert on the specified attribute ID.
A1020022	Invalid condition specified [condition].	Invalid condition is specified.