timeseries

Provides timeseries entity metric data.

This API queries and retrieves information from CarbonData database that is associated with Timeseries and DiamondDB Services.

URL

https://<dashboard_route>/insight/service/dataset/metric/timeseries
https://<dashboard_hostname>:<dashboard_port>/insight/service/dataset/metric/timeseries
https://<myserver.ibm.com>:31443/insight/service/dataset/metric/timeseries?entities=ncim-348
&metrics=ifInDiscards&time=last-hour

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 list of metrics and their aggregation.

For example, snmpInBandwidth, health, max(health), min(health)
parents No N/A Comma-separated list of main node ID.
parentNames No N/A Comma-separated list of device names
searchByProperties No N/A Properties filter in this format: 
<propertyName><ops>=='<propertyValue>'
Note: Property name and value are case-sensitive.
For example:
&searchByProperties=resource.deviceName=='BR-03-AKHMW'
searchByMetricValue No N/A It is used to filter the metric data from the timeseries database based on the condition provided.
&searchByMetricValue=ts['tavg_day_LTE.Cell.Availability']==100 
and (ts['tsum_day_LTE.VOLTE.TRF.VOL.ERL']<0.0001 or ts['tsum_day_LTE.VOLTE.TRF.VOL.MB']<0.0001)
You can include multiple metrics with and or conditions. For example, 
ts[‘metricName1’] and ts[‘metricName2’] or ts[‘metricName3’]
start No N/A The start time for which flow data must be returned.
end No N/A The end time for which flow data must be returned.
time No N/A The name of the time short cut. For example:
  • last-hour
  • last-day
  • last-week
  • last-month
  • last-year
requestgranularity No N/A The granularity for which the data must be aggregated. The default granularity can be as follows:
  • 1-hour
  • 1-minute
  • 15-minute
  • 30-minute
  • 6-hour
  • 1-day
  • 7-day
sort No N/A

An expression that defines the sort order of the records. Prefix + or - to indicate sort direction. For example, +metric -upper_limit indicates that the sorting must be by metric in ascending order, and then by upper_limit in descending order.
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)
excludeParent No N/A Flag to exclude the parent ID from the result. By default, this parameter is set to False.
flatten No false Output of the result without nested the objects.
entityResourceTypes No N/A Entity Type of node that must be filtered in result. For example,
  • interface
  • device
  • probe
  • physicalcard
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.
properties No N/A Comma-separated list of properties that are returned for the entities that are specified.

Querying Flow data from persistent cache

Run the following URI to test that the Flow data is available in the persistent cache:
/service/cache/byScope?scope=flow
If it returns data, then you can proceed to run the rest of the URIs.
If you have enabled the persistent Flow cache data, you can use the following URIs to query the data:
/service/cache/byTypeScope?type=device&scope=flow
/service/cache/byTypeScope?type=interface&scope=flow
/service/cache/byCondition?condition=resource.scope=='flow' AND resource.type=='interface'&projection=scope,npiIfIdOut,npiIfIdIn,isNetflow

See Configuring persistent cache for Flow data to enable persistent cache for Flow data.

Special behavior

When you specify a granularity period with a start and end time in your query, the API engine always returns the data from the next available round-up time. For example, if you give a query as follows:

https://<myserver.ibm.com>:31443/insight/service/dataset/metric/timeseries?entities=43064,188&
metrics=ifInDiscards&start=1497052800000&end=1497117600000&requestgranularity=18-hours
Start time is calculated based on the aggregation round-up time. For 18-hrs granularity, the round-up aggregation times for the start time of 9 June 2017 12:00:00 AM are:
  • 9 June 2017 12:00:00 PM
  • 10 June 2017 6:00:00 AM
  • 11 June 2017 12:00:00 AM
The query returns the aggregated data from next available round-up time that is 10 June 2017 6:00:00 AM and not from 10 June 2017 12:00:00 AM.
Note: This behavior is noticed with timeseries API only.

Error response

For example, 

{"errorMesg":"Either entities, parents, entityNames, parentNames or serachByProperties 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.
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
metricId long The metric ID for the associated time and metric value.
timestamp number The time that is associated with the metric value.
value number The metric value for the associated time
<property> string Values of the requested properties that are specified in the request URL.
JSON code without flatten parameter set:
[
   {
      "parent":6,
      "timestamp":1471503616000,
      "entityName":"0",
      "parentName":"10.55.239.2",
      "metric":"ifOutErrors",
      "metricId":2118,
      "entity":86,
      "value":5398
   },
   {
      "parent":-1,
      "timestamp":1471501946000,
      "entityName":"unknown",
      "parentName":"unknown",
      "metric":"ifOutErrors",
      "metricId":2118,
      "entity":134,
      "value":40
   },
   {
      "parent":8,
      "timestamp":1471501956000,
      "entityName":"T1 1/2",
      "parentName":"10.55.239.4",
      "metric":"ifOutErrors",
      "metricId":2118,
      "entity":114,
      "value":0
   }
]
JSON code with flatten parameter set:
[
   {
      "parent":587,
      "timestamp":1506250800000,
      "entityName":"0",
      "parentName":"10.55.239.31",
      "AVG(ifInDiscards)":6,
      "entity":607,
      "SUM(ifInDiscards)":6
   },
   {
      "parent":587,
      "timestamp":1506258000000,
      "entityName":"0",
      "parentName":"10.55.239.31",
      "AVG(ifInDiscards)":6,
      "entity":607,
      "SUM(ifInDiscards)":6
   }
]
JSON code with properties 
[{  
      "targetAddress":"4.20.45.112",
      "parent":3202,
      "timestamp":1561423380000,
      "entityName":"10.55.239.235_udpEcho:<201>",
      "parentName":"10.55.239.235",
      "metric":"Probe.Echo.Probe.Loss.Percent",
      "sourceAddress":"20.10.11.119",
      "entity":3878,
      "vendor":"Cisco",
      "value":50
   },
   {  
      "targetAddress":"4.10.110.47",
      "parent":3202,
      "timestamp":1561387380000,
      "entityName":"10.55.239.235_echo:<106>",
      "parentName":"10.55.239.235",
      "metric":"Probe.Echo.Probe.Loss.Percent",
      "sourceAddress":"10.25.238.209",
      "entity":3852,
      "vendor":"Cisco",
      "value":100
   }
]