4.3. NetProfiler and Reporting

The NetProfiler package offers a set of interfaces to control and work with a SteelCentral NetProfiler appliance.

4.3.1. NetProfiler Objects

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.

4.3.3. SingleQueryReport Objects

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

4.3.3.1. TrafficSummaryReport Objects

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.

4.3.3.2. TrafficOverallTimeSeriesReport Objects

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.

4.3.3.3. TrafficFlowListReport Objects

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.

4.3.3.4. IdentityReport Objects

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.

4.3.3.5. WANSummaryReport Objects

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.

4.3.3.6. WANTimeSeriesReport Objects

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.

4.3.4. MultiQueryReport Objects

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’

4.4. steelscript.netprofiler.core.filters

4.4.1. TimeFilter Objects

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.

4.4.2. TrafficFilter Objects

class steelscript.netprofiler.core.filters.TrafficFilter(filter)

Wrapper class for NetProfiler Traffic expressions.

View more information on Traffic expressions via NetProfiler help.

__init__(filter)