`summary`

Provides a summary of the metric data.

This API queries and retrieves information from ENTITY_METRIC.RAW, ENTITY_METRIC.AGG_001DAY/AGG_006HR/ AGG_030MIN tables.

URL

http://[host]:[port]/service/dataset/metric/summary

http://<myserver.ibm.com>:9443/service/dataset/metric/summary

Method

The supported request type.

HTTP 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 name of the metric expression that includes the type of aggregation. For example, `snmpInBandwidth`, `health`, `max(health)`, `min(health)`
`parents`	No	N/A	Comma-separated list of main node IDs.
`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 time for which flow data must be returned.
`end`	No	N/A	The end time for which flow data must be returned. Note: `start` and `end` parameters must be used together.
`time`	No	N/A	Specific time values: `last-hour` `last-day` `last-week` `last-month` `last-year` Note: You need either `start`/`end` or `time` parameters in the URL.
`sort`	No	N/A	Metric expression that defines the sort order of the records. Only one metric is allowed with the `sort` expression. Prefix `+` or `-` to indicate sort direction.
`count`	No	-1	Number of entities summary that must be returned. Combined with `sort` provides topN or bottomN functions.
`page`	No	1	The index of the page for data display. This parameter is supplied with `count` parameter to indicate page size. By default, it is 1.
`excludeParent`	No	false	Flag to exclude the parent ID from the result. By default, this parameter is set to `False`.
`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)
`flatten`	No	false	Output of the result without nested the objects.
`suppressSummary`	No	N/A	Output of the result without the summary portion.
`entityResourceTypes`	No	N/A	Entity Type of node that must be filtered in result. For example: interface device probe physicalcard artTarget qosQueue
`parentChildRelation`	No	union	Set operation between the result from parent identifier search and entity identifier search.
`flowEnabled`	No	false	If set to `true`, the result must contain the flow enabled entities.
`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/summary?entities=ncim-217&metrics=snmpInBandwidth&
start=1466008260000&end=1466011860000

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

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

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

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

/service/dataset/metric/summary?parents=3&metrics=max(health),min(health),avg(health),sum(health),
count(health)&time=last-month

/service/dataset/metric/summary?parents=3,4&entities=ncim-217,ncim-218&metrics=max(health),min(health),
avg(health),sum(health),count(health)&time=last-month

/service/dataset/metric/summary?parents=3,4&entities=ncim-217,ncim-218&metrics=max(health),min(health),
avg(health),sum(health),count(health)&time=last-month&sort=-sum(health)

/service/dataset/metric/summary?parents=3,4&entities=ncim-217,ncim-218&metrics=max(health),min(health),
avg(health),sum(health),count(health)&time=last-month&sort=-sum(health)&count=10

/service/dataset/metric/summary?parentNames=10.55.239.42,10.55.239.4&entityNames=T11/1&metrics=max(health),
min(health),avg(health),sum(health),count(health)&time=last-month&sort=-sum(health)&count=10

/service/dataset/metric/summary?entities=ncim-217,ncim-218&metrics=snmpInBandwidth&time=lasthour&page=2&count=10

/service/dataset/metric/summary?metrics=snmpInBandwidth&time=last-hour&page=2&count=10&
searchByProperties="PHYSICALADDRESS"='30' AND "LOCATION"='KL'

/service/dataset/metric/summary?parents=3&metrics=snmpInBandwidth&time=lastday&childTypes=interface,
device/service/dataset/metric/summary?metrics=ifInDiscards&time=last-hour&entityResourceType=interface

/service/dataset/metric/summary?entities=ncim-138&metrics=max(ifInDiscards),sum(health),count(health)&
time=last-hour&flatten=true

/service/dataset/metric/summary?entities=ncim-135&metrics=count(health)&time=lasthour&suppressSummary=true

/service/dataset/metric/summary?entities=ncim-138&metrics=max(ifInDiscards),sum(snmpInBandwidth),
count(ifOutErrors)&time=lasthour&suppressSummary=false

/service/dataset/metric/summary?entities=ncim-135&metrics=count(health)&time=lasthour&
parentChildRelation=[union/intersection]

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.
The start and end parameters must be used together. The time parameter supersedes start and end if they are all present in the URL.

Supported operators for properties filter are as follows:

For example:

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

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

count must be provided with sort.
metric used in the sort parameter must be in one of the expressions that is used in metrics parameter.
When sort is not provided, output is sorted by entities and rank is shown as zero.

Error response

For example:


{"errorMesg":"Either entities, parents, entityNames, parentNames, entityResourceType 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
`total`	number	Total number of records available
`page`	number	Current page number
`count`	number	Number of records in the page
`items`	list	List of metric values. The entity that is associated with the time and metric value.
`entity`	number	The entity that is associated with the time and metric value.
`parent`	number	The entity that is associated with the time and metric value.
`entityName`	string	The parent entity ID that is associated with the entity.
`parentName`	string	Parent entity name. This value is defaulted to `unknown`, if enrichment fails.
`scope`	string	Scope of the resource. For example, `ibm-itnm` or `flow`.
`startTimestamp`	number	The start time that is associated with the metric value.
`endTimestamp`	number	The end time that is associated with the metric value.
`rank`	number	The rank (1-N) of the record relative to all other entities based on sort. Defaults to 0 if `sort` parameter is not provided.
`metricValues`	list	The list metric names and their values.
`metric`	string	The metric expression for the associated time and metric value.
`metricId`	long	The metric ID for the associated time and metric value.
`value`	number	The metric value for the associated time, entity, and metric expression.
`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,
         "scope":"ibm-itnm",
         "startTimestamp":1469515500000,
         "endTimestamp":1469615500000,
         "rank":1,
         "metricValues":[
            {
               "metric":"min(health)",
               "metricId":2118,
               "value":0
            },
            {
               "metric":"max(health)",
               "metricId":2118,
               "value":54
            },
            {
               "metric":"avg(health)",
               "metricId":2118,
               "value":50
            },
            {
               "metric":"avg(snmpInBandwidth)",
               "metricId":2119,
               "value":150
            }
         ]
      },
      {
         "entity":61,
         "scope":"ibm-itnm",
         "startTimestamp":1469515500000,
         "endTimestamp":1469615500000,
         "rank":2,
         "metricValues":[
            {
               "metric":"min(health)",
               "metricId":2118,
               "value":0
            },
            {
               "metric":"max(health)",
               "metricId":2118,
               "value":54
            },
            {
               "metric":"avg(health)",
               "metricId":2118,
               "value":50
            },
            {
               "metric":"avg(snmpInBandwidth)",
               "metricId":2119,
               "value":150
            }
         ]
      }
   ]
}

JSON code with suppressSummary flag set:

[
   {
      "entity":59,
      "scope":"ibm-itnm",
      "startTimestamp":1469515500000,
      "endTimestamp":1469615500000,
      "rank":1,
      "metricValues":[
         {
            "metric":"min(health)",
            "metricId":2118,
            "value":0
         },
         {
            "metric":"max(health)",
            "metricId":2118,
            "value":54
         }
      ]
   }
]

JSON code with flatten and suppressSummary flags set:

{
   "total":27,
   "page":1,
   "count":27,
   "items":[
      {
         "entity":59,
         "scope":"ibm-itnm",
         "startTimestamp":1469515500000,
         "endTimestamp":1469615500000,
         "rank":1,
         "min(health)":0,
         "max(health)":54,
         "avg(health)":50,
         "avg(snmpInBandwidth)":150
      },
      {
         "entity":61,
         "scope":"ibm-itnm",
         "startTimestamp":1469515500000,
         "endTimestamp":1469615500000,
         "rank":2,
         "min(health)":54,
         "avg(health)":50,
         "avg(snmpInBandwidth)":150
      }
   ]
}

JSON code with flatten and flag set:

[
   {
      "entity":59,
      "scope":"ibm-itnm",
      "startTimestamp":1469515500000,
      "endTimestamp":1469615500000,
      "rank":1,
      "min(health)":0,
      "max(health)":54
   },
   {
      "entity":61,
      "scope":"ibm-itnm",
      "startTimestamp":1469515500000,
      "endTimestamp":1469615500000,
      "rank":2,
      "min(health)":54,
      "avg(health)":50,
      "avg(snmpInBandwidth)":150
   }
]