Reporting API

Overview

The reporting API is a simple way to access the report data via HTTP or the command line.

Prerequisites

When using the API, pass the following mandatory fields:

authToken
The authentication token from Plixer Scrutinizer that allows access to API.
rm
The runmode for accessing the API. It is specific to each section of the product. report_api will be used for each of the following examples.
action
The list of available actions will change with each request. Below is a list of available actions within the report_api run mode:
Field Description
get the action used to execute flow reports
rpt_json
An array of details to specify most of the options found in the gear menu of the UI, where you can specify report type, date range, etc. See section below for more details on how to fill out the rpt_json field. Every report has an API tab for obtaining JSON for it..
data_requested

It is used to indicate to the API what part of the report we need. Reports return two data sets, one for rendering the graph and the other for rendering the table. Each one is divided into outbound and inbound.

While rpt_json tells Plixer Scrutinizer how to prepare the data (timeframe, filters, aggregation, etc.), data_requested tells Plixer Scrutinizer what data should be returned with the request (inbound, outbound, table, graph, or just a table name).

Available Parameters

rpt_json

The rpt_json field tells Plixer Scrutinizer how to prepare the data: report type, timeframe, filters, aggregation, etc.

JSON object expected (More options available, this is the minimal needed):

{
  "reportTypeLang": "conversations",
  "filters": {
      "sdfDips_0": "in_0A190101_ALL"
  },
  "reportDirections": {
      "selected": "inbound"
  },
  "times": {
      "dateRange": "LastFiveMinutes",
      "clientTimezone": "America/New_York"
  },
  "dataMode": {
      "selected": "saf"
  },
  "rateTotal": {
      "selected": "total"
  },
  "dataGranularity": {
      "selected": "auto"
  },
  "bbp": {
      "selected": "bits"
  }
}

Here is a breakdown of the options for each of the fields from above:

  Description
reportTypeLang a language keycode that represents a report type
  Report Lang Report Description
    conversations Conversations WKP (the default report)
host2host Host to Host
ipGroupGroup IP Group to IP Group
applications Applications Defined
country2country Country to Country
..etc.. Each report has an API tab, with the report lang, in the UI.
filters  
  sdfDips_0 The exporter and interface to use to generate report with. The syntax for this field is in_[IP Hex]_[interface(s)]
  Value Filter Description
    in_0A190101_ALL use all interfaces
in_0A190101_0A190101_1 use interface index 1
reportDirections  
  selected Specify which direction to query. Direction is relative to the interfaces in the filter. If not applicable, just use inbound.
    inbound
outbound
times You can specify just dateRange at a minimal, alternatively use start and end to specify a custom range
  dateRange Indicate timeframe to run report. Valid Options:
    LastFiveMinutes
LastTenMinutes
LastFifteenMinutes
LastTwentyMinutes
LastThirtyMinutes
LastFortyfiveMinutes
LastHour
LastFullHour
LastThreeDays
LastSevenDays
LastThirtyDays
Today
Yesterday
Last24Hours
ThisWeek
LastWeek
ThisMonth
LastMonth
ThisYear
LastYear
Custom
  start Epoch timestamp of the report start (Optional) Specify ‘Custom’ dateRange
  1597974180
  end Epoch timestamp of the report start (Optional) Specify ‘Custom’ dateRange
  1597974480
  clientTimezone Used to display dates local to your timezone
    America/New_York
America/Los_Angelos
..etc..
dataMode The system can save and roll up data in one of two ways. Read more about data aggregation <data_aggregation> to learn more
  selected  
  Value Description
    saf This is the default dataMode type
traditional This is for legacy support
rateTotal specify whether to display data as a rate or as total traffic
  selected  
  Value Description
    rate Display row data as a rate, eg packets/second or bit/second
total Display row data as a total, eg. total traffic seen within timeframe
dataGranularity Data from each exporter is stored and aggregated according to data retention settings. Specify how to retrieve data for report.
  selected  
  Value Description
    auto Let the api choose aggregation
1m Show data from 1 minute granularity
5m Show data from 5 minute granularity
30m Show data from 30 minute granularity
2h Show data from 2 hour granularity
12h Show data from 12 hour granularity
bbp This field determines how to display data
  selected  
  Value Description
    bits display data as bits/second or total bits, depending on rateTotal selection
bytes display data as bytes/second or total bytes, depending on rateTotal selection
percent display data as a percentage, rateTotal selection will not matter
 
       

data_requested

The data_requested field tells Plixer Scrutinizer how to prepare the data for graphs, table pagination, etc.

Important

The direction specified in data_requested needs to match the reportDirections selected value in rpt_json. e.g. (inbound/inbound or outbound/outbound)

JSON object expected (More options available, this is the minimal needed):

{
   "inbound": {
       "graph": "none",
       "table": {
           "query_limit": {
               "offset": 0,
               "max_num_rows": 10
           }
       }
   }
}

Running A Report

The following example is an API call to run a default report, over the last 5 minutes, on all interfaces of a device.

Note

In the example below, you will need to replace {{scrutinizer_ip_address}} with your Plixer Scrutinizer’s IP address, as well as {{authToken}} with an Authentication Token that can be obtained from the UI.

Example API call

curl --location --request POST 'https://{{scrutinizer_ip_address}}/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken={{authToken}}' \
--form 'rm=report_api' \
--form 'action=get' \
--form 'rpt_json=
{
    "reportTypeLang": "conversations",
    "filters": {
        "sdfDips_0": "in_0A190101_ALL"
    },
    "reportDirections": {
        "selected": "inbound"
    },
    "times": {
        "dateRange": "LastFiveMinutes",
        "clientTimezone": "America/New_York"
    },
    "dataMode": {
        "selected": "saf"
    },
    "rateTotal": {
        "selected": "total"
    },
    "dataGranularity": {
        "selected": "auto"
    },
    "bbp": {
        "selected": "bits"
    }

}' \
--form 'data_requested=
{
    "inbound": {
        "graph": "none",
        "table": {
            "query_limit": {
                "offset": 0,
                "max_num_rows": 10
            }
        }
    }
}'

The above API call will get processed by the reporting engine. The server will return a JSON response.

JSON object returned ( Note: Response condensed to show structure ):

{
    "report": {
        "request_id": "0xed184820e4b611eab58f1fc02130f7f9",
        "table": {
            "inbound": {
                "totalRowCount": 1,
                "footer": [],
                "columns": [],
                "rows": []
            }
        },
        "time_details": {},
        "exporter_details": {},
        "graph": {}
    }
}

Here is a breakdown of the most important fields from the ‘report’ field/key from the above response:

Field Description
table The table data is divided into inbound or outbound. For each direction the following are provided:
  columns An array of objects that represent the definition of each column in the table. Most of the data is used to create the html table in the browser
    elementName Name of the element that the data in the column is for
format Details about how the data in the column needs to be formatted
label Label used in the table header
  rows Each collection in the array represents a row and each object in the collection represents a table cell for that row.
    rawValue The unformatted value as it is return from the database
label formatted value including bits bytes or percent
  footer  
    The footer[0] represents the ‘Others’ data for the operations columns (columns which value is the product of an arithmetic operation). That is, the amount for the data not included in the rows.
The footer[1] represents the ‘total’. Total for a column is equal to the sum of the rows for that column plus the ‘Others’ value for that column.
  totalRowCount integer representing the total number of rows available
graph    
    all return all available graph types
pie values used in drawing pie chart of table data
timeseries values used in drawing line graph chart of table data
none Will only return data for pie, as that is the default