Documentation for PythonAPI
17.2.0py1

packetlogic2.pldb.statistics

This module contains functionality for reading statistics data from the PacketLogic system.

Do NOT import this module directly. The PLConnection object should be used, e.g:

>>> import packetlogic2
>>> pl = packetlogic2.connect("192.168.1.25", "admin", "pldemo00")
>>> s = pl.Statistics()

Classes defined here:

  • Statistics - The Statistics resource is used for for reading statistics

Priority

Undocumented!
Inherits from: int
Methods:
bit_length()
int.bit_length() -> int
conjugate()
Returns self, the complex conjugate of any int
Properties:
expandable
priority

bit_length()

int.bit_length() -> int

Number of bits necessary to represent self in binary. >>> bin(37) '0b100101' >>> (37).bit_length() 6

conjugate()

Returns self, the complex conjugate of any int.

expandable

Undocumented!

priority

Undocumented!

Statistics

The Statistics resource is used for for reading statistics.

Inherits from: Resource
Methods:
Ungrouped data_invalidate(self, start, end, path, pathtype=0, deleteroot=True)
Invalidate all Statistics data for requested path and all its children
list of str date_list(self)
List the statistics database of available statistics data
dict of dict fields_list(self)
List available fields
dict {list} of dict graph(self, start, end, path, numvals=24, pathtype=0, mode=1, replymask=0, usage_rate=False)
Retrieve graph data between two dates
graph_invalidate(self, start, end, path, pathtype=0, deleteroot=True)
Invalidate only graph data for requested path and all its children
list of dict list(self, start, end, path, pathtype=0, replymask=0)
List stats nodes between two dates
list of dict list_duration(self, start, end, path, pathtype=0, thresholds=None)
List nodes with calculated duration they satisfy thresholds
Max == 0, list of dict list_search(self, start, end, path, searchstr, pathtype=0, max=0, recursiondepth=0, replymask=0)
List top N values matching a "search string" between two dates
Max == 0, list of dict list_subscribers(self, start, end, path, pathtype=0, max=0, replymask=0)
List top N subscribers between two dates (N=0, returns all subscribers)
list of dict names_list(self, start, end, path, pathtype=0, matchstr='')
List the names of stats nodes between two dates
boolean path_is_expandable(self, start, end, path, pathtype=0)
Verify that a path is expandable
query(self, query)
Returns a dictionary with columns and row data:
query_callback(self, query, row_desc_cb, row_data_cb, notice_cb=None)
Issue the query using callbacks
dict subitem_count(self, start, end, path, pathtype=0)
Count number of subitems for requested path between the two dates
list of dict subitem_count_list(self, start, end, path, pathtype=0)
Subitem count for the list of stats nodes between two dates
int subscriber_count(self, start, end, path, pathtype=0)
Count number of subscribers for requested path between the two dates
list of dict subscriber_count_graph(self, start, end, path, pathtype=0, numvals=24)
Retrieve subscriber count for each requested interval between two dates
list of dict subscriber_count_list(self, start, end, path, pathtype=0)
List subscriber count for each node for requested path between the two
dict of list of dict toplist(self, start, end, path, max, pathtype=0, replymask=0, offset=0)
List top N nodes between two dates
dict transfer_get(self, start, end, path, pathtype=0, replymask=0)
Retrieves total transfer for path between two dates
Inherited from Resource close(self)
Immediately disconnects the resource
commit(self, message='PythonAPI commit')
Store the current transaction to the database
ping(self, string='')
Send a command to server to test if it is up
tuple of (str, int) protocol(self, protocol, strict=False)
Translate protocol name OR number to tuple with name AND number
dict of str:int and int:str protocols_dict(self)
Returns a dictionary with name:nr and nr:name items for IP protocols
rollback(self)
Abort the current transaction and discard the data
services_cmd(self, services=[], props=[])
Send services to pldbd
list of str services_list(self)
List all services
list of str services_prop_list(self)
List all properties
wait_for_commit(self, pinginterval=60)
Wait for new data to be committed on resource
list of str xfb_flags_list(self)
List all XFB (Transfer Behaviour) flags, that can be used in FlagObjects
Class Variables:
VALUETYPE_DUMMY Root values (/ or Statistics Objects)
VALUETYPE_ROOT Alias for VALUETYPE_DUMMY
VALUETYPE_AGGREGATION Aggregation value
VALUETYPE_TRAFFICSTATS Traffic stats value
VALUETYPE_ZONESTATS Zone Stats value
VALUETYPE_CHANNELSTATS Channel Stats value
VALUETYPE_NETOBJECT Netobject
VALUETYPE_HOST Host
VALUETYPE_LOCALVHOST Local Vhost
VALUETYPE_REMOTEVHOST Remote Vhost
VALUETYPE_SERVOBJECT ServiceObject
VALUETYPE_SERVICE Service
VALUETYPE_CLIENTASPATH Client ASpath
VALUETYPE_SERVERASPATH Server ASpath
VALUETYPE_INTASPATH Internal ASpath
VALUETYPE_EXTASPATH External ASpath
VALUETYPE_VLAN Vlan
VALUETYPE_INVLAN Inbound VLAN
VALUETYPE_OUTVLAN Outbound VLAN
VALUETYPE_INDSCP Inbound DSCP
VALUETYPE_OUTDSCP Outbound DSCP
VALUETYPE_INCHAN Inbound Channel
VALUETYPE_OUTCHAN Outbound Channel
VALUETYPE_INMPLS Inbound MPLS
VALUETYPE_OUTMPLS Outbound MPLS
VALUETYPE_XFBFLAG XFB Flags
VALUETYPE_CONTENTLOGIC ContentLogic
VALUETYPE_IPPROTOCOL IP Protocol
VALUETYPE_REMOTEHOST Remote Host
VALUETYPE_LINK Link
VALUETYPE_PROPERTY Property
VALUETYPE_BASESERVICE Base Service
VALUETYPE_ORIGINAS Origin AS
VALUETYPE_INTBGPCOMM Internal BGP Community
VALUETYPE_EXTBGPCOMM External BGP Community
VALUETYPE_TTL Outbound TTL
VALUETYPE_INVLAN_PRIO Inbound Vlan Priority
VALUETYPE_OUTVLAN_PRIO Outbound Vlan Priority
VALUETYPE_SYSTEM System
VALUETYPE_DEVICE_ID Device ID
VALUETYPE_CHANNELSTATS_ROOT Channel Stats root
VALUETYPE_CHANNELSTATS_CHANNEL Channel Stats channel
VALUETYPE_NAT_ROOT NAT Stats Root
VALUETYPE_NAT_HOST NAT Stats Host
VALUETYPE_NAT_ROOT NAT Stats Pool
VALUETYPE_SHAPINGOBJECTSTATS_ROOT Shapingobject Stats root @cvar VALUETYPE_SHAPINGOBJECTSTATS_SYSTEM Shapingobject Stats system
TOTALFIELD_BYTES_IN Incoming Bytes count
TOTALFIELD_BYTES_OUT Outgoing Bytes count
TOTALFIELD_CONNS Connections
TOTALFIELD_UCONNS Unestablished Connections
TOTALFIELD_CONNS_IN Incoming Connections
TOTALFIELD_CONNS_OUT Outgoing Connections
TOTALFIELD_UCONNS_IN Incoming unestablished Connections
TOTALFIELD_UCONNS_OUT Outgoing unestablished Connections
TOTALFIELD_QUALITY_IN Incoming Quality of Experience
TOTALFIELD_QUALITY_OUT Outgoing Quality of Experience
TOTALFIELD_BYTES_TOTAL Total bytes
TOTALFIELD_CURCONNS_IN Incoming concurrent connections (Peak)
TOTALFIELD_CURCONNS_OUT Incoming concurrent connections (Peak)
TOTALFIELD_PKTDROPS_IN Incoming Shaping dropped packets
TOTALFIELD_PKTDROPS_OUT Outgoing Shaping dropped packets
TOTALFIELD_AVG_LATENCY_IN Incoming Avg Latency
TOTALFIELD_AVG_LATENCY_OUT Outgoing Avg Latency
TOTALFIELD_SUBITEMS Sub-Item Count
TOTALFIELD_QUALITY_IN_INT Incoming Quality of Experience (Internal)
TOTALFIELD_QUALITY_OUT_INT Outgoing Quality of Experience (Internal)
TOTALFIELD_QUALITY_IN_EXT Incoming Quality of Experience (External)
TOTALFIELD_QUALITY_OUT_EXT Outgoing Quality of Experience (External)
TOTALFIELD_QUALITY_PKTS_IN Incoming Quality Packets
TOTALFIELD_QUALITY_PKTS_OUT Outgoing Quality Packets
TOTALFIELD_RTT_IN Internal Avg Handshake RTT
TOTALFIELD_RTT_OUT External Avg Handshake RTT
TOTALFIELD_PACKETS_IN Incoming Packets
TOTALFIELD_PACKETS_OUT Outgoing Packets
TOTALFIELD_SHAPING_BYTEDROPS_IN Incoming Shaping bytes dropped
TOTALFIELD_SHAPING_BYTEDROPS_OUT Outgoing Shaping bytes dropped
TOTALFIELD_QUALITY_DROPS_IN Incoming dropped packets
TOTALFIELD_QUALITY_DROPS_OUT Outgoing dropped packets
TOTALFIELD_QUALITY_RETRANSMISSIONS_IN Incoming retransmission packets
TOTALFIELD_QUALITY_RETRANSMISSIONS_OUT Incoming retransmission packets
GRAPHFIELD_BPS_IN Incoming bytes/bps
GRAPHFIELD_BPS_OUT Outgoing bytes/bps
GRAPHFIELD_CPS Connections (per sec)
GRAPHFIELD_UCPS Unestablished Connections (per sec)
GRAPHFIELD_CPS_IN Incoming Connections (per sec)
GRAPHFIELD_CPS_OUT Outgoing Connections (per sec)
GRAPHFIELD_UCPS_IN Unestablished Incoming Connections (per sec)
GRAPHFIELD_UCPS_OUT Unestablished Outgoing Connections (per sec)
GRAPHFIELD_CURCONNS_IN Incoming concurrent connections
GRAPHFIELD_CURCONNS_OUT Outgoing concurrent connections
GRAPHFIELD_QUALITY_IN Incoming Quality of Experience
GRAPHFIELD_QUALITY_OUT Outgoing Quality of Experience
GRAPHFIELD_SUBITEMS Sub-Item Count
GRAPHFIELD_BPS_TOTAL Total BPS
GRAPHFIELD_PKTDROPS_IN Incoming Shaping Dropped Packets
GRAPHFIELD_PKTDROPS_OUT Outgoing Shaping Dropped Packets
GRAPHFIELD_AVG_LATENCY_IN Incoming Avg Latency
GRAPHFIELD_AVG_LATENCY_OUT Outgoing Avg Latency
GRAPHFIELD_QUALITY_IN_INT Incoming Quality of Experience (Internal)
GRAPHFIELD_QUALITY_OUT_INT Outgoing Quality of Experience (Internal)
GRAPHFIELD_QUALITY_IN_EXT Incoming Quality of Experience (External)
GRAPHFIELD_QUALITY_OUT_EXT Outgoing Quality of Experience (External)
GRAPHFIELD_QUALITY_PKTS_IN Incoming Quality Packets
GRAPHFIELD_QUALITY_PKTS_OUT Outgoing Quality Packets
GRAPHFIELD_LINK_UTILIZATION_IN Incoming Link Utlization
GRAPHFIELD_LINK_UTILIZATION_OUT Outgoing Link Utlization
GRAPHFIELD_RTT_IN Internal Avg Handshake RTT
GRAPHFIELD_RTT_OUT External Avg Handshake RTT
GRAPHFIELD_PACKETS_IN Incoming Packets
GRAPHFIELD_PACKETS_OUT Outgoing Packets
GRAPHFIELD_SHAPING_BYTEDROPS_IN Incoming Shaping bytes dropped
GRAPHFIELD_SHAPING_BYTEDROPS_OUT Outgoing Shaping bytes dropped
GRAPHFIELD_QUALITY_DROPS_IN Incoming dropped packets
GRAPHFIELD_QUALITY_DROPS_OUT Outgoing dropped packets
GRAPHFIELD_QUALITY_RETRANSMISSIONS_IN Incoming retransmission packets
GRAPHFIELD_QUALITY_RETRANSMISSIONS_OUT Incoming retransmission packets
TOTALFIELD_CHANNEL_RX_PACKETS RX packets
TOTALFIELD_CHANNEL_TX_PACKETS TX packets
TOTALFIELD_CHANNEL_RX_SPEED RX speed
TOTALFIELD_CHANNEL_TX_SPEED TX speed
TOTALFIELD_CHANNEL_RX_ERRORS RX errors
TOTALFIELD_CHANNEL_TX_ERRORS TX errors
TOTALFIELD_CHANNEL_RX_DROPS RX drops
TOTALFIELD_CHANNEL_TX_DROPS TX drops
GRAPHFIELD_CHANNEL_RX_PACKETS RX packets
GRAPHFIELD_CHANNEL_TX_PACKETS TX packets
GRAPHFIELD_CHANNEL_RX_SPEED RX speed
GRAPHFIELD_CHANNEL_TX_SPEED TX speed
GRAPHFIELD_CHANNEL_RX_ERRORS RX errors
GRAPHFIELD_CHANNEL_TX_ERRORS TX errors
GRAPHFIELD_CHANNEL_RX_DROPS RX drops
GRAPHFIELD_CHANNEL_TX_DROPS TX drops
SHAPINGOBJECT_FIELDS_COPIES Copies
SHAPINGOBJECT_FIELDS_CONNECTIONS Connections
SHAPINGOBJECT_FIELDS_BYTES_IN Bytes In
SHAPINGOBJECT_FIELDS_CONGESTED_BYTES_IN Congested Bytes In
SHAPINGOBJECT_FIELDS_PACKETS_IN Packets In
SHAPINGOBJECT_FIELDS_CONGESTED_PACKETS_IN Congested Packets In
SHAPINGOBJECT_FIELDS_DROPS_IN Dropped Packets In
SHAPINGOBJECT_FIELDS_AVG_LATENCY_IN Average Latency In
SHAPINGOBJECT_FIELDS_MAX_LATENCY_IN Max Latency In
SHAPINGOBJECT_FIELDS_AVG_QUEUE_IN Average Queue In
SHAPINGOBJECT_FIELDS_MAX_QUEUE_IN Max Queue In
SHAPINGOBJECT_FIELDS_BYTES_OUT Bytes Out
SHAPINGOBJECT_FIELDS_CONGESTED_BYTES_OUT Congested Bytes Out
SHAPINGOBJECT_FIELDS_PACKETS_OUT Packets Out
SHAPINGOBJECT_FIELDS_CONGESTED_PACKETS_OUT Congested Packets Out
SHAPINGOBJECT_FIELDS_DROPS_OUT Dropped Packets Out
SHAPINGOBJECT_FIELDS_AVG_LATENCY_OUT Average Latency Out
SHAPINGOBJECT_FIELDS_MAX_LATENCY_OUT Max Latency Out
SHAPINGOBJECT_FIELDS_AVG_QUEUE_OUT Average Queue Out
SHAPINGOBJECT_FIELDS_MAX_QUEUE_OUT Max Queue Out
GRAPH_MODE_SIZE Graph result as absolute count
GRAPH_MODE_SPEED Graph result as rate.
FLAG_VALID Value is valid.
FLAG_EXPANDABLE Value has values stored underneath.
FLAG_REMOTEPLDB Unused
FLAG_GRAPHS Value has graph data.
FLAG_PEAKS Value has peak analysis data.
FLAG_ISPEAK Value is a peak.
FLAG_SYMLINK Value is a symbolic link.
FLAG_REMOTELINK Value is a remote link.
FLAG_IS_SUBSCRIBER Value is a subscriber.
FLAG_HAS_SUBSCRIBERS Value has subscriber values stored underneath.
Properties:
commitid The CommitID associated with this session
numtype Set the type to use for numeric values in the result of statistics queries

close(self)

Immediately disconnects the resource.

After this method has been called this object becomes useless.

It may be used to force a disconnect when the garbage collector can't be trusted to do a timely disconnect.

commit(self, message='PythonAPI commit')

Store the current transaction to the database.

When you do this PacketLogic will reload the ruleset. This will take a lot of CPU resources from the system, try to do this in batches.

Observe that if you don't commit the changes you've made, no other resource (including the client) will see your changes.

Parameters:
  • message (str) - Message recorded in the commit log. Ignored in v12.1 and earlier.
  • message parameter is ignored in v12.1 firmware and earlier.

data_invalidate(self, start, end, path, pathtype=0, deleteroot=True)

Invalidate all Statistics data for requested path and all its children

Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - The statistics path to list e.g. /NetObjects
  • pathtype (int) - Value path type.
  • deleteroot (boolean) - Invalidate data for requested path itself.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this method is called without firmware support.
  • This method requires firmware v13.1 or newer

date_list(self)

List the statistics database of available statistics data.

>>> x.date_list()
['2005-12-01', '2005-12-02', '2005-12-03', '2005-12-04', '2005-12-05', '2005-12-06', '2005-12-07', '2005-12-08', '2005-12-09']
Returns:
  • a sorted list with dates that have statistics data
  • list of str

fields_list(self)

List available fields.

>>> s.fields_list()
{'graphs': [{'desc': 'Incoming bps', 'id': 1, 'type': 1},
            {'desc': 'Outgoing bps', 'id': 2, 'type': 1},
            {'desc': 'CPS', 'id': 4, 'type': 2},
            {'desc': 'Unestablished CPS', 'id': 8, 'type': 2},
            {'desc': 'Incoming CPS', 'id': 16, 'type': 2},
            {'desc': 'Outgoing CPS', 'id': 32, 'type': 2},
            {'desc': 'Unestablished Incoming CPS', 'id': 64, 'type': 2},
            {'desc': 'Unestablished Outgoing CPS', 'id': 128, 'type': 2},
            {'desc': 'Incoming concurrrent connections', 'id': 256, 'type': 2},
            {'desc': 'Outgoing concurrent connections', 'id': 512, 'type': 2},
            {'desc': 'Incoming Quality of Experience', 'id': 1024, 'type': 3},
            {'desc': 'Outgoing Quality of Experience', 'id': 2048, 'type': 3}],
 'totals': [{'desc': 'Incoming Bytes', 'id': 1, 'type': 1},
            {'desc': 'Outgoing Bytes', 'id': 2, 'type': 1},
            {'desc': 'Connections', 'id': 4, 'type': 2},
            {'desc': 'Unestablished Connections', 'id': 8, 'type': 2},
            {'desc': 'Incoming Connections', 'id': 16, 'type': 2},
            {'desc': 'Outgoing Connections', 'id': 32, 'type': 2},
            {'desc': 'Incoming Unestablished Connections', 'id': 64, 'type': 2},
            {'desc': 'Outgoing Unestablished Connections', 'id': 128, 'type': 2},
            {'desc': 'Incoming Quality of Experience', 'id': 256, 'type': 3},
            {'desc': 'Outgoing Quality of Experience', 'id': 512, 'type': 3}]}
Returns:
  • Dict with 'graphs' and 'totals' sub-dicts. The sub-dicts contain the keys 'desc', 'id' and 'type'. Type corresponds to the pathtype used in list/graph calls.
  • dict of dict

graph(self, start, end, path, numvals=24, pathtype=0, mode=1, replymask=0, usage_rate=False)

Retrieve graph data between two dates.

>>> s.graph("2009-01-05", "2008-01-05", "/Host per services", 24, 0, s.GRAPH_MODE_SIZE)
[{'bytes out': 528960416.0, 'connections': 7485.5, 'bytes in': 95168704.0},
 {'bytes out': 503229952.0, 'connections': 7073.0, 'bytes in': 136215120.0},
 {'bytes out': 561612864.0, 'connections': 7457.75, 'bytes in': 165719856.0},
 {'bytes out': 574073536.0, 'connections': 7316.66650390625, 'bytes in': 125461376.0}, 
 {'bytes out': 575875264.0, 'connections': 7071.0, 'bytes in': 142020688.0}, 
 {'bytes out': 533374208.0, 'connections': 7379.75, 'bytes in': 128362920.0}, 
 {'bytes out': 542574656.0, 'connections': 7120.75, 'bytes in': 145863184.0}, 
 {'bytes out': 627854016.0, 'connections': 7328.91650390625, 'bytes in': 124391448.0},
 {'bytes out': 356714592.0, 'connections': 8949.1669921875, 'bytes in': 111401304.0}, 
 {'bytes out': 276146240.0, 'connections': 9937.1669921875, 'bytes in': 121161912.0}, 
 {'bytes out': 271035360.0, 'connections': 10208.8330078125, 'bytes in': 105619560.0}, 
 {'bytes out': 282889088.0, 'connections': 9836.9169921875, 'bytes in': 105585656.0}, 
 {'bytes out': 257417728.0, 'connections': 9915.75, 'bytes in': 118984736.0},
 {'bytes out': 291532384.0, 'connections': 10910.6669921875, 'bytes in': 198847856.0}, 
 {'bytes out': 281107264.0, 'connections': 10963.0830078125, 'bytes in': 96303560.0}, 
 {'bytes out': 261479232.0, 'connections': 10322.6669921875, 'bytes in': 106611800.0}, 
 {'bytes out': 365030240.0, 'connections': 10602.9169921875, 'bytes in': 233681280.0}, 
 {'bytes out': 514466784.0, 'connections': 10718.75, 'bytes in': 129939368.0},
 {'bytes out': 394594048.0, 'connections': 10602.5, 'bytes in': 128155672.0},
 {'bytes out': 1116160000.0, 'connections': 11515.25, 'bytes in': 149660416.0},
 {'bytes out': 423695584.0, 'connections': 10865.25, 'bytes in': 121420984.0},
 {'bytes out': 592000384.0, 'connections': 10532.0, 'bytes in': 228060944.0},
 {'bytes out': 623388928.0, 'connections': 9260.9169921875, 'bytes in': 198206720.0}, 
 {'bytes out': 323936608.0, 'connections': 8981.25, 'bytes in': 117023752.0}]
Returns:
  • Dictionaries with data.
  • dict {list} of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • end (str or datetime.date) - End date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • path (str) - The statistics path to list e.g. /NetObjects
  • numvals (int) - The number of data points to retrieve. The specified time interval is divided into this number of segments and the average for each segment is reported. In firmware versions 13.1 and newer this value can be set to 0 to retrieve all data points that have been stored.
  • pathtype (int) - Value path type.
  • mode (int) - throughput rate (GRAPH_MODE_SPEED) or actual byte/connection count (GRAPH_MODE_SIZE).
  • replymask (int) - If replymask is non-zero only data for the fields in the mask will be retured. (requires firmwares v14.0 or newer).
  • usage_rate (boolean) - If usage_rate is set then graph rates are calculated based on micro usage bitmask. (requires firmwares v14.1 or newer).
Exceptions raised:
  • PLDBUnsupportedInFirmware - If pathtype/mode/replymask/usage_rate arguments are used without firmware support.
  • pathtype parameter requires v12.0 firmware or newer.
  • mode parameter requires v12.0 firmware or newer.
  • replymask parameter requires v14.0 firmware or newer.
  • usage_rate parameter requires v14.1 firmware or newer.

graph_invalidate(self, start, end, path, pathtype=0, deleteroot=True)

Invalidate only graph data for requested path and all its children

Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - The statistics path to list e.g. /NetObjects
  • pathtype (int) - Value path type.
  • deleteroot (boolean) - Invalidate graph data for requested path itself.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this method is called without firmware support.
  • This method requires firmware v13.1 or newer

list(self, start, end, path, pathtype=0, replymask=0)

List stats nodes between two dates

>>> s.list("2005-12-01", "2005-12-02", "/")
[{'name': 'HostperNO', 
        'values': {'bytes out': 4900070621184.0,
                'connections': 351976704.0, 
                'outbound Quality of Experience': 99.520118713378906, 
                'inbound Quality of Experience': 99.921859741210938, 
                'bytes in': 21536893304832.0}, 
        'flags': 3,'type': 0}, 
{'name': 'Top Sites', 
                'values': {'bytes out': 4900070621184.0, 
                        'connections':351976704.0, 
                        'bytes in':21536893304832.0},
                'flags': 3, 'type': 0}, 
{'name': 'StatsByClass', 
                'values':{'bytes out': 4888053415936.0,
                        'bytes in': 21408400801792.0},
                'flags': 3, 'type': 0}]
Returns:
  • A dictionary for each stats node inside a list.
  • list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • end (str or datetime.date) - End date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • path (str) - The statistics path to list e.g. /
  • pathtype (int) - Value path type. For use in firmwares v12.0 and newer.
  • replymask (int) - If replymask is non-zero only data for the fields in the mask will be retured. (requires firmwares v14.0 or newer).
Exceptions raised:
  • PLDBUnsupportedInFirmware - If pathtype argument is used withoutfirmware support.
  • pathtype parameter requires v12.0 firmware or newer.
  • replymask parameter requires v14.0 firmware or newer.

list_duration(self, start, end, path, pathtype=0, thresholds=None)

List nodes with calculated duration they satisfy thresholds.

>>> s.list_duration("2010-09-08", "2010-09-08", "/All Host?/",thresholds=[(s.GRAPHFIELD_BPS_IN, 1e6,-1)])
[{'duration': 36900L, 'flags': 11, 'name': '10.93.192.16', 'type': 514},
 {'duration': 52500L, 'flags': 11, 'name': '10.93.192.17', 'type': 514},
 {'duration': 300L, 'flags': 11, 'name': '10.93.192.25', 'type': 514},
 {'duration': 49200L, 'flags': 11, 'name': '10.93.192.39', 'type': 514},
 {'duration': 600L, 'flags': 11, 'name': '10.91.91.7', 'type': 514},
 {'duration': 3900L, 'flags': 11, 'name': '10.92.97.2', 'type': 514},
 {'duration': 300L, 'flags': 11, 'name': '10.92.97.5', 'type': 514},
 {'duration': 300L, 'flags': 11, 'name': '10.92.97.10', 'type': 514},
 {'duration': 1800L, 'flags': 11, 'name': '10.92.97.18', 'type': 514},
 {'duration': 7500L, 'flags': 11, 'name': '10.92.97.25', 'type': 514},
 {'duration': 3600L, 'flags': 11, 'name': '10.92.97.26', 'type': 514},
 {'duration': 300L, 'flags': 11, 'name': '10.92.97.28', 'type': 514},
 {'duration': 2400L, 'flags': 11, 'name': '10.91.91.12', 'type': 514},
 {'duration': 3600L, 'flags': 11, 'name': '10.91.91.40', 'type': 514},
 {'duration': 1800L, 'flags': 11, 'name': '10.91.91.41', 'type': 514},
 {'duration': 69000L, 'flags': 11, 'name': '10.92.102.104', 'type': 514}]
Returns:
  • A dictionary for each stats node inside a list.
  • list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - The statistics path to list e.g. /NetObjects
  • pathtype (int) - Value path type.
  • thresholds (list of tuple) - List of tuples specifying thresholds. Each tuple is in the form (field, lower_limit, upper_limit), e.g: (s.GRAPHFIELD_BPS_TOTAL, 1e6, -1)
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this function is called without firmware support.
  • This function requires firmware v12.4 or newer

list_search(self, start, end, path, searchstr, pathtype=0, max=0, recursiondepth=0, replymask=0)

List top N values matching a "search string" between two dates. N = 0, will return all the matching values.

>>> res=s.list_search ("2013-10-02", "2013-10-02", "/Applications", "Sub115",)
>>> for node in res:
...     print node
...
{'values': {'bytes out': 30924881920.0, 'bytes in': 6812166656.0}, 'type': 518, 'name': '/Web Browsing?ServiceObject/HTTP?ServiceObject/Sub115?NetObject'}
{'values': {'bytes out': 10508003328.0, 'bytes in': 2729902848.0}, 'type': 518, 'name': '/Messaging and Collaboration?ServiceObject/E-mail and Calendaring?ServiceObject/SMTP-TLS?ServiceObject/Sub115?NetObject'}
{'values': {'bytes out': 2935312384.0, 'bytes in': 2098169216.0}, 'type': 518, 'name': '/Web Browsing?ServiceObject/HTTP download?ServiceObject/AN-115?NetObject'}
Returns:
  • If max=0, returns the list of items each stored as a Dict. If max is non-zero, Dict with the top list for each field stored or requested. Each list of is a list of dictonaries for each node.
  • Max == 0, list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • end (str or datetime.date) - End date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • path (str) - The statistics path to list e.g. /NetObjects
  • searchstr (str) - The search string to match on.
  • pathtype (int) - Value path type. For use in firmwares v12.0 and newer.
  • max (int) - Maximum number of nodes to output. If this is zero, all nodes will be returned.
  • recursiondepth (int) - Max depth of Statistics tree to search.
  • replymask (int) - If replymask is non-zero only data for the fields in the mask will be retured. (requires firmwares v14.0 or newer).
Exceptions raised:
  • PLDBUnsupportedInFirmware - If pathtype argument is used withoutfirmware support.
  • This method requires firmware v15.0 or newer.

list_subscribers(self, start, end, path, pathtype=0, max=0, replymask=0)

List top N subscribers between two dates (N=0, returns all subscribers)

This function exists to limit the amount of data sent between the server and the client.It returns any node which is in the top N list for each of the fields being stored.

>>> res=s.list_subscribers("2013-09-14", "2013-09-14", "/Applications?Statistics Object")
>>> for node in res:
...     print node
...
{'values': {'bytes out': 30924881920.0, 'bytes in': 6812166656.0}, 'name': 'Sub113'}
{'values': {'bytes out': 10508003328.0, 'bytes in': 2729902848.0},  'name': 'Sub5'}
{'values': {'bytes out': 2935312384.0, 'bytes in': 2098169216.0},  'name': 'Sub49'}
{'values': {'bytes out': 577248896.0, 'bytes in': 1004788544.0},  'name': 'Sub362'}
{'values': {'bytes out': 7716958720.0, 'bytes in': 923890496.0},  'name': 'Sub74'}
Returns:
  • If max=0, returns the list of items each stored as a Dict. If max is non-zero, Dict with the top list for each field stored or requested. Each list of is a list of dictonaries for each node.
  • Max == 0, list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • end (str or datetime.date) - End date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • path (str) - The statistics path to list e.g. /NetObjects
  • pathtype (int) - Value path type. For use in firmwares v12.0 and newer.
  • max (int) - Maximum number of nodes to output. If this is zero, all nodes will be returned.
  • replymask (int) - If replymask is non-zero only data for the fields in the mask will be retured. (requires firmwares v14.0 or newer).
Exceptions raised:
  • PLDBUnsupportedInFirmware - If pathtype argument is used withoutfirmware support.
  • pathtype parameter requires v12.0 firmware or newer.
  • replymask parameter requires v14.0 firmware or newer.
  • This method requires firmware v15.0.2 or newer

names_list(self, start, end, path, pathtype=0, matchstr='')

List the names of stats nodes between two dates

Returns:
  • A dictionary for each stats node inside a list.
  • list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - Match string
  • pathtype (int) - Value path type.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this method is called without firmware support.
  • This method requires firmware v14.0.3 or newer

path_is_expandable(self, start, end, path, pathtype=0)

Verify that a path is expandable.

Returns:
  • True if path is expandable.
  • boolean
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • end (str or datetime.date) - End date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • path (str) - The statistics path to list e.g. /NetObjects
  • pathtype (int) - Value path type.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If pathtype argument is used without firmware support.
  • pathtype parameter requires v12.0 firmware or newer.

ping(self, string='')

Send a command to server to test if it is up.

protocol(self, protocol, strict=False)

Translate protocol name OR number to tuple with name AND number. Can be used to e.g translate numerical protocol in connlog.search() result to protocol name.

An unknown protocol will be translated to e.g '#7' or -1, unless strict is set to True, in which case ValueError is raised for unknown protocols.

Returns:
  • Tuple with name and nr of specified protocol.
  • tuple of (str, int)
Parameters:
  • protocol (int, str or a ProtocolObject Item) - Name or number of an IP protocol
  • strict (bool) - If True, ValueError is raised for an unknown protocol, if False (default), an unknown protocol translates to number -1 or name '#7' (where 7 is the supplied unknown protocol number).

protocols_dict(self)

Returns a dictionary with name:nr and nr:name items for IP protocols. Can be used to e.g translate numerical protocol in connlog.search() result to protocol name.

Returns:
  • Dict with name:nr and nr:name items for IP protocols.
  • dict of str:int and int:str

query(self, query)

Returns a dictionary with columns and row data:

{"columns": ["name", "bytes_in", "bytes_out"],
 "rows": [("461233124", 1231515, 1231451),
          ("469878922", 9879872, 3874872),
          ("469879872", 8927342, 8723423)],
 "notices": ["some message", "other message"]}

rollback(self)

Abort the current transaction and discard the data.

This will also automatically happen if your connection drops or that you exit the program without commit.

Exceptions raised:
  • resource.PLDBError - If the rollback command failed.

services_cmd(self, services=[], props=[])

Send services to pldbd

Sets stringtable for services and properties. Do NOT use this unless you know exactly what you are doing.

Parameters:
  • services (list of str) - List of services
  • props (list of str) - List of service properties

services_list(self)

List all services

Returns:
  • List of services
  • list of str

services_prop_list(self)

List all properties.

Returns:
  • List of service properties
  • list of str

subitem_count(self, start, end, path, pathtype=0)

Count number of subitems for requested path between the two dates

Returns:
  • Dictionary of various subtypes with their count.
  • dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - The statistics path to list e.g. /
  • pathtype (int) - Value path type.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this method is called without firmware support.
  • This method requires firmware v13.1 or newer

subitem_count_list(self, start, end, path, pathtype=0)

Subitem count for the list of stats nodes between two dates

Returns:
  • A dictionary for each stats node inside a list.
  • list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - The statistics path to list e.g. /
  • pathtype (int) - Value path type.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this method is called without firmware support.
  • This method requires firmware v13.1 or newer

subscriber_count(self, start, end, path, pathtype=0)

Count number of subscribers for requested path between the two dates

Returns:
  • Integer count of subscribers.
  • int
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - The statistics path to list e.g. /
  • pathtype (int) - Value path type.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this function is called without firmware support.
  • This function requires firmware v12.4 or newer

subscriber_count_graph(self, start, end, path, pathtype=0, numvals=24)

Retrieve subscriber count for each requested interval between two dates.

Returns:
  • A dictionary for each stats node inside a list.
  • list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - The statistics path to list e.g. /NetObjects
  • pathtype (int) - Value path type.
  • numvals (int) - The number of data points to retrieve. The specified time interval is divided into this number of segments and the average for each segment is reported. In firmware versions 13.1 and newer this value can be set to 0 to retrieve all data points that have been stored.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this method is called without firmware support.
  • This function requires firmware v12.4 or newer

subscriber_count_list(self, start, end, path, pathtype=0)

List subscriber count for each node for requested path between the two dates

Returns:
  • A dictionary for each stats node inside a list.
  • list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD
  • end (str or datetime.date) - End date in the format YYYY-MM-DD
  • path (str) - The statistics path to list e.g. /
  • pathtype (int) - Value path type.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If this function is called without firmware support.
  • This function requires firmware v12.4 or newer

toplist(self, start, end, path, max, pathtype=0, replymask=0, offset=0)

List top N nodes between two dates

This function exists to limit the amount of data sent between the server and the client.It returns any node which is in the top N list for each of the fields being stored.

Also if the requested Statistics node contains sub-nodes of more than one type then a Top N list would be sent for each type for each field.

>>> res=s.toplist("2009-01-14", "2009-01-14", "/v11 stats", 5, s.VALUETYPE_ROOT)
>>> for node in res["Toplist, bytes in"]:
...     if node['type'] == s.VALUETYPE_SERVICE:
...             print node
... 
{'values': {'bytes out': 30924881920.0, 'bytes in': 6812166656.0}, 'type': 518, 'name': 'BitTorrent transfer'}
{'values': {'bytes out': 10508003328.0, 'bytes in': 2729902848.0}, 'type': 518, 'name': 'BitTorrent encrypted transfer'}
{'values': {'bytes out': 2935312384.0, 'bytes in': 2098169216.0}, 'type': 518, 'name': 'HTTP'}
{'values': {'bytes out': 577248896.0, 'bytes in': 1004788544.0}, 'type': 518, 'name': 'SMTP'}
{'values': {'bytes out': 7716958720.0, 'bytes in': 923890496.0}, 'type': 518, 'name': 'CIFS'}
Returns:
  • Dict with the top list for each field stored ('In Bytes', 'Out Bytes', 'connections', 'Unest. Connections', 'In Connections', 'Out Connections', 'In Quality of Experience' 'Out Quality of Experience'. Each list of is a list of dictonaries for each node.
  • dict of list of dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • end (str or datetime.date) - End date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • path (str) - The statistics path to list e.g. /NetObjects
  • max (int) - Maximum number of nodes to output. If this is zero, all nodes will be returned.
  • replymask (int) - If replymask is non-zero only data for the fields in the mask will be retured. (requires firmwares v14.0 or newer).
  • pathtype (int) - Value path type. For use in firmwares v12.0 and newer.
  • offset (int) - Offset top list.
Exceptions raised:
  • PLDBUnsupportedInFirmware - If pathtype argument is used withoutfirmware support.
  • pathtype parameter requires v12.0 firmware or newer.
  • replymask parameter requires v14.0 firmware or newer.
  • offset parameter requires v15.1 firmware or newer.

transfer_get(self, start, end, path, pathtype=0, replymask=0)

Retrieves total transfer for path between two dates.

>>> r.transfer_get("2006-01-20", "2006-01-21", "/NetObjects")
{'priority': 129, 'out': 1458559580273L, 'name': '/NetObjects', 'in': 1632574443658L}
Returns:
  • Dictionary containing transfer information.
  • dict
Parameters:
  • start (str or datetime.date) - Start date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • end (str or datetime.date) - End date in the format YYYY-MM-DD or YYYY-MM-DD HH:MM:SS
  • path (str) - The statistics path to list e.g. /NetObjects
  • pathtype (int) - Value path type.
  • replymask (int) - If replymask is non-zero only data for the fields in the mask will be retured. (requires firmwares v14.0 or newer).
Exceptions raised:
  • RuntimeError - "Could not retrieve data for path": If statistic path could not be read.
  • PLDBUnsupportedInFirmware - If pathtype argument is used without firmware support.
  • pathtype parameter requires v12.0 firmware or newer.
  • replymask parameter requires v14.0 firmware or newer.

wait_for_commit(self, pinginterval=60)

Wait for new data to be committed on resource.

This method returns as soon as the server signals that another client has committed new data to the resource. It also periodically tests the connection to the server. If connection is broken (or any other error happens) an exception is raised.

Parameters:
  • pinginterval (int) - Interval used to check if connection still is alive.

xfb_flags_list(self)

List all XFB (Transfer Behaviour) flags, that can be used in FlagObjects.

Returns:
  • List of XFB flags
  • list of str

commitid

The CommitID associated with this session. (14.0 or newer only)

numtype

Set the type to use for numeric values in the result of statistics queries.

Defaults to 'float', but as of firmware version 13.1 the data is stored with higher precision which may be lost when converting to a float. To get the increased precision in python this property can be set to int (or decimal.Decimal, but that is discouraged as that can easily create a huge amount of Decimal objects which consume much more memory than simple ints or floats).

>>> s.list("2012-03-01", "2012-03-01", "/Applications?Statistics Object/Procera Categories?ServiceObject/")
[{'flags': 523,
  'name': 'File Sharing',
  'subitemcounts': {'ServiceObject': 1.0},
  'type': 517,
  'values': {'bytes in': 75138613803.0,
             'bytes out': 45238584181.0,
             'bytes total': 120377197984.0}},
 {'flags': 523,
  'name': 'Streaming Media',
  'subitemcounts': {'ServiceObject': 3.0},
  'type': 517,
  'values': {'bytes in': 24489327889.0,
             'bytes out': 600116961.0,
             'bytes total': 25089444850.0}}]
>>> s.numtype=int
>>> s.list("2012-03-01", "2012-03-01", "/Applications?Statistics Object/Procera Categories?ServiceObject/")[2]
{'flags': 523,
 'name': 'File Sharing',
 'subitemcounts': {'ServiceObject': 1},
 'type': 517,
 'values': {'bytes in': 75138613803L,
            'bytes out': 45238584181L,
            'bytes total': 120377197984L}},
 {'flags': 523,
  'name': 'Streaming Media',
  'subitemcounts': {'ServiceObject': 3},
  'type': 517,
  'values': {'bytes in': 24489327889L,
             'bytes out': 600116961,
             'bytes total': 25089444850L}}]