anomalies

Provides anomalies in timeseries entity metric data. This information is used in the Device Dashboard to display the network anomalies.

This API queries and retrieves information from THRESHOLD.STATE table.

URL

http://[host]:[port]/service/dataset/metric/anomalies
http://<myserver.ibm.com>:9443/service/dataset/metric/anomalies

Method

The supported request type.

HTTP GET

URL parameters

Name Required Default value Description
entities No N/A Comma-separated list of ncim entity IDs.
entityNames No N/A Comma-separated list of entity names
metrics Yes N/A Comma-separated names of the metrics and their aggregation expression.
parents No N/A Comma-separated list of main node ID.
parentNames No N/A Comma-separated list of ncim device names
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 of the period for which flow data that must be returned.
end No N/A The end of the period for which flow data that must be returned.
time No N/A The name of time short cut used. For example:
  • last-hour
  • last-day
  • last-week
  • last-month
  • last-year
excludeParent No false A flag to exclude the parent ID from response.
childTypes No * Comma-separated list of entity types of node that must be filtered in the result. Supported childTypes filter values are interface, device, probe, and * (All).
entityResourceTypes No N/A Entity Type of node that must be filtered in result. For example:
  • interface
  • device
  • probe
  • physicalcard
  • artTarget
  • qosQueue
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/anomalies?entities=ncim-59,ncim-81,ncim-86&time=lastweek&
metrics=ifInDiscards

/service/dataset/metric/anomalies?entities=ncim-59&start=1466008260000&end=1466011860000&
metrics=ifInDiscards

/service/dataset/metric/anomalies?entities=ncim-59&start=1466008260000&end=1466011860000&
metrics=ifInDiscards,ifOutDiscards

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

/service/dataset/metric/anomalies?parents=1,2&entities=ncim-59&start=1466008260000&
end=1466011860000&metrics=ifInDiscards,ifOutDiscards

/service/dataset/metric/anomalies?parentNames=10.55.239.42,10.55.239.4&entityNames=T1
1/1&start=1466008260000&end=1466011860000&metrics=ifInDiscards

/service/dataset/metric/anomalies?start=1466008260000&end=1466011860000&
metrics=ifInDiscards&searchByProperties="PHYSICALADDRESS"='30' AND "LOCATION"='KL'

/service/dataset/metric/anomalies?parents=3&metrics=snmpInBandwidth&time=lastday&
childTypes=interface,device
Note:
  • At least one or more of the following parameters must be provided:
    • entities
    • parents
    • entityNames
    • parentNames
    • searchByProperties
    • entityResourceTypes
  • time or a combination of start AND or OR end must be provided.
  • time parameter is superseded by combination of start AND or OR end if both combinations are present and it must support last-hour and last_day only.
  • Supported operators for properties filter are as follows:
    • ,
    • =
    • <>
    • IN
    • LIKE
    • AND
    • OR
    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.

Error Response


{"errorMesg":"Either entities, parents, entityNames, parentNames or searchByProperties should be
provided"}
{
"errorMesg": "Invalid start, end and granularity combination. Granularity : 1 minute StartMs :
1568373360000 endMs : 1468375200000"
}

Response

The results are returned as JSON data that contains an array of the following fields:
Name Data type Description
entity number The entity that is associated with the time and metric value.
parent number The parent entity ID that is associated with the entity. The value is defaulted to -1 if enrichment fails.
entityName string The entity name. The value is defaulted to unknown if enrichment fails.
parentName string The entity’s parent name. The value is defaulted to unknown if enrichment fails.
metric string The metric name for the associated time and metric value.
type string The type of anomaly that is detected.
severity string The severity of the anomaly.
start number The time that is associated with the start of the anomaly.
end number The time that is associated with the end of the anomaly.

This field is available when the anomaly is ended, but not when anomaly is still outstanding.
value number The last violation metric value for the associated time
details string JSON blob that contains the details of the anomaly.

JSON code:


[
   {
      "parent":6,
      "entityName":"",
      "parentName":"10.55.239.2",
      "metric":"ifInDiscards",
      "entity":59,
      "details":"{'effectiveTimeStamp':1472098732320,'limitType':0,'upperLimit':10,'lowerLimit':5,'numEvents':2}",
      "severity":"critical",
      "type":"StaticThreshold",
      "start":1472099473383,
      "value":20
   },
   {
      "parent":6,
      "entityName":"0",
      "parentName":"10.55.239.2",
      "metric":"ifInDiscards",
      "entity":81,
      "details":"{'effectiveTimeStamp':1472098732320,'limitType':0,'upperLimit':10,'lowerLimit':5,'numEvents':2}",
      "severity":"critical",
      "type":"StaticThreshold",
      "start":1472099473384,
      "value":10
   }
]