`deviation`

Computes deviation for the current data that is compared against average value on the same day of week over N number of weeks.

The deviation REST API is used to compare against an aggregated metric data from a specific start and end time stamp and lookBackWeek to produce a TopN resource list.

Consider the following scenario:

You provide a start and end time from 1 AM - 2 AM Monday, 28 August 2017.
You select the lookBackWeek of 1.
You select the average value for a specific metric.

In this scenario, the deviation REST API queries all the related device types; interface, physical card, and probe, and the average value of the metric for the period of 7 days earlier, that is, Monday , 21 August 2017. The API also compares the results and retrieves the top ranking list.

This API queries and retrieves information from Cassandra.

URL

https://[host]:[port]/service/dataset/metric/deviation

https://<myserver.ibm.com>:9443/service/dataset/metric/deviation

Method

The supported request type.

https GET

URL parameters

Name	Required	Default value	Description
`entities`	No	N/A	Comma-separated list of entity IDs
`entityNames`	No	N/A	Comma-separated list of entity names
`metrics`	Yes	N/A	Comma-separated names of the metrics. Also supports metric IDs.
`parents`	No	N/A	Comma-separated list of main node IDs. Note: Must be associated with `childTypes` for ART, QoS related metrics.
`parentNames`	No	N/A	Comma-separated list of ncim device names. Note: Must be associated with `childTypes` for ART and QoS related metrics.
`searchByProperties`	No	N/A	Properties filter in this format: `"<propertyName>"<ops>' <propertyValue>'` Note: Property name and value are case-sensitive. For example: `"IFTYPESTRING"='ethernet-csmacd'`
`start`	No	N/A	The start time for which flow data must be returned. Note: The start and end time periods for deviation must be minimum 30 minutes and not longer than 1 day.
`end`	No	N/A	The end time for which flow data must be returned. Note: The start and end time periods for deviation must be minimum 30 minutes and not longer than 1 day.
`time`	No	N/A	Specific time values: `last-hour` `last-day` Note: You need either `start`/`end` or `time` parameters in the URL.
`lookBackWeek`	Yes	N/A	The number of weeks to look back. `lookBackWeek` for deviation is always <=4.
`scope`	No Yes for ART/QoS metrics	`ibm-itnm` `flow` `cacti`	Scope of the resource. Scope is required for ART, QoS related metrics. Note: For all the performance data that is collected and analyzed from your Cacti deployment scenario, scope is set to `cacti`.
`childTypes`	No	*	Comma-separated list of entity types of nodes that must be filtered in the result. By default, it is device and interface. Supported `childTypes` filter values are as follows: interface device probe physicalcard artTarget qosQueue * (All)
`suppressSummary`	No	false	Output the result without the summary portion.
`count`	No	-1	Number of entities summary that must be returned. Combined with `sort` provides topN or bottomN functions. The default value -1 returns all available records.
`page`	No	1	The index of the page with data to return. It must be supplied with count parameter to indicate the page size.
`properties`	No	N/A	Comma-separated list of properties to output.
`flowEnabled`	No	false	If set to `true`, the result must contain the flow enabled entities.
`entityResourceTypes`	No	N/A	Entity Type of node that must be filtered in result. For example: interface device probe physicalcard artTarget qosQueue
`excludeParent`	No	false	A flag to exclude the parent IDs from response.
`parentChildRelation`	No	union	Set operation between result from parent ID search and entity ID search. For example, intersection, union.
`site`	No	ALL	Configured site name.
`bizHour`	No	ALL	Configured business hours for a site. Expected values are OFF, ON and ALL.
`site`	No	ALL	Configured site name.
`bizHour`	No	ALL	Configured business hours for a site. Expected values are OFF, ON and ALL.

Sample URLs

/service/dataset/metric/deviation?entities=ncim-217&metrics=snmpInBandwidth&
start=1466008260000&end=1466011860000

/service/dataset/metric/deviation?entities=ncim-217,ncim-218&metrics=snmpInBandwidth&time=last-hour

/service/dataset/metric/deviation?entities=ncim-217&metrics=snmpInBandwidth&time=
last-hour/service/dataset/metric/deviation?entities=ncim-217&metrics=snmpInBandwidth&
start=1466008260000&end=1466011860000

/service/dataset/metric/deviation?entityNames=T1 1/1,T1 1/2&metrics=snmpInBandwidth&
start=1466008260000&end=1466011860000

/service/dataset/metric/deviation?entities=ncim-217,ncim-218&metrics=snmpInBandwidth&time=last-hour

/service/dataset/metric/deviation?metrics=snmpInBandwidth&time=lasthour&
searchByProperties="PHYSICALADDRESS"='30' AND "LOCATION"='KL'

/service/dataset/metric/deviation?parents=3&metrics=snmpInBandwidth&time=lastday&childTypes=
interface,device

/service/dataset/metric/deviation?parents=760&metrics=PingResult&time=last-day&lookBackWeek=4

Note:

At least one or more of the following parameters must be provided:
- entities
- parents
- entityNames
- parentNames
- searchByProperties
- entityResourceTypes

Supported operators for properties filter are as follows:

For example:


searchByProperties="sysName"='"10.55.239.40"' AND "If"='897'
searchByProperties="sysName"='"10.55.239.40"' AND "If" IN ('897','898')
searchByProperties="sysName" like '"10.55.239.%25"' AND "If"='897'

Note: % is reserved keyword. It must be encoded with %25.

time or a combination of start AND or OR end must be provided.
start and end range must be minimum of 30 minutes and maximum 1 day.
time parameter is superseded by combination of start AND or OR end. It must support last-hour or last_day only.
lookBackWeek parameter must contain the value greater than 0.
count parameter must be used to get top N resources.
Data must always be sorted by deviation value.

Error response

For example:


{"errorMesg":"Either entities, parents, entityNames, parentNames 
or searchByProperties should be provided"}
{"errorMesg":"lookBackWeek is a mandatory parameter and should 
contain value greater than zero"}
{"errorMesg":"Time range between start and end should be minimum 30-mins
 to maximum 1 day"}
{"errorMesg":"Metric Deviation Servlet support only 1 metric"}

Response

The results are returned as JSON data that contains an array of the following fields:

Name	Data type	Description
`total`	number	Total number of records available
`page`	number	Current page number
`count`	number	Number of records in the page
`items`	list	The list of entity metric summary
`entity`	number	The entity ID that is associated with the time and metric value.
`parent`	number	The parent Entity ID that is associated with the entity.
`entityName`	string	The entity name. This value is defaulted to `unknown`, if enrichment fails.
`parentName`	string	Parent entity name. This value is defaulted to `unknown`, if enrichment fails.
`startTimestamp`	number	The start time that is associated with the metric value.
`endTimestamp`	number	The end time that is associated with the metric value.
`metric`	string	The metric name for the associated time and metric value. If `metricId` is used for search, this attribute returns the metric name.
`rank`	number	The rank (1-N) of the record relative to all other entities based on sort. Default is 0 if sort parameter is not provided.
`devValues`	number	The metric deviation value for the associated time, entity, and metric expression.
`properties`	map	Map of properties that are given in input parameters and their values.
`inIfId`	number	In interface IDs for given entities if enriched.
`outIfId`	number	Out interface IDs for given entities if enriched.

JSON code without suppressSummary flag set:

{
   "total":27,
   "page":1,
   "count":27,
   "items":[
      {
         "entity":59,
         "parent":59,
         "entityName":"entityName",
         "parentName":"parentName",
         "startTimestamp":1469515500000,
         "endTimestamp":1469615500000,
         "rank":1,
         "devValues":100,
         "metricId":"MetricName",
         "metric":10,
         "inIfId":11,
         "outIfId":12
      },
      {
         "entity":58,
         "parent":58,
         "entityName":"entityName",
         "parentName":"parentName",
         "startTimestamp":1469515500000,
         "endTimestamp":1469615500000,
         "rank":2,
         "devValues":99,
         "metricId":"MetricName",
         "metric":10,
         "inIfId":11,
         "outIfId":12
      }
   ]
}

JSON code with suppressSummary flag set:

[
   {
      "entity":59,
      "parent":59,
      "entityName":"entityName",
      "parentName":"parentName",
      "startTimestamp":1469515500000,
      "endTimestamp":1469615500000,
      "rank":1,
      "devValues":100,
      "metricId":"MetricName",
      "metric":10,
      "inIfId":11,
      "outIfId":12
   },
   {
      "entity":60,
      "parent":60,
      "entityName":"entityName",
      "parentName":"parentName",
      "startTimestamp":1469515500000,
      "endTimestamp":1469615500000,
      "rank":2,
      "devValues":100,
      "metricId":"MetricName",
      "metric":10,
      "inIfId":11,
      "outIfId":12
   }
]