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 | ||