Reporting (v2)

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.

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}
      ]
    },
    ...
  ]
}

Articles in this section

Comments

Articles in this section

Related articles