Overview:
This article provides cnMaestro users with a comprehensive explanation of
- Performance and Statistics RESTful API behavior
- How different metrics are calculated with in cnMaestro
- Interpreting Performance API response
- Map Performance API response to cnMaestro UI
What is difference between Statistics and Performance API?
- Statistics API, is focused to serve recent data from a resource. In other words, will always retrieve the current data from the resource.
- Performance API, will help to retrieve historic data from a resource depending on the start and stop time.
Can you explain in detail about these API behaviors?
|
Performance API: |
|
Performance API takes start and stop time as mandatory parameters in the request and if time difference between start and stop time in the query Behavior from 2.1.0 version of cnMaestro:
Behavior until 1.6.3 version of cnMaestro:
API Illustration from 2.1.0 version of cnMaestro: /api/v1/{{device_types}}/XX:XX:XX:XX:XX:XX/performance?start_time=2018-12-27T05:19:43&stop_time=2018-12-28T10:19:43
In the above example, we are querying from 6th hour of 27th day to 11th hour of 28th day for performance data. Based on the given time-stamp there will be record for every hour starting from 6th hour of Dec 27 until 11th hour of Dec 28. Below are the sample records with timestamp. Since, the number of records will be huge truncated to two records for reference. {
"name": "Automation-E500-Clients",
"network": "NBI_clients_network",
"type": "wifi-enterprise",
"timestamp": "2018-12-27T06:00:00+00:00",
"radio": {
"24ghz": {
"clients": 1,
"rx_bps": 168.11,
"throughput": 246.62,
"tx_bps": 78.51
},
"5ghz": {
"clients": 0,
"rx_bps": 0,
"tx_bps": 0
}
},
"tower": "NBI_clients_site",
"mac": "00:04:56:B9:53:E4",
"mode": "wi-fi",
"isSite": true,
"managed_account": ""
},
{
"name": "Automation-E500-Clients",
"network": "NBI_clients_network",
"type": "wifi-enterprise",
"timestamp": "2018-12-27T07:00:00+00:00",
"radio": {
"24ghz": {
"clients": 1,
"rx_bps": 237.23,
"throughput": 313.18,
"tx_bps": 75.95
},
"5ghz": {
"clients": 0,
"rx_bps": 0,
"tx_bps": 0
}
},
"tower": "NBI_clients_site",
"mac": "00:04:56:B9:53:E4",
"mode": "wi-fi",
"isSite": true,
"managed_account": ""
},
Another example, where the start and stop time is less than 24 hours /api/v1/{{device_types}}/XX:XX:XX:XX:XX:XX/performance?start_time=2018-12-27T02:19:43&stop_time=2018-12-27T08:19:43
Since the delta of start and stop time falls less than 24 hours, there would be one record for every periodic stats message (usually 5 mins interval) Sample output looks like below {
"name": "Automation-E500-Clients",
"network": "NBI_clients_network",
"type": "wifi-enterprise",
"timestamp": "2018-12-27T02:20:48+00:00",
"radio": {
"24ghz": {
"clients": 1,
"rx_bps": 358.4,
"throughput": 440.32,
"tx_bps": 81.92
},
"5ghz": {
"clients": 0,
"rx_bps": 0,
"tx_bps": 0
}
},
"tower": "NBI_clients_site",
"mac": "00:04:56:B9:53:E4",
"mode": "wi-fi",
"isSite": true,
"managed_account": ""
},
{
"name": "Automation-E500-Clients",
"network": "NBI_clients_network",
"type": "wifi-enterprise",
"timestamp": "2018-12-27T02:25:49+00:00",
"radio": {
"24ghz": {
"clients": 1,
"rx_bps": 61.44,
"throughput": 133.12,
"tx_bps": 71.68
},
"5ghz": {
"clients": 0,
"rx_bps": 0,
"tx_bps": 0
}
},
"tower": "NBI_clients_site",
"mac": "00:04:56:B9:53:E4",
"mode": "wi-fi",
"isSite": true,
"managed_account": ""
},
API Illustration until 1.6.3 version of cnMaestro: /api/v1/{{device_types}}/XX:XX:XX:XX:XX:XX/performance?start_time=2018-08-06T10:00:00&stop_time=2018-08-07T10:00:00
In the above example, we are querying 6th and 7th dates for performance data. Based on the given time-stamp for Aug 6th records 14hrs data will be be shown (converted to 24hrs format i.e., 9-23), for date 7th 10hrs data will be shown(i.e, 0-9). Below are the sample records with timestamp. "timestamp": "2018-08-06T00:00:00+00:00"
"dl_throughput": {
"9": 3.325,
"10": 4.32636,
"11": 7.1675,
"12": 3.51583,
"13": 4.47833,
"14": 3.34545,
"15": 3.33167,
"16": 3.3475,
"17": 3.33083,
"18": 3.355,
"19": 3.33667,
"20": 3.33667,
"21": 3.33583,
"22": 3.34167,
"23": 3.33
},
"timestamp": "2018-08-07T00:00:00+00:00"
"dl_throughput": {
"0": 3.35167,
"1": 3.3275,
"2": 3.34167,
"3": 3.3425,
"4": 3.335,
"5": 3.33667,
"6": 3.35333,
"7": 3.33833,
"8": 3.37583,
"9": 3.325
}
Another example, where the start and stop time is less than 24 hours /api/v1/{{device_types}}/XX:XX:XX:XX:XX:XX/performance?start_time=2018-08-07T17:00:00&stop_time=2018-08-07T17:00:00
Since the delta of start and stop time falls with in an hour, there would be data entry shown for every 5 minutes interval Sample output looks like below timestamp": "2018-08-07T17:00:00+00:00",
"dl_throughput": {
"0": 3.43,
"5": 3.33,
"10": 3.38,
"15": 3.31,
"20": 3.33,
"25": 3.37,
"30": 3.34,
"35": 3.31,
"40": 3.17,
"45": 3.54,
"50": 3.35,
"55": 3.11
}
To summarize, you will need to adjust the start and stop time to get the detailed historic data for the resource |
|
Statistics API |
|
As stated above, this will help to provide recent data from the resource. API Illustration: /api/v1/devices/statistics Above api will povide current data for all managed devices from cnMaestro system Below is the sample output for the example {
"config_version": "164",
"last_sync": "2018-09-05T14:59:19+00:00",
"mac": "xx:xx:xx:xx:xx:xx",
"managed_account": "",
"mode": "wi-fi",
"name": "Test-3",
"network": "Bangalore",
"parent_mac": "",
"site": "AD-SZone",
"status": "offline",
"status_time": 1531582,
"type": "wifi-enterprise",
"ip_wan": "xx.xx.xx.xx",
"lan_mode_status": "dhcp",
"lan_speed_status": "100M",
"lan_status": "UP",
"radio": {
"24ghz": {
"airtime": "11/0/11/0",
"bssid": "xx:xx:xx:xx:xx:xx",
"channel": "8",
"multicast_rate": "18",
"noise_floor": -97,
"num_clients": 0,
"num_wlans": 2,
"power": 25,
"quality": 78,
"radio_state": "ON",
"rx_bps": 17.48,
"rx_bytes": 1216786,
"tx_bps": 109.21,
"tx_bytes": 6751684,
"unicast_rates": "18b 24 36 48 54",
"utilization": 0
},
"5ghz": {
"airtime": "20/0/20/0",
"bssid": "xx:xx:xx:xx:xx:xx",
"channel": "165",
"multicast_rate": "24",
"noise_floor": -104,
"num_clients": 0,
"num_wlans": 1,
"power": 22,
"quality": 80,
"radio_state": "ON",
"rx_bps": 0,
"rx_bytes": 0,
"tx_bps": 0,
"tx_bytes": 0,
"unicast_rates": "18b 24b 36 48 54",
"utilization": 0
}
}
/api/v1/devices/<mac_address>/statistics This API will provide current data for specific resource, in this example mac_address asked for. Sample response to this API will appear like above |
What is the time frame for calculating these metrics in statistics API?
- it is always the latest value received from device, typically gets updated every 5 minutes
What does each data point represent on performance API? Is that an hourly avg? hourly max?
- data point representation depends on the start and stop time. Please refer to Performance API beahvior explained above for more details.
- About hourly avg or max, it depends on the type of parameter. Below table explains the logic applied to derive data for certain parameters in API
| Name | Logic applied |
| frame_utilization, mcs, retransmits_pct rssi, snr, throughput, clients, rx_bps, tx_bps |
average of the data received in 5 minutes interval |
| kbits, pkts | delta (previous to current value) |
| modulation | last value received from device |
How to interpret the response of performance API, specifically how to convert data points represented as sets into timestamp?
Letz illustrate with sample query and response
From 2.1.0 version:
Performance API response is enhanced to ease the older logic of nested timestamp representation for data points. In the newer implementation, there will be timestamp for each performance record avoiding nested representation.
For more details about Performance records, refer to Detail Illustration about Performance API.
Query:
/api/v1/devices/00:04:56:B9:53:E4/performance?start_time=2018-12-27T01:19:43&stop_time=2018-12-27T03:19:43
Response:
{
"name": "Automation-E500-Clients",
"network": "NBI_clients_network",
"type": "wifi-enterprise",
"timestamp": "2018-12-27T02:10:46+00:00",
"radio": {
"24ghz": {
"clients": 1,
"rx_bps": 133.12,
"throughput": 204.8,
"tx_bps": 71.68
},
"5ghz": {
"clients": 0,
"rx_bps": 0,
"throughput": 0,
"tx_bps": 0
}
},
"site": "NBI_clients_site",
"mac": "00:04:56:B9:53:E4",
"mode": "wi-fi",
"managed_account": ""
},
In the above query, we are querying for the data from 1st to 4th hour. For this illustration we have picked only one record. If you look at the timestamp key in the record (2018-12-27T02:10:46+00:00) it refers to 2nd hour of the day and all the details in the record are pertaining to the 2nd hour 10minutes and 46seconds.
Until 1.6.3 version:
Query1:
/api/v1/devices/<mac_address>/performance?start_time=2018-09-24T2:00:00&stop_time=2018-09-24T03:00:00
Response1:
"timestamp": "2018-09-24T02:00:00+00:00",
"type": "wifi-enterprise",
"radio": {
"24ghz": {
"clients": {
"5": 1,
"10": 1,
"15": 1,
"20": 1,
"25": 1
},
"rx_bps": {
"5": 0.01,
"10": 0.2,
"15": 0.04,
"20": 0.01,
"25": 0.01
},
"throughput": {
"5": 1.17,
"10": 1.43,
"15": 1.1600000000000001,
"20": 1.11,
"25": 1.09
},
In Query1, the delta of start and stop time is less than a day hence, there would be data for every 5 minutes.
Now letz convert entry of each record into timestamp. In this example, timestamp for the data is "2018-09-24T02:00:00+00:00" and data is avaialable for every 5 minute interval, hence add 5 minutes to the each record say
Timestamp_of_the_data + <add 5 minutes for each entry in the record since the every record is a 5 min interval>
Above response will look as represented below after adding timestamps to every entry in the record. This example is just for reference only. Due to larger response, culled only one parameter for the conversion demonstration
"timestamp": "2018-09-24T02:00:00+00:00",
"type": "wifi-enterprise",
"radio": {
"24ghz": {
"clients": {
"2018-09-24T02:05:00+00:00": 1,
"2018-09-24T02:10:00+00:00": 1,
"2018-09-24T02:15:00+00:00": 1,
"2018-09-24T02:20:00+00:00": 1,
"2018-09-24T02:25:00+00:00": 1
},
"throughput": {
"2018-09-24T02:05:00+00:00": 1.17,
"2018-09-24T02:10:00+00:00": 1.43,
"2018-09-24T02:15:00+00:00": 1.1600000000000001,
"202018-09-24T02:20:00+00:00: 1.11,
"2018-09-24T02:25:00+00:00": 1.09
}
Letz take another example query, letz frame this Query2 so that the delta between start and stop time is more than a day
Query2:
/api/v1/devices/<mac_address>/performance?start_time=2018-09-23T2:00:00&stop_time=2018-09-24T03:00:00
Response2:
"timestamp": "2018-09-23T00:00:00+00:00",
"type": "wifi-enterprise",
"radio": {
"24ghz": {
"clients": {
"1": 1,
"2": 1,
"3": 1,
"4": 1,
"5": 1,
"6": 1,
"7": 1,
"8": 1,
"9": 1,
"10": 1,
"11": 1,
"12": 1,
"13": 1,
"14": 1,
"15": 1,
"16": 1,
"17": 1,
"18": 1,
"19": 1,
"20": 1,
"21": 1,
"22": 1,
"23": 1
},
In Query2, the delta of start and stop time is more than a day hence, there would be data for every hour.
Now letz convert entry of each record into timestamp. In this example, timestamp for the data is " 2018-09-23T00:00:00+00:00" and data is avaialable for every hour interval, hence add an hour to the each record say
Timestamp_of_the_data + <add an hour for each entry >
Above response will look as represented below after adding timestamps to every entry in the record.
"timestamp": "2018-09-23T00:00:00+00:00",
"type": "wifi-enterprise",
"radio": {
"24ghz": {
"clients": {
"2018-09-23T01:00:00+00:00": 1,
"2018-09-23T02:00:00+00:00": 1,
"2018-09-23T03:00:00+00:00": 1,
"2018-09-23T04:00:00+00:00": 1,
"2018-09-23T05:00:00+00:00": 1,
"2018-09-23T06:00:00+00:00": 1,
"2018-09-23T07:00:00+00:00": 1,
"2018-09-23T08:00:00+00:00": 1,
"2018-09-23T09:00:00+00:00": 1,
"2018-09-23T10:00:00+00:00": 1,
"2018-09-23T11:00:00+00:00": 1,
"2018-09-23T12:00:00+00:00": 1,
"2018-09-23T13:00:00+00:00": 1,
"2018-09-23T14:00:00+00:00": 1,
"2018-09-23T15:00:00+00:00": 1,
"2018-09-23T16:00:00+00:00": 1,
"2018-09-23T17:00:00+00:00": 1,
"2018-09-23T18:00:00+00:00": 1,
"2018-09-23T19:00:00+00:00": 1,
"2018-09-23T20:00:00+00:00": 1,
"2018-09-23T21:00:00+00:00": 1,
"2018-09-23T22:00:00+00:00": 1,
"2018-09-23T23:00:00+00:00": 1
},
Can you explain how can i map API response to cnMaestro UI?
From 2.1 version:
For this demonstration, let us refer to below sample response
"name": "Automation-E500-Clients",
"network": "NBI_clients_network",
"type": "wifi-enterprise",
"timestamp": "2018-12-27T02:10:46+00:00",
"radio": {
"24ghz": {
"clients": 1,
"rx_bps": 133.12,
"throughput": 204.8,
"tx_bps": 71.68
},
Let us see how can we map throughput and clients info to the cnMaestro UI.
In the example, timestamp refers to "2018-12-27T02:10:46+00:00" which is always represented in UTC.
Make sure you first identify the timezone your are launching cnMaestro UI and convert the above timestamp to timezone you are running.
Since i am launching cnMaestro in IST, i will add +5.30 hrs for the above timestamp which looks like below
timestamp from API response: "2018-12-27T02:10:46+00:00" timestamp after converting to IST: "2018-12-27T07:40:46+00:00"
From the cnMaestro UI, let us refer to the "2018-12-27T07:40:46+00:00" and validate the API response against UI.
For the given timestamp, API response is as below
"radio": {
"24ghz": {
"clients": 1,
"rx_bps": 133.12,
"throughput": 204.8,
"tx_bps": 71.68
},
Until 1.6.3 version:
for this demonstration, let us take examples of above queries Query1 and Query2.
Query1, refer to the response after converting to timestamp which looks like
"throughput": {
"2018-09-24T02:05:00+00:00": 1.17,
"radio": {
"24ghz": {
"clients": {
"2018-09-24T02:05:00+00:00": 1,
since the timestamps displayed in API are UTC timezone, make sure you first identify the timezone your are running and convert the above timestamp to timezone you are running.
Since i am running in IST, i will add +5.30 hrs for the above timestamp which looks like below
timestamp_of_the_record + your_Timezone --> Time_Stamp_in_respective_TimeZone Example: 2018-09-24T02:05:00+00:00 + 5.30 --> 2018-09-24T07:35:00+00:00
actual_throughput_record:
"throughput": {
"2018-09-24T02:05:00+00:00": 1.17,
throughput_record_after_timezone_conversion:
"throughput": {
"2018-09-24T07:35:00+00:00": 1.17,
actual_clients_record:
"24ghz": {
"clients": {
"2018-09-24T02:05:00+00:00": 1,
clients_record_after_timezone_conversion:
"24ghz": {
"clients": {
"2018-09-24T07:35:00+00:00": 1,
Now let us pick this time "2018-09-24T07:35:00+00:00". API response shows that for the given timestamp throughput is 1.17 and clients connected is ONE. Now let us check the data from cnMaestro UI for comparison.
cnMaestro UI data point at the given timestamp for throughput
cnMaestro UI data point at the given timestamp for clients
Now let us take another example where data is represented for every hour and validate the data from API to cnMaestro UI
actual_record:
"24ghz": {
"clients": {
"2018-09-23T01:00:00+00:00": 1,
record_after_timezone_conversion:
"24ghz": {
"clients": {
"2018-09-23T06:30:00+00:00": 1,
Now let us pick again time "2018-09-23T06:30:00+00:00". API response shows that for the given timestamp clients connected is ONE. Now let us check the data from cnMaestro UI for comparison.
cnMaestro UI data point at the given timestamp
