- 10 Jan 2023
- 6 Minutes to read
- Print
- DarkLight
- PDF
How to Retrieve Performance Data for a Device Using the Netreo APIs
- Updated on 10 Jan 2023
- 6 Minutes to read
- Print
- DarkLight
- PDF
Using Netreo's APIs, you can retrieve the recorded performance data for individual instances of statistics for a given device. This is useful, for example, if you would like to store this data for a longer period of time than Netreo is capable. The data is provided as part of a JSON object, and includes the value of the statistic itself and the timestamp of when the data was recorded by Netreo.
It is important to remember that the data set retrieved is only for the specified instance of a particular statistic. To retrieve all of a device's performance data, you will have to repeat these steps multiple times to retrieve the data sets for each individual instance of every different statistic type.
Step 1. Retrieve Device Index
The first thing you need is the index number of the device for which you want to retrieve the data. This can be quickly accomplished using any of the following APIs:
- Device Management API - GET or POST. Use the Device Metadata endpoint to retrieve the device index.
- Category API - POST only. First use the Category ID List endpoint to retrieve the ID for the category containing the device. Then use the Category Device List endpoint to retrieve the dev_index for the device.
- Site API - POST only. First use the Site ID List endpoint to retrieve the ID for the site containing the device. Then use the Site Device List endpoint to retrieve the dev_index for the device.
- Strategic Group API - POST only. First use the Strategic Group ID List endpoint to retrieve the ID for the strategic group containing the device. Then use the Strategic Group Device List endpoint to retrieve the dev_index for the device.
Once you have the device index number move to the next step, where you'll be using the Device Performance API to retrieve the various data required to finally retrieve the desired performance data. You will need to provide the device index for every endpoint that you use.
Step 2. Retrieve Statistic Category
Use the Performance Statistic Category ID List endpoint of the Device Performance API to retrieve the list of statistic categories available for the specified device. POST only. Don't forget to provide the Netreo API key if one has been set.
Curl example using POST with API Authentication Enabled:
curl -X POST \ 'http://38.2.11.62/fw/index.php?r=restful/devices/performance-category' \ -F password=pass123 \ -F device_id=3
Statistic categories are things like CPU, Disk, Memory, etc. Look at the "category" field of the returned data to determine which category is the one you want. Then, make note of the category "id". You will use this with the next endpoint.
Example JSON output from above curl:
[ { "id": 1, "category": "CPU" }, { "id": 9, "category": "Disk" }, { "id": 5, "category": "Latency" }, { "id": 2, "category": "Memory" }, { "id": "interfaces", "cat": "Network" } ]
Step 3. Retrieve Statistic Instance
Use the Statistic Instance List endpoint of the Device Performance API to retrieve the list of individual instances of the specified statistic category for the device. POST only. Don't forget to provide the Netreo API key if one has been set.
Curl using POST with API Authentication Enabled:
curl -X POST \ 'http://38.2.11.62/fw/index.php?r=restful/devices/performance-instance-per-category' \ -F password=pass123 \ -F device_id=3 \ -F id=9
Look at the "description" field of the returned data to determine which instance is the one you want. Then, make note of the instance "key" and "type". You will use these with the next endpoint.
Example JSON output from above curl:
[ { "key": "21117", "type": "oid_pertable", "index": "156", "title": "Hard Drive Usage", "unit": "B", "description": "/" }, { "key": "21115", "type": "oid_pertable", "index": "156", "title": "Hard Drive Usage", "unit": "B", "description": "/dev/shm" }, { "key": "21116", "type": "oid_pertable", "index": "156", "title": "Hard Drive Usage", "unit": "B", "description": "/boot" } ]
Step 4. Retrieve Performance Data
Use the Performance Data endpoint of the Device Performance API to retrieve the performance data set for the specified instance. POST only. You will need to specify a time frame for the data set using the "quick_time" parameter. The available time frames are explained in the table below.
Quick Time | Description |
---|---|
lasthour | Data values from the previous 60 minutes from time of retrieval. |
last5 | Data values from the current timestamp five hours ago until the time of retrieval. |
last15 | Data values from the current timestamp fifteen hours ago until the time of retrieval. |
last24 | Data values from the current timestamp twenty four hours ago until the time of retrieval. |
today | Data values from 00:00 hours that morning to the time of retrieval. |
yesterday | Data values from 00:00 hours to 12:59 from the previous day. |
7dy | Data values from the current timestamp seven days ago until the time of retrieval. |
thisweek | Data values from 00:00 hours of the first day of the current week until the time of retrieval. |
lastweek | Data values from 00:00 hours of the first day of the previous week until 12:59 of the last day of the previous week. |
thismonth | Data values from 00:00 hours of the first day of the current month until the time of retrieval. |
lastmonth | Data values from 00:00 hours of the first day of the previous month until 12:59 of the last day of the previous month. |
thisyear | Data values from 00:00 hours of the first day of the current year until the time of retrieval. |
last12months | Data values from the current timestamp twelve months ago until the time of retrieval. |
Curl using POST with API Authentication Enabled:
curl -X POST \ 'http://38.2.11.62/fw/index.php?r=restful/devices/data-per-instance' \ -F password=pass123 \ -F device_id=14 \ -F type=oid_pertable \ -F key=21117 \ -F quick_time=last24
Remember that performance statistics for devices are recorded roughly every five minutes. That translates to roughly 12 sets of data values per hour. But data older than 100 days is rolled up into 30 minutes averages. So, retrieving a data set that includes data older than 100 days will result in a data set of 30-minute averages (2 sets of data values per hour). See Data Retention in Netreo for more information about how performance data is stored.
Example JSON output from above curl (the "data" array is the performance data in the format "timestamp,data value"):
[ { "name": "/", "legend": "Free Drive Space", "max": "16855834624.000000", "avg": "16855619007.668148", "current": "16855404817.066666", "data": [ "1548253800,16855831970.702223", "1548254700,16855827988.480001", "1548255600,16855822336.000000", "1548256500,16855818331.022223", "1548257400,16855815623.111109", "1548258300,16855810266.453333", "1548259200,16855801974.328888", "1548260100,16855797760.000000", "1548261000,16855793745.920000", "1548261900,16855792380.586668", "1548262800,16855787083.093332", "1548263700,16855781376.000000", "1548264600,16855777366.471109", "1548265500,16855776023.893333", "1548266400,16855771900.586668", "1548267300,16855769088.000000", "1548268200,16855765083.022223", "1548269100,16855763699.484444", "1548270000,16855759617.137777", "1548270900,16855755507.484444", "1548271800,16855748758.186666", "1548272700,16855746013.866667", "1548273600,16855743233.137777", "1548274500,16855740416.000000", "1548275400,16855736397.368889", "1548276300,16855733757.724443", "1548277200,16855729570.702223", "1548278100,16855726844.586668", "1548279000,16855722753.137777", "1548279900,16855715921.920000", "1548280800,16855713223.111109", "1548281700,16855710519.751112", "1548282600,16855707648.000000", "1548283500,16855703647.573334", "1548284400,16855700916.906668", "1548285300,16855698186.240000", "1548286200,16855695360.000000", "1548287100,16855690071.608887", "1548288000,16855684523.804443", "1548288900,16855681784.035555", "1548289800,16855678976.000000", "1548290700,16855675039.288889", "1548291600,16855670879.573334", "1548292500,16855669496.035555", "1548293400,16855666688.000000", "1548294300,16855662678.471109", "1548295200,16855658687.146667", "1548296100,16855651751.253334", "1548297000,16855649052.444443", "1548297900,16855646208.000000", "1548298800,16855635713.137777", "1548299700,16855610053.973333", "1548300600,16855594525.582220", "1548301500,16855574455.182220", "1548302400,16855557679.786667", "1548303300,16855553547.377777", "1548304200,16855546638.791109", "1548305100,16855543808.000000", "1548306000,16855541163.804443", "1548306900,16855537081.457777", "1548307800,16855534359.893333", "1548308700,16855531520.000000", "1548309600,16855528907.662222", "1548310500,16855524793.457777", "1548311400,16855519432.248886", "1548312300,16855515136.000000", "1548313200,16855511144.675554", "1548314100,16855508404.906668", "1548315000,16855505651.484444", "1548315900,16855502848.000000", "1548316800,16855498833.920000", "1548317700,16855494747.022223", "1548318600,16855492066.417778", "1548319500,16855486650.595552", "1548320400,16855481093.688889", "1548321300,16855478272.000000", "1548322200,16855475641.457777", "1548323100,16855472892.586668", "1548324000,16855468792.035555", "1548324900,16855465984.000000", "1548325800,16855463348.906668", "1548326700,16855460618.240000", "1548327600,16855453909.902222", "1548328500,16855449600.000000", "1548329400,16855445608.675554", "1548330300,16855444216.035555", "1548331200,16855440133.688889", "1548332100,16855437312.000000", "1548333000,16855433320.675554", "1548333900,16855430571.804443", "1548334800,16855426503.111109", "1548335700,16855421119.146666", "1548336600,16855416832.000000", "1548337500,16855414187.804443", "1548338400,16855410123.662222", "1548339300,16855407365.688889" ] }, { "name": "/", "legend": "Used Drive Space", "max": "1513991918.931968", "avg": "1513777728.331852", "current": "1513991918.933333", "data": [ "1548253800,1513564765.297778", "1548254700,1513568747.520000", "1548255600,1513574400.000000", "1548256500,1513578404.977778", "1548257400,1513581112.888889", "1548258300,1513586469.546667", "1548259200,1513594761.671111", "1548260100,1513598976.000000", "1548261000,1513602990.080000", "1548261900,1513604355.413333", "1548262800,1513609652.906667", "1548263700,1513615360.000000", "1548264600,1513619369.528889", "1548265500,1513620712.106667", "1548266400,1513624835.413333", "1548267300,1513627648.000000", "1548268200,1513631652.977778", "1548269100,1513633036.515556", "1548270000,1513637118.862222", "1548270900,1513641228.515556", "1548271800,1513647977.813334", "1548272700,1513650722.133333", "1548273600,1513653502.862222", "1548274500,1513656320.000000", "1548275400,1513660338.631111", "1548276300,1513662978.275555", "1548277200,1513667165.297778", "1548278100,1513669891.413333", "1548279000,1513673982.862222", "1548279900,1513680814.080000", "1548280800,1513683512.888889", "1548281700,1513686216.248889", "1548282600,1513689088.000000", "1548283500,1513693088.426666", "1548284400,1513695819.093333", "1548285300,1513698549.760000", "1548286200,1513701376.000000", "1548287100,1513706664.391111", "1548288000,1513712212.195555", "1548288900,1513714951.964444", "1548289800,1513717760.000000", "1548290700,1513721696.711111", "1548291600,1513725856.426667", "1548292500,1513727239.964444", "1548293400,1513730048.000000", "1548294300,1513734057.528889", "1548295200,1513738048.853333", "1548296100,1513744984.746667", "1548297000,1513747683.555555", "1548297900,1513750528.000000", "1548298800,1513761022.862222", "1548299700,1513786682.026667", "1548300600,1513802210.417777", "1548301500,1513822280.817778", "1548302400,1513839056.213333", "1548303300,1513843188.622222", "1548304200,1513850097.208889", "1548305100,1513852928.000000", "1548306000,1513855572.195555", "1548306900,1513859654.542222", "1548307800,1513862376.106667", "1548308700,1513865216.000000", "1548309600,1513867828.337778", "1548310500,1513871942.542222", "1548311400,1513877303.751111", "1548312300,1513881600.000000", "1548313200,1513885591.324445", "1548314100,1513888331.093333", "1548315000,1513891084.515556", "1548315900,1513893888.000000", "1548316800,1513897902.080000", "1548317700,1513901988.977778", "1548318600,1513904669.582222", "1548319500,1513910085.404444", "1548320400,1513915642.311111", "1548321300,1513918464.000000", "1548322200,1513921094.542222", "1548323100,1513923843.413333", "1548324000,1513927943.964444", "1548324900,1513930752.000000", "1548325800,1513933387.093333", "1548326700,1513936117.760000", "1548327600,1513942826.097778", "1548328500,1513947136.000000", "1548329400,1513951127.324445", "1548330300,1513952519.964444", "1548331200,1513956602.311111", "1548332100,1513959424.000000", "1548333000,1513963415.324445", "1548333900,1513966164.195555", "1548334800,1513970232.888889", "1548335700,1513975616.853333", "1548336600,1513979904.000000", "1548337500,1513982548.195555", "1548338400,1513986612.337778", "1548339300,1513989370.311111" ] } ]