Reporting¶

The following fields are required for all IP group management API requests:

authToken - Authentication token generated by Plixer Scrutinizer to allow API access
rm - report_api (runmode corresponding to the function set being accessed)
action - get (runs the report defined in the request)
rpt_json - JSON object defining the parameters of the report to be run
data_requested - Specifies the elements of the report to be included in the response

Report parameters

Each report API request must specify the parameters for the report using the following elements of the rpt_json object:

Object Element/Field	Report Parameter	Available Options	Example
`reportTypeLang`	Report type	`conversations`: Conversations WKP `host2host`: Host to host `ipGroupGroup`: IP group to IP group `applications`: Applications defined `country2country`: Country to country	"reportTypeLang": "conversations"
`filters`	Exporter and interface filter	`in_<EXPORTER_IP_HEX>_ALL`: Includes all interfaces on the specified exporter `in_<EXPORTER_IP_HEX>_<HEX_INTERFACE_N>`: Includes interface index `N`	"filters": { "sdfDips_0": "in_0A190101_ALL" }
`reportDirections`	Traffic directionality (relative to interfaces included)	`inbound` or `outbound`	"reportDirections": { "selected": "inbound" }
`times`	Report time range/window and time zone to display dates in (use `scrut_util --show tzlist` for a list of valid timezones)	`LastFiveMinutes` `LastTenMinutes` `LastFifteenMinutes` `LastTwentyMinutes` `LastThirtyMinutes` `LastFortyFiveMinutes` `LastHour` `LastFUllHour` `LastThreeDays` `LastSevenDays` `LastThirtyDays` `Today` `Yesterday` `Last24Hours` `ThisWeek` `LastWeek` `ThisMonth` `LastMOnth` `ThisYear` `LastYear` `Custom` (requires additional `start` and `end` fields to specify)	"times": { "dateRange": "LastFiveMinutes" "clientTimezone": "America/New York" }
`dataMode`	Aggregation method to apply to collected data	`saf` (default) `traditional` (used for legacy support)	"dataMode": { "selected": "saf" }
`rateTotal`	Selects between rate (packets/s, bits/s, etc.) or total traffic in the report output	`rate` or `total`	"rateTotal": { "selected": "total" }
`dataGranularity`	Source data granularity	`auto` (API selects an appropriate source data bucket) `1m` `5m` `30m` `2h` `12h`	"dataGranularity": { "selected": "auto" }
`bbp`	Selects the measurement units to use in the report output data	`bits` `bytes` `percent` (`rateTotal` provided is ignored)	"bbp": { "selected": "bits" }

Response data

The data_requested field specifies how to format the graph and table of the report output.

JSON object example:

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

Note

The directionality specified in the data_requested object must match the reportDirections field.

Request example¶

The following API call runs a default report against all interfaces of the specified device for the last 5 minutes:

curl --location  --insecure --request POST 'https://<SCRUTINIZER_ADDRESS>/fcgi/scrut_fcgi.fcgi' \
--header 'Content-Type: application/json' \
--form 'authToken=<AUTH_TOKEN>' \
--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"
    },
    "reportDirections": {
    {
        "type": "ip",
        "address": "10.30.10.1"
    }
}' \
--form 'data_requested'=
{
    "inbound": {
        "graph": "none",
        "table": {
            "query_limit": {
                "offset": 0,
                "max_num_rows": 10
            }
        }
    }
}'

Returned JSON object¶

The following condensed response shows the typical structure of the object returned for a report API request:

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

Field details:

`table` (will include separate data for inbound and outbound if applicable)	`columns`	`elementName`: Name of the data element in the column `format`: Formatting details for data in the column `label`: Table header label
	`rows`	`rawValue`: Unformatted value (as returned from the database) `label`: Formatted value including bits, bytes, or percent
	`footer`	`[0]`: Represents the Others data for a calculated column, which is the sum of the data in all rows not included in the table `[1]`: Represents Total for a calculated column, which is the sum of the data in all included rows plus the Others value for the same column
	`totalRowCount`	Integer specifying the total number of rows available
`graph`	`all`	Includes data for all graph types
	`pie`	Values for graphing table data as a pie chart
	`timeseries`	Values for graphing table data as a line graph
	`none`	Includes only default graph (pie) data