`summary`

Provides the top 10 values for an aggregation on a flow interface over a period. This API is specific for Flow data only.

This API queries and retrieves information from FLOW_METRIC.RAW, and other FLOW_METRIC. 1MIN/30MIN/1DAY AGGREGATION tables.

URL

https://<dashboard_route>/service/dataset/aggregation/summary

https://<dashboard_hostname>:<dashboard_port>/service/dataset/aggregation/summary

https://<myserver.ibm.com>:31443/service/dataset/aggregation
/summary?aggregation=app_srctos&entity=ncim-102&time=lasthour&granularity=1-minutes

Method

The supported request type.

https GET

URL parameters

Name	Required	Default value	Description
`entity`	Yes	N/A	The entity ID that represents the interface. The three type of entities are: `<FLOW_METRIC.INTERFACE.exporter_ip> -<FLOW_METRIC.INTERFACE.if_index>` `ncim-<NCIM.NETWORK_INTERFACES.entityID>` `flow-<FLOW_METRIC.INTERFACE.entityID>`
`aggregation`	Yes	N/A	The aggregation ID that represents how the data must be aggregated.
`direction`	No	Both	The direction of the flow data that must be returned.
`start`	Yes	N/A	The start time of the period for which flow data must be returned.
`end`	Yes	N/A	The end time of the period for which flow data must be returned.
`time`	Yes	N/A	The name of time short cut: last-hour last-day last-week last-month
`granularity`	No	See Note.	The granularity for which the data must be aggregated. For example, 5 minutes, 14000 minutes.
`remaining`	No	false	A flag to indicate whether a row with the total of the remaining records must be provided.
`extendedAppInfo`	No	false	A flag to indicate whether app base aggregation result contains additional NBAR, and NBAR2 application information as follows: `description` `businessRelevance` `applicationGroup` `applicationCategory` `applicationSubcategory` `p2p_technology` `tunnelTechnology` `encryptedTechnology`

Sample URL


/service/dataset/aggregation/summary?aggregation=app_srctos&entity=ncim-102&time=lasthour&
granularity=1-minutes

/service/dataset/aggregation/summary?
aggregation=app&entity=ncim-102&time=lasthour&granularity=1-minutes&extendedAppInfo=true

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.

Error response

For example:

{
"errorMesg": "Invalid start, end and granularity combination. Granularity : 1 minute StartMs :
1568373360000 endMs : 1468375200000"
}
{
"errorMesg":"Missing mandatory parameter :aggregation"
}

Response

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

Name	Data type	Description
`rank`	number	Rank (1-10) of the record that is relative to all other records. Rank 11 indicates remaining records in total.
`application`	string	Application name as specified in the NBAR2 Protocol Pack. Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`description`	string	Description of the application as specified in the NBAR2 Protocol Pack. Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`srctos`	string	Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`octets`	number	The aggregated octets value for a time period
`packets`	number	The aggregated packets value for a time period
`percentage`	number	The relative percentage of total octets for a time period.
`maxThroughput`	number	The granularity wise max throughput(octets) for a time period
`avgThroughput`	number	The granularity wise avg throughput(octets) for a time period
`maxUtilization`	number	The granularity wise max utilization(octets) for a time period
`avgUtilization`	number	The granularity wise max utilization(octets) for a time period
`label`	string	Aggregation key values that are separated by `/`.
`businessRelevance`	string	Specifies whether the application is considered relevant to the business activity of the organization. Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`applicationGroup`	string	Allows the configuration of applications that are grouped based on the same networking application as the match criteria. Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`applicationCategory`	string	Allows you to configure applications that are grouped based on the first level of categorization for each protocol as the match criteria. Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`applicationSubCategory`	string	Provides the option to configure applications that are grouped based on the second level of categorization for each protocol as the match criteria. Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`p2p_technology`	string	Provides the option to indicate whether a protocol uses p2p technology. Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`tunnelTechnology`	string	Provides the option to configure protocols based on whether a protocol tunnels the traffic of other protocols. Note: Applicable only if the `extendedAppInfo` parameter is enabled.
`encryptedTechnology`	string	Provides the option to configure applications that are grouped based on whether the protocol is an encrypted protocol or not as the match criteria. Note: Applicable only if the `extendedAppInfo` parameter is enabled.

Note:

The actual fields returned depend on the type of aggregation in the URL. The rank, octets, and percentage values are constant for all aggregations.
If granularity is not provided, it is computed as follows:
- If time range is <= 3 hours, granularity = 1 minute.
- If time range is >3 hour and <=12 hour, granularity = 15 minutes.
- If time range is >12 hour and <=7 days, granularity = 30 minutes.
- If time range is between 7 and <90 days, granularity = 1 day.
- If time range is >=90 days, granularity = 7days.

The supported aggregations are as follows:

app – (Application)
app_srctos – (Applications, Source TOS)
conv – (Source, Destination)
conv_app – (Source, Destination, Application)
conv_as – (Source Autonomous System Conversation, Destination Autonomous System Conversation)
conv_tos – (Conversations, TOS)
convgroup – (Source IP Group, Destination IP Group)
convgroup_app – (Source IP Group, Destination IP Group, Application)
convgroup_prot – (Source IP Group, Destination IP Groups, Protocol)
convgroup_tos – (Source IP group, Destination IP Groups, Source TOS)
dstas – (Destination Autonomous System)
dstip – (Destination)
dstip_app – (Destination, Application)
dstipgroup – (Destination IP Group)
dstipgroup_app – (Destination IP Group, Application)
dstipgroup_prot – (Destination IP Group, Protocol)
dstipgroup_tos – (Destination IP Group, Source TOS)
hierarchy_queueid – (QoS Hierarchies with Classification, QoS Hierarchies with Queue ID)
prot – (Protocol)
prot_app – (Protocol, Application)
prot_conv – (Protocol, Source, Destination)
prot_dstip – (Protocol, Destination)
prot_srcip – (Protocol, Source)
srcas – (Source Autonomous System)
srcip – (Source)
srcip_app – (Source, Application)
srcipgroup – (Source IP group)
srcipgroup_app – (Source IP group, Application)
srcipgroup_prot – (Source IP group, Protocol)
srcipgroup_tos – (Source IP group, Source TOS)
srctos – (Source TOS)

JSON code:


[
   {
      "rank":1,
      "application":"ftp",
      "srctos":"AF13",
      "label":"ftp/AF13",
      "octets":22866690,
      "packets":44379,
      "percentage":19.43,
      "maxThroughput":532756.93,
      "avgThroughput":190555.75,
      "maxUtilization":0.05,
      "avgUtilization":0.02
   },
   {
      "rank":2,
      "application":"ssh",
      "srctos":"AF13",
      "label":"ssh/AF13",
      "octets":16502348,
      "packets":35801,
      "percentage":14.02,
      "maxThroughput":318072.67,
      "avgThroughput":137519.57,
      "maxUtilization":0.03,
      "avgUtilization":0.01
   },
   {
      "rank":3,
      "application":"https",
      "srctos":"AF13",
      "label":"https/AF13",
      "octets":16055850,
      "packets":38910,
      "percentage":13.64,
      "maxThroughput":370810.53,
      "avgThroughput":152912.86,
      "maxUtilization":0.04,
      "avgUtilization":0.02
   },
   {
      "rank":4,
      "application":"https",
      "srctos":"AF13",
      "label":"https/AF13",
      "octets":10447134,
      "packets":18166,
      "percentage":8.88,
      "maxThroughput":260432.53,
      "avgThroughput":107150.09,
      "maxUtilization":0.03,
      "avgUtilization":0.01
   },
   {
      "rank":5,
      "application":"bootps",
      "srctos":"AF13",
      "label":"bootps/AF13",
      "octets":9739971,
      "packets":17876,
      "percentage":8.28,
      "maxThroughput":230403.47,
      "avgThroughput":118060.25,
      "maxUtilization":0.02,
      "avgUtilization":0.01
   },
   {
      "rank":6,
      "application":"nicname",
      "srctos":"AF13",
      "label":"nicname/AF13",
      "octets":9577779,
      "packets":19000,
      "percentage":8.14,
      "maxThroughput":178783.87,
      "avgThroughput":91216.94,
      "maxUtilization":0.02,
      "avgUtilization":0.01
   },
   {
      "rank":7,
      "application":"sqlserv",
      "srctos":"AF13",
      "label":"sqlserv/AF13",
      "octets":9437316,
      "packets":26845,
      "percentage":8.02,
      "maxThroughput":340232.93,
      "avgThroughput":125830.88,
      "maxUtilization":0.03,
      "avgUtilization":0.01
   },
   {
      "rank":8,
      "application":"domain",
      "srctos":"AF13",
      "label":"domain/AF13",
      "octets":9058840,
      "packets":14997,
      "percentage":7.70,
      "maxThroughput":287669.60,
      "avgThroughput":109804.12,
      "maxUtilization":0.03,
      "avgUtilization":0.01
   },
   {
      "rank":9,
      "application":"irc",
      "srctos":"AF13",
      "label":"irc/AF13",
      "octets":7185223,
      "packets":9944,
      "percentage":6.10,
      "maxThroughput":197913.07,
      "avgThroughput":106447.75,
      "maxUtilization":0.02,
      "avgUtilization":0.01
   },
   {
      "rank":10,
      "application":"bootpc",
      "srctos":"AF13",
      "label":"bootpc/AF13",
      "octets":6827520,
      "packets":9747,
      "percentage":5.80,
      "maxThroughput":159044.53,
      "avgThroughput":82757.82,
      "maxUtilization":0.02,
      "avgUtilization":0.01
   }
]

Response for the URL with extendedAppInfo flag set:

[
   {
      "rank":1,
      "application":"ftp",
      "description":"",
      "businessRelevance":"",
      "applicationGroup":"",
      "applicationCategory":"",
      "applicationSubCategory":"",
      "p2p_technology":"",
      "tunnelTechnology":"",
      "encryptedTechnology":"",
      "label":"ftp",
      "octets":1627476,
      "packets":5392,
      "percentage":17.00,
      "maxThroughput":216996.80,
      "avgThroughput":216996.80,
      "maxUtilization":0.02,
      "avgUtilization":0.02
   },
   {
      "rank":2,
      "application":"bootps",
      "description":"",
      "businessRelevance":"",
      "applicationGroup":"",
      "applicationCategory":"",
      "applicationSubCategory":"",
      "p2p_technology":"",
      "tunnelTechnology":"",
      "encryptedTechnology":"",
      "label":"bootps",
      "octets":1600439,
      "packets":3975,
      "percentage":16.71,
      "maxThroughput":213391.87,
      "avgThroughput":213391.87,
      "maxUtilization":0.02,
      "avgUtilization":0.02
   }
]