Network Traffic Analytics API

How It Works

Network traffic analytics for each meter are stored as a set of CSV files in an Amazon S3 bucket. Software Developers can retrieve these files using the Amazon S3 REST API.

In order to make requests to Amazon S3 to retrieve the CSV files, developers will be provided with credentials (AWS access Key ID and AWS secret access key).

With the above credentials, developers can make REST API calls directly from code, or use the AWS SDKs or AWS CLI to make Amazon S3 API calls. For full details, follow the Amazon S3 Rest API documentation:

https://docs.aws.amazon.com/AmazonS3/latest/API

For each CSV file, the endpoint URL can be contrsucted by combining the meter ID with the CSV file name:

https://prilink-nta.s3.amazonaws.com/{meter-ID}/{CSV-file-name}

Example

AWS provides SDKs for many programming languages – in this example, we are using Python to retrieve a single CSV file. The AWS SDK for Python is called Boto3. To retrieve the file, we need our credentials (access key and secret access key) and the meter ID (in this example, 8/1).

In this snippet, the CSV file we are downloading contains SIP traffic chart data (sip-chart.csv). See the CSV File Layout section below for the full list of CSV files available.

  import boto3
  
  client = boto3.client('s3',
                        aws_access_key_id='AKIAIOSFODNN7EXAMPLE',
                        aws_secret_access_key='wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY')
  
  client.download_file('prilink-nta', '8/1/sip-chart.csv', 'sip-chart.csv')

CSV File layout

Network traffic analytics consists of a set of 10 CSV files. The name and format of each file is documented below.

IP ChartIP PortIP Most Active SummaryIP Most Active ComparisonIP Table DefinitionSIP ChartSIP Most Active NumbersSIP SummarySIP CDRSIP Group Defnition

IP Chart (ip-chart-012.csv)

This file contains traffic statistics for each IP address in the IP table. Statistics are recorded for every 15-minute interval over the last 14 days.

Sample

  row,tIndex,date,download BW,BW_d_log(1024),upload BW,BW_u_log(1024),connection,download speed(bps),speed_d_log(1024),upload speed(bps),speed_u_log(1024),download packet,packet_d_log(1024),upload packet,packet_u_log(1024),sync-in,sync-out,finRst-in,finRst-out
  0,0,2021-10-22 19:45:00,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
  1,0,2021-10-22 20:00:00,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
  2,0,2021-10-22 20:15:00,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
  3,0,2021-10-22 20:30:00,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
  4,0,2021-10-22 20:45:00,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0
  ...

Download full sample

Fields

Name	Value	Description
row	Number	Row number
tIndex	Number (0‑2)	The entry in the IP table that this record belongs to. This indicates which IP address this record belongs to.
date	Datetime (YYYY-MM-DD HH:mm:ss)	15-minute interval.
download BW	String	Total bytes downloaded during 15-minute interval, including metric prefix.
BW_d_log(1024)	Number	Logarithm base 1024 of the total number of bytes downloaded during 15-minute interval.
upload BW	String	Total bytes uploaded during 15-minute interval, including metric prefix.
BW_u_log(1024)	Number	Logarithm base 1024 of the total number of bytes uploaded during 15-minute interval.
connection	Number	Total number of IP sessions during 15-minute interval.
download speed(bps)	String	Maximum download speed in bits per second during 15-minute interval, including metric prefix.
speed_d_log(1024)	Number	Logarithm base 1024 of the maximum download speed during 15-minute interval.
upload speed(bps)	String	Maximum upload speed in bits per second during 15-minute interval, including metric prefix.
speed_u_log(1024)	Number	Logarithm base 1024 of the maximum upload speed during 15-minute interval.
download packet	String	Total packets downloaded during 15-minute interval, including metric prefix.
packet_d_log(1024)	Number	Logarithm base 1024 of the total packets downloaded during 15-minute interval.
upload packet	String	Total packets uploaded during 15-minute interval, including metric prefix.
packet_u_log(1024)	Number	Logarithm base 1024 of the total packets uploaded during 15-minute interval.
sync-in	Number	Total number of inbound packets with SYN flag set during 15-minute interval.
sync-out	Number	Total number of outbound packets with SYN flag set during 15-minute interval.
finRst-in	Number	Total number of inbound packets with FIN or RST flag set during 15-minute interval.
finRst-out	Number	Total number of outbound packets with FIN or RST flag set during 15-minute interval.

IP Port (ip-port-012.csv)

This file contains TCP / UDP port statistics for each IP address in the IP table. Statistics are recorded for each TCP / UDP port number detected over the last 14 days, and sorted by total bandwidth.

Sample

  row,tIndex,port,down/upload BW,percent,time,down/upload speed (bps)
  0,0,49707,3.10M 16.21K,11.20,0.50hr,0  0 
  1,0,3389,478.40K 2.20M,9.44,0.75hr,0  0 
  2,0,49758,1.54M 32.34K,5.56,0.50hr,0  0 
  3,0,49790,1.44M 9.74K,5.15,0.50hr,0  0 
  4,0,49692,1.24M 74.57K,4.66,0.75hr,0  0 
  ...

Download full sample

Fields

Name	Value	Description
row	Number	Row number
tIndex	Number (0‑2)	The entry in the IP table that this record belongs to. This indicates which IP address this record belongs to.
port	Number (0‑65535)	TCP / UDP port number.
down/upload BW	String	Total bytes downloaded and uploaded (space separated), including metric prefix.
percent	Number	Percentage of overall IP bandwidth used by this port number.
time	String	Total time that his port number was used over the last 14 days.
down/upload speed (bps)	String	Maximum download and upload speed (space separated) in bits per second, including metric prefix.

IP Most Active Summary (ip-dash.csv)

This file contains summary of the most active IP addresses, IP-Port combinations (endpoints), and IP-IP routes. The top 128 entries are sorted by bandwidth, duration, packet count, and number of routes.

Sample

  row,dIndex,period,rec,alert,ID,speed_down,speed_up,BW_down,BW_up,BW_down%,BW_up%,BW%,duration,duration%,packet_down,packet_up,packet_down%,packet_up%,route,route%
  0,0,24-hour,0, ,155:155:87:211,49.11M bps,3.45M bps,24.18M,4.20M,85.72,14.27,99.99,0.50hr,2.80,49.11M,3.45M,61.79,38.16,163,98.19
  1,0,24-hour,1, ,72:21:81:240,1.23K bps,56.46K bps,20.74K,4.30M,0.70,14.28,14.35,0.25hr,1.40,1.23K,56.46K,0.63,6.50,1,0.60
  2,0,24-hour,2, ,104:118:8:139,768  bps,89.10K bps,14.90K,3.90M,0.50,10.98,11.30,0.25hr,1.40,768 ,89.10K,0.51,4.62,1,0.60
  3,0,24-hour,3, ,65:95:7:144,43.53K bps,9.86K bps,2.20M,478.12K,7.81,1.65,9.46,0.50hr,2.80,43.53K,9.86K,12.23,11.77,1,0.60
  4,0,24-hour,4, ,23:78:87:233,61.14K bps,419.31K bps,76.12K,1.93M,0.26,6.86,7.12,0.25hr,1.40,61.14K,419.31K,1.27,3.51,1,0.60
  ...

Download full sample

Fields

Name	Value	Description
row	Number	Row number
dIndex	Number (0‑10)	The type of summary that this record belongs to. Possible values are as follows: 0: IP addresses, sorted by bandwidth 1: IP addresses, sorted by number of routes 2: IP addresses, sorted by packet count 3: IP addresses, sorted by duration 4: IP-Port combinations, sorted by bandwidth 5: IP-Port combinations, sorted by number of routes 6: IP-Port combinations, sorted by packet count 7: IP-Port combinations, sorted by duration 8: IP-IP pairs, sorted by bandwidth 9: IP-IP pairs, sorted by packet count 10: IP-IP pairs, sorted by duration
period	String	The time period that this record belongs to. Possible values are 24-hour, 7-day, or 14-day.
rec	Number (0‑127)	Rank of this entry.
alert	String	Asterisk (*) indicates deviation from normal traffic pattern for this entry.
ID	String	The format of ID depends on the value of dIndex: dIndex 0-3: IP address dIndex 4-7: IP address + TCP / UDP Port number dIndex 8-10: Pair of IP addresses
speed_down	String	Maximum download speed in bits per second, including metric prefix.
speed_up	String	Maximum upload speed in bits per second, including metric prefix.
BW_down	String	Total bytes downloaded, including metric prefix.
BW_up	String	Total bytes uploaded, including metric prefix.
BW_down%	Number	Total bytes downloaded, as a percentage of overall IP bandwidth.
BW_up%	Number	Total bytes uploaded, as a percentage of overall IP bandwidth.
BW%	Number	Total bytes downloaded or uploaded, as a percentage of overall IP bandwidth.
duration	String	Total amount of time that this entry was active.
duration	Number	Total amount of time that this entry was active, as a percentage of period.
packet_down	String	Total packets downloaded, including metric prefix.
packet_up	String	Total packets uploaded, including metric prefix.
packet_down%	Number	Total packets downloaded, as a percentage of overall IP packet count.
packet_up%	Number	Total packets uploaded, as a percentage of overall IP packet count.
route	Number	Total number of routes involving this entry.
route%	Number	Total number of routes involving this entry, as a percentage of overall IP route count.

IP Most Active Comparison (ip-dash-s.csv)

This file contains a bandwidth comparison of the most active network entities over 24-hour, 7-day, and 14-day periods. note: this file has not header row.

Sample

  0,0,rec,alert,24-hour,BW 28.21M,alert,7-day,BW 28.29M,alert,14-day,BW 28.29M
  1,0,0, ,155:155:87:211,, ,155:155:87:211,, ,155:155:87:211,
  2,0,1, ,72:21:81:240,14.35%, ,72:21:81:240,14.31%, ,72:21:81:240,14.31%
  3,0,2, ,104:118:8:139,, ,104:118:8:139,11.30%, ,104:118:8:139,11.00%
  4,0,3, ,65:95:7:144,11.00%, ,65:95:7:144,, ,65:95:7:144,9.46%
  5,0,4, ,23:78:87:233,9.44%, ,23:78:87:233,9.44%, ,23:78:87:233,
  ...

Download full sample

Fields

Name	Value	Description
Column-1	Number	Row number
Column-2	Number (0‑10)	The type of summary that this record belongs to. Possible values are as follows: 0: IP addresses, sorted by bandwidth 1: IP addresses, sorted by number of routes 2: IP addresses, sorted by packet count 3: IP addresses, sorted by duration 4: IP-Port combinations, sorted by bandwidth 5: IP-Port combinations, sorted by number of routes 6: IP-Port combinations, sorted by packet count 7: IP-Port combinations, sorted by duration 8: IP-IP pairs, sorted by bandwidth 9: IP-IP pairs, sorted by packet count 10: IP-IP pairs, sorted by duration
Column-3	Number (0‑31)	Rank of this entry.
Column-4	String	Alert. Asterisk () indicates deviation from normal traffic pattern over 24-hours for the entity in Column-5*.
Column-5	String	Entity ID. The format of ID depends on the value of Column-2: 0-3: IP address 4-7: IP address + TCP / UDP Port number 8-10: Pair of IP addresses
Column-6	String	Total bytes downloaded or uploaded over 24-hours by entity in Column-5, as a percentage of overall IP bandwidth over 24-hours.
Column-7	String	Alert. Asterisk () indicates deviation from normal traffic pattern over 7-days for the entity in Column-8*.
Column-8	String	Entity ID. The format of ID depends on the value of Column-2: 0-3: IP address 4-7: IP address + TCP / UDP Port number 8-10: Pair of IP addresses
Column-9	String	Total bytes downloaded or uploaded over 7-days by entity in Column-8, as a percentage of overall IP bandwidth over 7-days.
Column-10	String	Alert. Asterisk () indicates deviation from normal traffic pattern over 14-dayss for the entity in Column-11*.
Column-11	String	Entity ID. The format of ID depends on the value of Column-2: 0-3: IP address 4-7: IP address + TCP / UDP Port number 8-10: Pair of IP addresses
Column-12	String	Total bytes downloaded or uploaded over 14-days by entity in Column-11, as a percentage of overall IP bandwidth over 14-days.

IP Table Definition(ip-qsMsg.csv)

This file contains the definition of 3 IP addresses that will be tracked to produce the analytics in ip-chart-012.csv and ip-port-012.csv. The IP table can be defined manually using the t-Console application. If not defined manually, then the IP table is automatically defined to be the top 3 most active IP addresses over the last 14 days.

Sample

  row,name
  0,1-mostActive IP 155:155:87:211  
  1,2-mostActive IP 20:190:157:11  
  2,3-mostActive IP 52:167:249:196  
  ...

Download full sample

Fields

Name	Value	Description
Row	Number	Row number
name	String	IP address

SIP Chart (sip-chart.csv)

This file contains SIP traffic statistics for every 15-minute interval over the last 24 hours and the last 14 days. For each interval, seperate records are created for incoming and outgoing traffic, as well as for each SIP group.

Sample

  row,period,type,time,channel,ans,nAns
  0,0,0,2020-1-3 00:00:00,4,12,0
  1,0,0,2020-1-3 00:15:00,5,12,0
  2,0,0,2020-1-3 00:30:00,6,16,0
  3,0,0,2020-1-3 00:45:00,5,17,0
  4,0,0,2020-1-3 01:00:00,3,8,0
  ...

Download full sample

Fields

Name	Value	Description
row	Number	Row number
period	Number (0‑1)	The time period that this record belongs to. Possible values are as follows: 0: Last 24 hours 1: Last 14 days
type	Number (0‑4)	The type of traffic included in this record. Possible values are as follows: 0: Incoming 1: Outgoing 2: 1st SIP group 3: 2nd SIP group 4: 3rd SIP group
time	Datetime (YYYY-MM-DD HH:mm:ss)	15-minute interval.
channel	Number	Maximum number of simultaneous calls during 15-minute interval.
ans	Number	Total number of answered calls during 15-minute interval.
nAns	Number	Total number of not-answered calls during 15-minute interval.

SIP Most Active Numbers (sip‑mostActive.csv)

This file contains the top 50 most active SIP phone numbers over the last 24 hours and last 14 days.

Sample

  row,period,rank,alert,number,name,ans,Nans,percent
  0,0,1,  ,2086207916,,2084,6,17.62%
  1,0,2,  ,2084209377,,1558,2,13.15%
  2,0,3,  ,2089490468,,468,9,4.20%
  3,0,4,  ,2083920456,xxxxxxxxx,405,53,3.86%
  4,0,5,  ,2056907000,xxxxxxxxxx,422,0,3.56%
  ...

Download full sample

Fields

Name	Value	Description
Row	Number	Row number
period	Number (0‑1)	The time period that this record belongs to. Possible values are as follows: 0: Last 24 hours 1: Last 14 days
rank	Number	Rank by total call volume (1-50).
alert	String	Double asterisk (**) indicates an unusual traffic pattern for this phone number based on the last 14 days of traffic.
number	String	SIP phone number.
name	String	Display name (if available).
ans	Number	Total number of answered calls involving this phone number.
nAns	Number	Total number of not-answered calls involving this phone number.
percent	Number	Total call volume for this phone number, reported as a percentage of total SIP trunk traffic.

Sip Summary (sip-sum.csv)

This file contains a summary of the most active internal and external phone numbers, as well as the most active SIP response codes used for not-answered calls. Seperate records are created for incoming and outgoing traffic, as well as for each SIP group.

Sample

  row,period,sipIndex,type,number,name,ans,nAns,avgTalk(s)
  0,0,0,0,2086207916,,2084,6,161
  1,0,0,0,2084209377,,1558,2,119
  2,0,0,0,2089490468,,468,9,164
  3,0,0,0,2086208411,,134,0,95
  4,0,0,0,2083920437,,113,0,126
  ...

Download full sample

Fields

Name	Value	Description
row	Number	Row number
period	Number (0‑1)	The time period that this record belongs to. Possible values are as follows: 0: Last 24 hours 1: Last 14 days
sipIndex	Number (0‑2)	The type of entity that is record applies to. Possible values are as follows: 0: An internal phone number 1: An external phone number 2: A SIP response code
type	Number (0‑4)	The type of traffic included in this record. Possible values are as follows: 0: Incoming 1: Outgoing 2: 1st SIP group 3: 2nd SIP group 4: 3rd SIP group
number	String	The phone number if sipIndex is 0 or 1, or the 3-digit SIP response code if sipIndex is 2.
name	String	The display name if sipIndex is 0 or 1, or the full SIP reason phrase if sipIndex is 2.
ans	Number	Total number of answered calls (always 0 if sipIndex is 2).
nAns	Number	Total number of not-answered calls.
avgTalk(s)	Number	Average duration of answered calls in seconds (always 0 if sipIndex is 2).

SIP CDR (sip-cdr-rtp.csv)

This file contains Call Detail Records (CDR) for each call in the last 14 days.

Sample

  row,state,dir,setupTime,talkTime,int#,ext#,name,resCode,ringing(s),disconnect,  local_MOS,  pTime(ms),RTP codec,RTP port,RTP_port error,talk_time(ms),  packet_total,packet_receive,packet_lost(%%),packet_factor,  latency(ms),latency_factor,  jitter(ms),jitter_sample,jitter_factor,  R-factor,  telco_MOS,  pTime(ms),RTP codec,RTP port,RTP_port error,talk_time(ms),  packet_total,packet_receive,packet_lost(%%),packet_factor,  latency(ms),latency_factor,  jitter(ms),jitter_sample,jitter_factor,  R-factor
  0,ans,in,2019-11-14 20:59:24 ,0.47hr,0006*4602,51592129547,xxxxxxxxxxx,200 OK,12.00,telco,  4.32,  20,0,20471,0,1709704,  85483,85112,0.00%,0.00,  40,1.00,  50542,65535,3.00,  89.20,  4.29,  20,0,15186,0,1709704,  85476,85033,0.00%,0.00,  177,2.00,  57496,65535,3.00,  88.20
  1,ans,out,2019-11-14 19:45:25 ,0.49hr,0006*4602,9142256408, ,200 OK,12.00,telco,  4.39,  20,0,20469,0,1788493,  89423,88966,0.00%,0.00,  23,0.00,  30540,65535,1.00,  92.20,  4.34,  20,0,17668,0,1788493,  89424,88925,0.00%,0.00,  10,0.00,  51989,65535,3.00,  90.20
  2,ans,in,2019-11-14 18:41:39 ,0.00hr,0006*4602,52081452829,xxxxxxxxxx,200 OK,14.00,local,  4.31,  20,0,20467,0,7936,  394,387,1.00%,2.50,  43,1.00,  182,381,1.00,  88.70,  4.29,  20,0,12536,0,7936,  392,392,0.00%,0.00,  163,2.00,  341,384,3.00,  88.20
  3,ans,in,2019-11-14 17:57:41 ,0.00hr,0006*4602,56007993232,xxxxxxxxxxx,200 OK,14.00,telco,  4.33,  20,0,20465,0,12110,  603,594,1.00%,2.50,  33,1.00,  113,586,0.00,  89.70,  4.32,  20,0,11044,0,12110,  603,603,0.00%,0.00,  166,2.00,  369,599,2.00,  89.20
  4,ans,in,2019-11-14 15:23:24 ,0.00hr,0006*4602,52088245576,xxxxxxx,200 OK,14.00,telco,  4.26,  20,0,20463,0,4207,  208,202,2.00%,5.00,  37,1.00,  31,200,0.00,  87.20,  4.29,  20,0,10628,0,4207,  209,209,0.00%,0.00,  170,2.00,  160,207,3.00,  88.20
  ...

Download full sample

Fields

Name	Value	Description
Row	Number	Row number
state	String	The conclusion of the call. Possible values are as follows: ans: Answered nans: Not Answered ringing: Call attempt in progress
dir	String	Call direction (incoming or outgoing).
setupTime	Datetime (YYYY-MM-DD HH:mm:ss)	Time of the first INVITE message.
talkTime	Number	Duration of the call in hours.
int#	String	Internal phone number.
ext#	String	External phone number.
name	String	Call display name (if available).
resCode	String	3-digit SIP response code, plus corresponding reason phrase.
ringing(s)	Number	Number of seconds between first INVITE message and call acceptance or rejection.
disconnect	String	Indicates which party disconnected the call, telco or local.
local_MOS	Number	Mean Opinion Score.
pTime(ms)	Number	pTime(ms).
RTP codec	Number	RTP codec.
RTP port	Number	RTP port.
RTP_port error	Number	RTP_port error.
talk_time(ms)	Number	talk_time(ms).
packet_total	Number	packet_total.
packet_receive	Number	packet_receive.
packet_lost(%%)	Number	packet_lost(%%).
packet_factor	Number	packet_factor.
latency(ms)	Number	latency(ms).
latency_factor	Number	latency_factor.
jitter(ms)	Number	jitter(ms).
jitter_sample	Number	jitter_sample.
jitter_factor	Number	jitter_factor.
R-factor	Number	R-factor.

SIP Group Definition (sip-qsMsg.csv)

This file contains the definition of 3 SIP groups. Each group is defined by a single phone number, or a pair of phone numbers grouped together. SIP groups can be defined manually using the t-Console application. If not defined manually, then SIP groups are automatically defined to be the top 3 most active phone numbers over the last 14 days. Traffic analytics for SIP groups are reported in several other CSV files that include a type field.

Sample

  row,name
  0,service 2086207916
  1,support 2089490468 int
  2,support 2089490468 int   sales 2084209377 int
  ...

Download full sample

Fields

Name	Value	Description
Row	Number	Row number
name	String	Group name, following by one or two phone numbers which define the group. Each phone number is followed by int or ext to indicate an internal or external phone number.