4.3. NetProfiler and Reporting
The NetProfiler package offers a set of interfaces to control and work with
a SteelCentral NetProfiler appliance.
-
class steelscript.netprofiler.core.netprofiler.NetProfiler(host, port=None, auth=None)
The NetProfiler class is the main interface to interact with a
NetProfiler appliance. Primarily this provides an interface to reporting.
-
__init__(host, port=None, auth=None)
Establishes a connection to a NetProfiler appliance.
Parameters: |
- host (str) – name or IP address of the NetProfiler to
connect to
- port (int) – TCP port on which the NetProfiler appliance
listens. If this parameter is not specified, the function will try
to automatically determine the port.
- auth – defines the authentication method and credentials
to use to access the NetProfiler. It should be an instance of
UserAuth or
OAuth
- force_version (str) – API version to use when communicating.
if unspecified, this will use the latest version supported by both
this implementation and the NetProfiler appliance.
|
See the base Service class
for more information about additional functionality supported.
-
get_columns(columns, groupby=None)
Return valid Column objects for list of columns
Parameters: |
- columns (list) – list of strings and/or Column objects
- groupby (str) – will optionally ensure that the selected columns
are valid for the given groupby
|
-
get_columns_by_ids(ids)
Return Column objects that have ids in list of strings ids.
Parameters: | ids (list) – list of integer ids |
-
logout()
Issue logout command to netprofiler machine.
-
search_columns(realms=None, centricities=None, groupbys=None)
Identify columns given one or more values for the triplet.
Parameters: |
- realms (list) – list of strings
- centricities (list) – list of strings
- groupbys (list) – list of strings
|
Results will be based on the following relationship table:
realm |
centricity |
groupby |
traffic_summary |
hos,int |
all (except thu) |
traffic_overall_time_series |
hos,int |
tim |
traffic_flow_list |
hos |
hos |
identity_list |
hos |
thu |
-
version
Returns the software version of the NetProfiler
4.3.2. Report Objects
-
class steelscript.netprofiler.core.report.Report(profiler)
Base class for all NetProfiler reports.
This class is normally not used directly, but instead via subclasses
SingleQueryReport and MultiQueryReport.
-
__init__(profiler)
Initialize a report object.
A report object is bound to an instance of a NetProfiler at creation.
-
delete()
Issue a call to NetProfiler delete this report.
-
get_data(index=0, columns=None)
Retrieve data for this report.
If columns is specified, restrict the data to the list of
requested columns.
-
get_iterdata(index=0, columns=None)
Retrieve iterator for the result data.
If columns is specified, restrict the legend to the list of
requested columns.
-
get_legend(index=0, columns=None)
Return legend describing the columns in this report.
If columns is specified, restrict the legend to the list of
requested columns.
-
get_query_by_index(index=0)
Returns the query_id by specifying the index, defaults to 0.
-
get_totals(index=0, columns=None)
Retrieve the totals for this report.
If columns is specified, restrict the totals to the list of
requested columns.
-
run(template_id, timefilter=None, resolution='auto', query=None, trafficexpr=None, data_filter=None, sync=True)
Create the report and begin running the report on NetProfiler.
If the sync option is True, periodically poll until the report is
complete, otherwise return immediately.
Parameters: |
- template_id (int) – numeric id of the template to use for the report
- timefilter – range of time to query,
instance of TimeFilter
- resolution (str) – data resolution, such as (1min, 15min, etc.),
defaults to ‘auto’
- query (str) – query object containing criteria
- trafficexpr – instance of TrafficFilter
- data_filter (str) – deprecated filter to run against report data
- sync (bool) – if True, poll for status until the report is complete
|
-
status()
Query for the status of report. If the report has not been run,
this returns None.
The return value is a dict containing:
- status indicating completed when finished
- percent indicating the percentage complete (0-100)
- remaining_seconds is an estimate of the time left until complete
-
wait_for_complete(interval=1, timeout=600)
Periodically checks report status and returns when 100% complete.
-
class steelscript.netprofiler.core.report.SingleQueryReport(profiler)
Bases: steelscript.netprofiler.core.report.Report
Base class for NetProfiler REST API reports.
This class is not normally instantiated directly. See child classes such
as TrafficSummaryReport.
-
__init__(profiler)
-
run(realm, groupby='hos', columns=None, sort_col=None, timefilter=None, trafficexpr=None, host_group_type='ByLocation', resolution='auto', centricity='hos', area=None, data_filter=None, sync=True)
Parameters: |
- realm (str) – type of query, this is automatically set by subclasses
- groupby (str) – sets the way in which data should be grouped
(use netprofiler.groupby.*)
- columns (list) – list of key and value columns to retrieve
(use netprofiler.columns.*)
- sort_col – Column reference to sort by
- timefilter – range of time to query,
instance of TimeFilter
- trafficexpr – instance of TrafficFilter
- host_group_type (str) – sets the host group type to use
when the groupby is related to groups
(such as ‘group’ or ‘peer_group’).
- resolution (str) – data resolution, such as (1min, 15min, etc.),
defaults to ‘auto’
- centricity (‘hos’ or ‘int’) – ‘hos’ for host-based counts,
or ‘int’ for interface based counts, only affects
directional columns
- area (str) – sets the appropriate scope for the report
- data_filter (str) – deprecated filter to run against report data
- sync (bool) – if True, poll for status until the report is complete
|
-
class steelscript.netprofiler.core.report.TrafficSummaryReport(profiler)
Bases: steelscript.netprofiler.core.report.SingleQueryReport
-
__init__(profiler)
Create a traffic summary report. The data is organized by the requested
groupby, and retrieves the selected columns.
-
delete()
Issue a call to NetProfiler delete this report.
-
get_query_by_index(index=0)
Returns the query_id by specifying the index, defaults to 0.
-
get_totals(index=0, columns=None)
Retrieve the totals for this report.
If columns is specified, restrict the totals to the list of
requested columns.
-
run(groupby, columns, sort_col=None, timefilter=None, trafficexpr=None, host_group_type='ByLocation', resolution='auto', centricity='hos', area=None, sync=True)
See SingleQueryReport.run() for a description of the keyword
arguments.
-
status()
Query for the status of report. If the report has not been run,
this returns None.
The return value is a dict containing:
- status indicating completed when finished
- percent indicating the percentage complete (0-100)
- remaining_seconds is an estimate of the time left until complete
-
wait_for_complete(interval=1, timeout=600)
Periodically checks report status and returns when 100% complete.
-
class steelscript.netprofiler.core.report.TrafficOverallTimeSeriesReport(profiler)
Bases: steelscript.netprofiler.core.report.SingleQueryReport
-
__init__(profiler)
Create an overall time series report.
-
delete()
Issue a call to NetProfiler delete this report.
-
get_query_by_index(index=0)
Returns the query_id by specifying the index, defaults to 0.
-
get_totals(index=0, columns=None)
Retrieve the totals for this report.
If columns is specified, restrict the totals to the list of
requested columns.
-
run(columns, timefilter=None, trafficexpr=None, resolution='auto', centricity='hos', area=None, sync=True)
See SingleQueryReport.run() for a description of the keyword
arguments.
Note that sort_col, groupby, and host_group_type are not
applicable to this report type.
-
status()
Query for the status of report. If the report has not been run,
this returns None.
The return value is a dict containing:
- status indicating completed when finished
- percent indicating the percentage complete (0-100)
- remaining_seconds is an estimate of the time left until complete
-
wait_for_complete(interval=1, timeout=600)
Periodically checks report status and returns when 100% complete.
-
class steelscript.netprofiler.core.report.TrafficFlowListReport(profiler)
Bases: steelscript.netprofiler.core.report.SingleQueryReport
-
__init__(profiler)
Create a flow list report.
-
delete()
Issue a call to NetProfiler delete this report.
-
get_query_by_index(index=0)
Returns the query_id by specifying the index, defaults to 0.
-
get_totals(index=0, columns=None)
Retrieve the totals for this report.
If columns is specified, restrict the totals to the list of
requested columns.
-
run(columns, sort_col=None, timefilter=None, trafficexpr=None, sync=True)
See SingleQueryReport.run() for a description of the keyword
arguments.
Note that only columns, `sort_col, timefilter, and trafficexpr
apply to this report type.
-
status()
Query for the status of report. If the report has not been run,
this returns None.
The return value is a dict containing:
- status indicating completed when finished
- percent indicating the percentage complete (0-100)
- remaining_seconds is an estimate of the time left until complete
-
wait_for_complete(interval=1, timeout=600)
Periodically checks report status and returns when 100% complete.
-
class steelscript.netprofiler.core.report.IdentityReport(profiler)
Bases: steelscript.netprofiler.core.report.SingleQueryReport
-
__init__(profiler)
Create a report for Active Directory events.
-
delete()
Issue a call to NetProfiler delete this report.
-
get_query_by_index(index=0)
Returns the query_id by specifying the index, defaults to 0.
-
get_totals(index=0, columns=None)
Retrieve the totals for this report.
If columns is specified, restrict the totals to the list of
requested columns.
-
run(username=None, timefilter=None, trafficexpr=None, sync=True)
Run complete user identity report over the requested timeframe.
username specific id to filter results by
timefilter is the range of time to query, a TimeFilter object
trafficexpr is an optional TrafficFilter object
-
status()
Query for the status of report. If the report has not been run,
this returns None.
The return value is a dict containing:
- status indicating completed when finished
- percent indicating the percentage complete (0-100)
- remaining_seconds is an estimate of the time left until complete
-
wait_for_complete(interval=1, timeout=600)
Periodically checks report status and returns when 100% complete.
-
class steelscript.netprofiler.core.report.WANSummaryReport(profiler)
Tabular or summary WAN Report data.
-
__init__(profiler)
Create a WAN Traffic Summary report
-
delete()
Issue a call to NetProfiler delete this report.
-
get_data(as_list=True, calc_reduction=False, calc_percentage=False)
Retrieve WAN report data.
Parameters: |
- as_list (bool) – return list of lists or pandas DataFrame
- calc_reduction (bool) – include extra column with optimization
reductions
- calc_percentage (bool) – include extra column with optimization
percent reductions
|
-
get_interfaces(device_ip)
Query netprofiler to attempt to automatically determine
LAN and WAN interface ids.
-
get_query_by_index(index=0)
Returns the query_id by specifying the index, defaults to 0.
-
get_totals(index=0, columns=None)
Retrieve the totals for this report.
If columns is specified, restrict the totals to the list of
requested columns.
-
run(lan_interfaces, wan_interfaces, direction, columns=None, timefilter='last 1 h', trafficexpr=None, groupby='ifc', resolution='auto')
Run WAN Report.
Parameters: |
- lan_interfaces – list of full interface name for LAN
interface, e.g. [‘10.99.16.252:1’]
- wan_interfaces – list of full interface name for WAN interface
- direction (‘inbound’ or ‘outbound’) –
- columns – list of columns available in both ‘in’ and ‘out’
versions, for example, [‘avg_bytes’, ‘total_bytes’], instead of
[‘in_avg_bytes’, ‘out_avg_bytes’]
|
-
status()
Query for the status of report. If the report has not been run,
this returns None.
The return value is a dict containing:
- status indicating completed when finished
- percent indicating the percentage complete (0-100)
- remaining_seconds is an estimate of the time left until complete
-
wait_for_complete(interval=1, timeout=600)
Periodically checks report status and returns when 100% complete.
-
class steelscript.netprofiler.core.report.WANTimeSeriesReport(profiler)
-
__init__(profiler)
Create a WAN Time Series report.
-
delete()
Issue a call to NetProfiler delete this report.
-
get_data(as_list=True)
Retrieve WAN report data as list of lists or pandas DataFrame.
If as_list is True, return list of lists, False will return
pandas DataFrame.
-
get_interfaces(device_ip)
Query netprofiler to attempt to automatically determine
LAN and WAN interface ids.
-
get_query_by_index(index=0)
Returns the query_id by specifying the index, defaults to 0.
-
get_totals(index=0, columns=None)
Retrieve the totals for this report.
If columns is specified, restrict the totals to the list of
requested columns.
-
run(lan_interfaces, wan_interfaces, direction, columns=None, timefilter='last 1 h', trafficexpr=None, groupby=None, resolution='auto')
Run WAN Time Series Report
Parameters: |
- lan_interfaces – list of full interface name for LAN
interface, e.g. [‘10.99.16.252:1’]
- wan_interfaces – list of full interface name for WAN interface
- direction (‘inbound’ or ‘outbound’) –
- columns – list of columns available in both in_ and out_
versions, for example, [‘avg_bytes’, ‘total_bytes’], instead of
[‘in_avg_bytes’, ‘out_avg_bytes’]
- groupby (str) – Ignored for this report type, included for
interface compatibility
|
-
status()
Query for the status of report. If the report has not been run,
this returns None.
The return value is a dict containing:
- status indicating completed when finished
- percent indicating the percentage complete (0-100)
- remaining_seconds is an estimate of the time left until complete
-
wait_for_complete(interval=1, timeout=600)
Periodically checks report status and returns when 100% complete.
-
class steelscript.netprofiler.core.report.MultiQueryReport(profiler)
Bases: steelscript.netprofiler.core.report.Report
Used to generate NetProfiler standard template reports.
-
__init__(profiler)
Create a report using standard NetProfiler template ids which will
include multiple queries, one for each widget on a report page.
-
get_data_by_name(query_name)
Return data and legend for query matching query_name.
-
get_query_names()
Return full name of each query in report.
-
run(template_id, timefilter=None, trafficexpr=None, data_filter=None, resolution='auto')
The primary driver of these reports come from the template_id which
defines the query sources. Thus, no query input or
realm/centricity/groupby keywords are necessary.
Parameters: |
- template_id (int) – numeric id of the template to use for the report
- timefilter – range of time to query,
instance of TimeFilter
- trafficexpr – instance of TrafficFilter
- data_filter (str) – deprecated filter to run against report data
- resolution (str) – data resolution, such as (1min, 15min, etc.),
defaults to ‘auto’
|
-
class steelscript.netprofiler.core.filters.TimeFilter(start, end)
-
__init__(start, end)
-
compare_time(t, resolution=60)
Return True if time t falls in between start and end times.
t may be a unix timestamp (float or string) or a datetime.datetime
object
resolution is the number of seconds to use for rounding. Since
NetProfiler stores data in one-minute increments, typically this
should allow reasonable comparisons to report outputs. Passing
zero (0) in here will enforce strict comparisons.
-
classmethod parse_range(s)
Take a range string s and return a TimeFilter object.
-
profiler_minutes(astimestamp=False, aslocal=False)
Provide best guess of whole minutes for current time range.
astimestamp determines whether to return results in Unix
timestamp format or as datetime.datetime objects (defaults
to datetime objects).
aslocal set to True will apply local timezone to datetime
objects (defaults to UTC).
NetProfiler reports out in whole minute increments, and for time
deltas less than one minute (60 seconds) it will use the rounded
minute from the latest timestamp. For time deltas over one
minute, lowest and highest rounded minutes are used, along with
all in between.
-
class steelscript.netprofiler.core.filters.TrafficFilter(filter)
Wrapper class for NetProfiler Traffic expressions.
View more information on Traffic expressions via NetProfiler help.
-
__init__(filter)