Creating an alert definition

Ops Center Analyzer Detail View REST API Reference Guide

Version
11.0.x
Audience
anonymous
Part Number
MK-99ANA004-10

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.