All Classes Namespaces Files Functions Pages
Rx.Latency.Distribution Class Reference

Receive-side packet processor which calculates distribution of latency on the incoming frames, matching a filter. More...

Methods

 Counters.Clear
 Clears the current counters and resets them to zero. More...
 
 Counters.Get timeunit
 Returns the current values of the counters. More...
 
 Description.Get
 Returns a textual description of the object.
 
 Filter.Get
 Returns the current installed BPF filter string. More...
 
 Filter.Set bpfString
 Sets a BPF filter on a RX object. More...
 
 FrameTag.Default.Set
 Resets the receive-side frame tag to its server-default settings.
 
 FrameTag.Get
 Returns the FrameTag.Rx object related to this trigger. More...
 
 FrameTag.Set transmittedFrameTag
 Configure the FrameTag.Rx to match the given FrameTag.Tx. More...
 
 Parent.Get
 Returns the parent object.
 
 Range.Get
 Returns the current configured range for the latency distribution. More...
 
 Range.Set
 Configures the range for which the Latency Distribution will measure the latency and create a distribution. More...
 
 Result.Clear
 Resets the counter values to zero. More...
 
 Result.Get
 Returns the current result counters. More...
 

Class overview

Receive-side packet processor which calculates distribution of latency on the incoming frames, matching a filter.

This latency distribution calculation is always active and starts processing frames as soon as it is created. Processing continues until the packet processor is destructed.

The transmit time stamp of a packet is obtained from a time tag in the frame. This tag is configured on the FrameTag.Tx, which can be obtained via Frame::FrameTag.Time.Get.

Note
The initial (empty) filter string accepts all incoming frames. See Filter.Set for filtering information.

A latency distribution object can be created via a ByteBlowerPort, using ByteBlowerPort::Rx.Latency.Distribution.Add

This packet processor processes frames received on the ByteBlower interface where its parent ByteBlowerPort is located.

Example

Receive all frames on "trunk-1-45" of some server, matching UDP source or destination port 49523.

1 set port [ $server Port.Create "trunk-1-45" ]
2  set latencyDist [ $port Rx.Latency.Distribution.Add ]
3  $latencyDist Filter.Set "udp port 49523"
4  $latencyDist Result.Clear

Definition at line 19699 of file api.tcl.

Method documentation

Rx.Latency.Distribution::Counters.Clear

Clears the current counters and resets them to zero.

Deprecated:
since 2.1.0, please use Result.Clear instead.
Example
1 $latencyDist Counters.Clear

Definition at line 19711 of file api.tcl.

Rx.Latency.Distribution::Counters.Get   timeunit  

Returns the current values of the counters.

Deprecated:
since 2.1.0, please use Result.Get instead.
Note
The latency tag format in the transmitted frames define whether an additional sanity check is possible on the (filtered) frames. If the sanity check fails, the latency tag in the frame will not be processed. In this case the number of frames received (by filter) will be bigger than the number of frames that were actually accepted for latency calculation.
Parameters
timeunit(optional) The time unit used to represent latency range. The default time unit is microseconds. Nanosecond resolution is supported for versions 1.8.22 and beyond (older versions only supported microsecond units).
ns
nanoseconds
us
microseconds
ms
milliseconds
s
seconds
Default: us
Returns
Returns a list of calculated latency value buckets and the number of packet in this bucket. The list format is: <range> <number_of_packets> <range> <number_of_packets> ...
Example
1 $latencyDist Counters.Get

Returns:

{[0 - 1000[ us} 0 {[1000 - 2000[ us} 0 {[2000 - 3000[ us} 9 {[3000 - 4000[ us} 11 {[4000 - 5000[ us} 0\ 
  {[5000 - 6000[ us} 0 {[6000 - 7000[ us} 0 {[7000 - 8000[ us} 0 {[8000 - 9000[ us} 0 {[9000 - 10000[ us}\ 
  ...\ 
  {[995000 - 996000[ us} 0 {[996000 - 997000[ us} 0 {[997000 - 998000[ us} 0 {[998000 - 999000[ us} 0 {[999000 - 1000000[ us} 0\ 
  {< 0 us} 0 {> 1000000 us} 0 

Definition at line 19733 of file api.tcl.

Rx.Latency.Distribution::Filter.Get

Returns the current installed BPF filter string.

The filter string can be configured using Filter.Set

Returns
The current BPF filter string
Example

Suppose we configured the trigger with filter string:

1 $latencyDist Filter.Set "ip src [ $ipv4_1 Ip.Get ] and ip dst [ $ipv4_2 Ip.Get ] and len = ${frameSize}"

where $ipv4_1 and $ipv4_2 are Layer3.IPv4 objects and $frameSize is the (layer2) size of the frames (without CRC!). The BPF filter string would then become for example:

1 $latencyDist Filter.Get

Returns:

ip src 10.10.10.2 and ip dst 10.10.10.3 and len = 252 

Definition at line 19752 of file api.tcl.

Rx.Latency.Distribution::Filter.Set   bpfString  

Sets a BPF filter on a RX object.

Note
Configuring a new filter string does not reset the counter values which were triggered by a previous filter string.
Parameters
bpfStringValid BPF filter string. For creating valid BPF filter strings, please have a look at http://www.tcpdump.org/#documentation for more information.
Exceptions
ByteBlower.Rx.*When the {server-side} RX object could not be resolved.
ByteBlower.Rx.Filter.CompilationFailedWhen an invalid BPF filter string is given.
ByteBlower.InvalidFilterWhen an invalid BPF filter string is given.
Example

This will filter only UDP traffic.

1 $latencyDist Filter.Set "udp"

Set the filter on packets that match:

  • source and destination IPv4 address
  • UDP traffic with given destination and source UDP port
  • (layer2) frame length (without CRC!)
1 $latencyDist Filter.Set "ip src [ $ipv4_1 Ip.Get ] and ip dst [ $ipv4_2 Ip.Get ] and udp dst port ${dstUdpPort} and udp src port ${srcUdpPort} and len = ${frameSize}"

Definition at line 19773 of file api.tcl.

Rx.Latency.Distribution::FrameTag.Get

Returns the FrameTag.Rx object related to this trigger.

Each (transmitted) frame can be enabled to have a time tag and/or an sequence tag inserted into the frame. The FrameTag.Rx object on this trigger can be used to define how that transmitted tag is processed.

The FrameTag.Rx object which is returned by this method represents the current configuration of the frame tag processing. This object can be used to configure the processing of the injected frame tag.

For more detailed information about Frame tagging, you can also take a look at ByteBlower API Knowledgebase: Background: Adding FrameTags to your ByteBlower frame - structure and behaviour

Warning
On older ByteBlower servers, this requires a lot of resources, so this option must be used with care.
Since
1.8.18
Returns
This method returns the FrameTag.Rx object for frame tag processing of the (filtered) frames.
Example

In this example, we will retrieve the FrameTag.Rx object for the frame tag:

1 $latencyDist FrameTag.Get

Returns:

<FrameTag.Rx object> 

Definition at line 19801 of file api.tcl.

Rx.Latency.Distribution::FrameTag.Set   transmittedFrameTag  

Configure the FrameTag.Rx to match the given FrameTag.Tx.

This method takes a FrameTag.Tx and applies its metrics and format configuration on this trigger's FrameTag.Rx.

Note
The transmitted frame tag type (sequence number, time stamp, ...) must match the receiver frame tag type that is used for this trigger.

The transmitted frame tag (sequence number, time stamp) can be obtained from the Frame (Frame::FrameTag.Sequence.Get, resp. Frame::FrameTag.Time.Get)

Parameters
transmittedFrameTagThe FrameTag.Tx to obtain the metrics and format configuration from.
Since
1.8.18
Exceptions
ByteBlower.Server.NotSupportedUnsupported Server Capability: 'Manage TX/RX Frame Tag placement': When a transmitted frame tag with unsupported metrics and/or format is given.
<tcl_error>"FrameTag is of incorrect Type": When a transmitted frame tag of invalid type is given (sequence vs. time)
Example

This example applies the transmitted time tag configuration on the receiver's time tag:

1 set frameTagTx [ $frame FrameTag.Time.Get ]
2  $latencyDist FrameTag.Set $frameTagTx

Definition at line 19826 of file api.tcl.

Rx.Latency.Distribution::Range.Get

Returns the current configured range for the latency distribution.

Example

Suppose the range has been configured for [0, 750ms[

1 $latencyDist Range.Get

Returns:

0 750000000 

Definition at line 19841 of file api.tcl.

Rx.Latency.Distribution::Range.Set

Configures the range for which the Latency Distribution will measure the latency and create a distribution.

Default value: [0, 1s[
Note
Nanosecond resolution is supported for versions 1.8.24 and beyond (older versions only supported up to microsecond resolution).
Bug:
An incorrect exception is thrown when an invalid range is given.
Exceptions
<tcl_error>"LAT001": When trying to configure an invalid range.
Example

This will set the range from 0 to 5seconds.

1 $latencyDist Range.Set 0 5s

Definition at line 19859 of file api.tcl.

Rx.Latency.Distribution::Result.Clear

Resets the counter values to zero.

Example
1 $latencyDist Result.Clear

Definition at line 19869 of file api.tcl.

Rx.Latency.Distribution::Result.Get

Returns the current result counters.

Returns
The OID of the Rx.Latency.Distribution.ResultSnapshot result object
Example
1 $latencyDist Result.Get

Returns:

<Rx.Latency.Distribution.ResultSnapshot object> 

Definition at line 19881 of file api.tcl.