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

Receive-side packet processor which calculates 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.
 
 Result.Clear
 Resets the counter values to zero and empties the Result.History. More...
 
 Result.Get
 Returns the current result counters. More...
 
 Result.History.Get
 Returns the current trigger history counters. More...
 

Class overview

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

The basic latency processor extends the basic trigger . It provides additional information like latency and jitter. See Result.Get for more information.

This latency 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 basic latency object can be created via a ByteBlowerPort, using ByteBlowerPort::Rx.Latency.Basic.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 latency [ $port Rx.Latency.Basic.Add ]
3  $latency Filter.Set "udp port 49523"
4  $latency Result.Clear

Definition at line 19245 of file api.tcl.

Method documentation

Rx.Latency.Basic::Counters.Clear

Clears the current counters and resets them to zero.

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

Definition at line 19257 of file api.tcl.

Rx.Latency.Basic::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 times. The default time unit is microseconds. Nanosecond resolution is supported for versions 1.8.22 and beyond (older versions only supported up to microsecond resolution).
ns
nanoseconds
us
microseconds
ms
milliseconds
s
seconds
Default: us
Returns
Returns a list of name-value pairs with various frame counter values:
NrOfFrames
Number of frames received matching the filter.
MinLatency
Minimum latency of the received frames.
AvgLatency
Average latency of the received frames.
MaxLatency
Maximum latency of the received frames.
Jitter
Jitter on the latency of the received frames
Example

This example returns a list of name-value pairs of packet processor counter values.

1 $latency Counters.Get ns

Returns:

NrOfFrames 20 MinLatency 2733 AvgLatency 3023 MaxLatency 3337 Jitter 190 

Definition at line 19275 of file api.tcl.

Rx.Latency.Basic::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 $latency 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 $latency Filter.Get

Returns:

ip src 10.10.10.2 and ip dst 10.10.10.3 and len = 252 

Definition at line 19294 of file api.tcl.

Rx.Latency.Basic::Filter.Set   bpfString  

Sets a BPF filter on a RX object.

Note
Configuring a new filter string does reset the counter values which were triggered by a previous filter string. Also the earlier collected history is invalidated.
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 $latency 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 $latency 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 19315 of file api.tcl.

Rx.Latency.Basic::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 $latency FrameTag.Get

Returns:

<FrameTag.Rx object> 

Definition at line 19343 of file api.tcl.

Rx.Latency.Basic::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  $latency FrameTag.Set $frameTagTx

Definition at line 19368 of file api.tcl.

Rx.Latency.Basic::Result.Clear

Resets the counter values to zero and empties the Result.History.

Example
1 $latency Result.Clear

Definition at line 19383 of file api.tcl.

Rx.Latency.Basic::Result.Get

Returns the current result counters.

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

Returns:

<Rx.Latency.Basic.ResultSnapshot object> 

Definition at line 19395 of file api.tcl.

Rx.Latency.Basic::Result.History.Get

Returns the current trigger history counters.

Returns
The OID of the Rx.Latency.Basic.ResultHistory result object.
Example
1 $latency Result.History.Get

Returns:

<Rx.Latency.Basic.ResultHistory object> 

Definition at line 19407 of file api.tcl.