8.3.1.9. Histogram

This module contains the L23 port histogram classes that deal with configuration of data collection and retrieval of samples from a port.

The histogram command names all have the form PD_<xxx> and require both a module index id and a port index id, as well as a sub-index identifying a particular histogram.

A histogram has a number of buckets and counts the packets transmitted or received on a port, possibly limited to those with a particular test payload id. The packet length, inter-frame gap preceding it, or its latency is measured, and the bucket whose range contains this value is incremented.

While a histogram is actively collecting samples its parameters cannot be changed.

class PD_CREATE[source]

Bases: object

Creates a histogram definition with the specified sub-index value.

class SetDataAttr[source]: Bases: RequestBodyStruct

set()[source]: Create a histogram definition with the specified sub-index value.

class PD_DELETE[source]

Bases: object

Delete an existing histogram definition.

class SetDataAttr[source]: Bases: RequestBodyStruct

set()[source]: Delete an existing histogram definition.

class PD_ENABLE[source]

Bases: object

Whether a histogram is currently active on a port. When turned on, all the bucket counts are cleared to zero. Subsequently each packet matching the histogram source criteria is counted into one of the buckets. While a histogram is enabled its parameters cannot be changed.

class GetDataAttr[source]

Bases: ResponseBodyStruct

on_off: coded integer, whether the histogram is enabled.

class SetDataAttr[source]

Bases: RequestBodyStruct

on_off: coded integer, whether the histogram is enabled.

get()[source]

Get whether a histogram is currently active on a port.

Returns:: whether the histogram is enabled
Return type:: OnOff

set(on_off)[source]

Set whether a histogram is currently active on a port.

Parameters:: on_off (OnOff) – whether the histogram is enabled

set_off(): Disable the histogram on the port.

set_on(): Enable the histogram on the port.

class PD_INDICES[source]

Bases: object

Obtain or configure histogram indices for each of N histograms.

class GetDataAttr[source]

Bases: ResponseBodyStruct

histogram_indices: list of integers, histogram indices

class SetDataAttr[source]

Bases: RequestBodyStruct

histogram_indices: list of integers, histogram indices

get()[source]

Get the histogram indices for each of N histograms.

Returns:: the histogram indices for each of N histograms
Return type:: PD_INDICES.GetDataAttr

set(histogram_indices)[source]

Set the histogram indices for each of N histograms.

Parameters:: histogram_indices (List[int]) – histogram indices

class PD_RANGE[source]

Bases: object

The bucket ranges used for classifying the packets counted by a histogram of a port. The packets are either counted by length, measured in bytes, by inter- frame gap to the preceding packet, also measured in bytes, or by latency in transmission measured in nanoseconds. There are a fixed number of buckets, each middle bucket covering a fixed-size range of values which is a power of two. The first and last buckets count all the packets that do not fit within the ranges of the middle buckets. The buckets are placed at a certain offset by specifying the first value that should be counted by the first middle bucket.

class GetDataAttr[source]

Bases: ResponseBodyStruct

bucket_count: integer, the total number of buckets.

start: integer, first value going into the second bucket.

step: integer, the span of each middle bucket: (1) 1,2,4,8,16,32,64,128,256,512 (bytes, non-latency histograms). (2) 16,32,64,128,…,1048576,2097152 (nanoseconds, latency histograms).

class SetDataAttr[source]

Bases: RequestBodyStruct

bucket_count: integer, the total number of buckets.

start: integer, first value going into the second bucket.

step: integer, the span of each middle bucket: (1) 1,2,4,8,16,32,64,128,256,512 (bytes, non-latency histograms). (2) 16,32,64,128,…,1048576,2097152 (nanoseconds, latency histograms).

get()[source]

Get the bucket ranges used for classifying the packets counted by a histogram of a port.

Returns:: first value going into the second bucket, the span of each middle bucket, the total number of buckets
Return type:: PD_RANGE.GetDataAttr

set(start, step, bucket_count)[source]

Set the bucket ranges used for classifying the packets counted by a histogram of a port. The packets are either counted by length, measured in bytes, by inter- frame gap to the preceding packet, also measured in bytes, or by latency in transmission measured in nanoseconds. There are a fixed number of buckets, each middle bucket covering a fixed-size range of values which is a power of two. The first and last buckets count all the packets that do not fit within the ranges of the middle buckets. The buckets are placed at a certain offset by specifying the first value that should be counted by the first middle bucket.

Parameters:

start (int) – first value going into the second bucket
step (int) – the span of each middle bucket: (1) 1,2,4,8,16,32,64,128,256,512 (bytes, non-latency histograms). (2) 16,32,64,128,…,1048576,2097152 (nanoseconds, latency histograms)
bucket_count (int) – the total number of buckets

class PD_SAMPLES[source]

Bases: object

The current set of counts collected by a histogram for a port. There is one value for each bucket, but any trailing zeros are left out. The list is empty if all counts are zero.

class GetDataAttr[source]

Bases: ResponseBodyStruct

packet_counts: list of long integers, the number of packets counted for each bucket.

get()[source]

Get current set of counts collected by a histogram for a port.

Returns:: the number of packets counted for each bucket
Return type:: PD_SAMPLES.GetDataAttr

class PD_SOURCE[source]

Bases: object

The source criteria specifying what is counted, and for which packets, by a histogram of a port.

class GetDataAttr[source]

Bases: ResponseBodyStruct

identity: integer, test payload id or filter id for the wanted packets.

source_type: coded integer, specifying what is counted and for which packets.

which_packets: coded integer, specifying a further detail on which packets to count.

class SetDataAttr[source]

Bases: RequestBodyStruct

identity: integer, test payload id or filter id for the wanted packets.

source_type: coded integer, specifying what is counted and for which packets.

which_packets: coded integer, specifying a further detail on which packets to count.

get()[source]

Get the source criteria specifying what is counted, and for which packets, by a histogram of a port.

Returns:: what is counted and for which packets, a further detail on which packets to count, test payload id or filter id for the wanted packets
Return type:: PD_SOURCE.GetDataAttr

set(source_type, which_packets, identity)[source]

Set the source criteria specifying what is counted, and for which packets, by a histogram of a port.

Parameters:

source_type (SourceType) – what is counted and for which packets
which_packets (PacketDetailSelection) – a further detail on which packets to count
identity (int) – test payload id or filter id for the wanted packets