Overview
Usage
Querying Summary Information
Querying List Information
Querying Timeseries Information
Traffic monitored by the Sinefa system can be retrieved from the API by issuing a GET request to one of the following endpoints.
Summary (total and aggregate) information can be retrieved via the following endpoint.
GET /api/v2/traffic/summary.json
List (tabular) information can be retrieved via the following endpoint.
GET /api/v2/traffic/list.json
Timeseries (chart and graph) information can be retrieved via the following endpoint.
GET /api/v2/traffic/timeseries.json
Usage
The following parameters are passed to these endpoints as a query string. All 3 endpoints above support the following common parameters.
report: (optional) The type of data to return, must be one of "application", "apptag", "host-internal","host-external", "user", "website", "source". Defaults to "source" if not specified.
e.g. &report=application
filter: (optional) The URL encoded query filter as described in the Filtering Sinefa Reports article.
e.g. &application+%3d+HTTP
start_timestamp: The time range start timestamp in milliseconds since epoch.
end_timestamp: The time range end timestamp in milliseconds since epoch.
e.g. &start_timestamp=1365487800000&end_timestamp=1365491400000
period: (optional) The time period to query (only used if start_timestamp and end_timestamp are not present). Valid values are one of "last_60_minutes", "last_3_hours", "last_6_hours", "last_12_hours", "last_24_hours", "last_3_days", "last_7_days", "last_14_days", "last_30_days".
e.g. &period=last_24_hours
Querying Summary Information
Summary information refers to aggregates or totals. An example of a summary query would be "tell me how much YouTube traffic my head office did during the last 24 hours". To query summary information, use the summary endpoint:
GET /api/v2/traffic/summary.json
In addition to the common parameters above, the summary endpoint provides the following additional parameters.
metric: (optional) The metric(s) to return. Must be one (or more) of "data", "packets", "rate", "rtt", "health" or "pps" (multiple values must be comma separated). Defaults to "data,rate" if not specified.
e.g. &metric=data,packets
Return Data
The following JSON structure is returned.
{ in: { <metric_1>: <value>, <metric_n>: <value> }, out: { <metric_1>: <value>, <metric_n>: <value> } }
Examples
Retrieve the total data, rate and packets for YouTube over the last 24 hours.
curl 'https://ui.sinefa.com/api/v2/traffic/summary.json?period=last_24_hours&filter=application+%3d+YouTube&metric=data,rate,packets'
{
"in" : {
"data" : 36063,
"rate" : 240.42,
"packets" : 57
},
"out" : {
"packets" : 84,
"rate" : 48.54,
"data" : 7281
}
}
Querying List Information
List information refers to tabular data. An example of a list query would be "tell me all the internal IPs in my head office that did YouTube traffic during the last 24 hours". To query list information, use the list endpoint:
GET /api/v2/traffic/list.json
In addition to the common parameters above, the list endpoint provides the following additional parameters.
metric: (optional) The metric(s) to return. Must be one (or more) of "data", "packets", "rate", "rtt", "health" or "pps" (multiple values must be comma separated). Defaults to "data,rate" if not specified.
e.g. &metric=data,packets
sortby: (optional) Items are sorted by the first metric specified above. This parameter specifies which value to use for that metric. Must be one of "total", "in" or "out". Defaults to "total" if not specified.
e.g. &sortby=in
Return Data
The following JSON structure is returned.
{
items: [
{
name: <name of app, host, website, etc> in: { <metric_1>: <value>, <metric_n>: <value> }, out: { <metric_1>: <value>, <metric_n>: <value> }
},
...
] }
Examples
Retrieve the total data, rate and packets for all the internal IPs that did YouTube over the last 24 hours.
curl 'https://ui.sinefa.com/api/v2/traffic/summary.json?report=host-internal&period=last_24_hours&filter=application+%3d+YouTube&metric=data,rate,packets'
{
items: [
{
name: "192.168.1.211",
"in" : {
"data" : 36063,
"rate" : 240.42,
"packets" : 57
},
"out" : {
"packets" : 84,
"rate" : 48.54,
"data" : 7281
}
},
...
]
}
Querying Timeseries Information
Timeseries information refers to chart or graph data. An example of a timeseries query would be "tell me the utilization of YouTube traffic at my head office during the last 24 hours". To query timeseries information, use the timeseries endpoint:
GET /api/v2/traffic/timeseries.json
In addition to the common parameters above, the timeseries endpoint provides the following additional parameters.
metric: (optional) The metric to return. Must be one of "data", "packets", "rate", "rtt", "health" or "pps". Defaults to "rate" if not specified.
e.g. &metric=packets
sortby: (optional) This parameter specifies which value to use for the sorting of the metric specified above. Must be one of "total", "in" or "out". Defaults to "total" if not specified.
e.g. &sortby=in
Return Data
The following JSON structure is returned. Up to 5 timeseries are returned per query, if the results included more than 5 items, a 6th item is added called "other" that contains the aggregate of the remaining items.
{
items: [
{
name: <name of app, host, website, etc> in: [
{ timestamp: <timestamp of sample, in sec since epoch>, <metric>: <value>
},
...
] out: [
{ timestamp: <timestamp of sample, in sec since epoch>, <metric_n>: <value> },
...
]
},
...
] }
Examples
Retrieve the data transferred as a timeseries for the top internal IPs that did YouTube over the last 24 hours.
curl 'https://ui.sinefa.com/api/v2/traffic/timeseries.json?report=host-internal&period=last_24_hours&filter=application+%3d+YouTube&metric=data'
{
"items": [
{
"name":"192.168.1.22",
"in": [
{"timestamp":"1458104400","data":13993},{"timestamp":"1458104700","data":0},{"timestamp":"1458107700","data":21383},{"timestamp":"1458178800","data":20837}
],
"out": [
{"timestamp":"1458104400","data":2659},{"timestamp":"1458104700","data":80},{"timestamp":"1458107700","data":2922},{"timestamp":"1458178800","data":3110}
]
},
{
"name":"192.168.1.13",
"in": [
{"timestamp":"1458177600","data":20658},{"timestamp":"1458179700","data":9339},{"timestamp":"1458188100","data":6306}
],
"out":[{"timestamp":"1458177600","data":3191},{"timestamp":"1458179700","data":2034},{"timestamp":"1458188100","data":1543}
]
},
...
]
}
See Also
API Overview
Reporting: Quality
Events: Active
How to generate date specific reports through API queries
Comments
0 comments
Please sign in to leave a comment.