About | Support | Discussion Forum | Index | Service Status | ros @ Robotics Stack Exchange

Only released in EOL distros:   electric fuerte groovy hydro indigo

Overview

A UDP-based system for measuring network link metrics such as bandwidth, latency and loss. It is highly configurable and versatile provides support for multiple concurrent link tests, one-way or round-trip measurements, constant or adaptive bandwidth rates and more.

MonitorSource and udpmonsink

The basic link measurements are implemented by the class MonitorSource (defined in udpmonclient.py) and the udpmonsink node. MonitorSource sends UDP packets at a specified rate to udpmonsink which timestamps them and echoes them back either via UDP or via ROS topic message.

MonitorSource records packets receive times and sorts them into latency bins based on their travel time. These latency bins can be periodically retrieved and information such as packet loss, average latency and bandwidth can be therefrom determined.

Multiple stream support is built in so multiple MonitorSources on the same ROS node can ping packets off the same udpmonsink.

For a ROS independent setup, udpmonserv can be used instead of udpmoncli. The former is not a ROS node, but rather a standalone UDP server. By default, MonitorSource does not use ROS messages for the return path and no ROS dependency is created on the class.

udpmonsourcenode.py

udpmonsourcenode is a node that implements an action server which receives link testing goals. It instantiates and collects statistics from multiple MonitorSources. Each source (i.e. link test) is independent of all others and can be parametrized differently in terms of bandwidth, latency bin thresholds, update (i.e. stats collection) interval and so on. It sends periodical feedback to the action client.

udpmonsourcenode also implements logic for adaptive bandwidth tests: link tests that strive to saturate a link in terms of bandwidth while maintaining latency and loss within specified thresholds.

Typically there would be one udpmonsourcenode.py node running on every machine in a test setup as each sourcenode supports any number of tests with destination sinks on different machines.

linktest.py

The linktest.py implements the action client for link tests, as well as logging and test control logic via three classes:

• UdpmonsourceHandle: is a handle to a udpmonsourcenode.py (i.e. an action client); typically there would be as many instances as there are udpmonsourcenodes in the test setup. UdpmonsourceHandle also act as link test factories creating Linktest objects.

• LinkTest: an instance of this class corresponds to one link test. Instances are created from the UdpmonsourceHandle class. It receives the periodic link test statistics (measured bandwidth, latency and loss) and it logs these measurements in the MetricLog class.

• MetricLog: records a log of measurement for a variable and calculates aggregated statistics.

ROS API

udpmonsourcenode.py

Implements an action server which receives link testing goals. Tracks multiple concurrently running link tests and reports feedback periodically.

Parameters

LinktestGoal: goal sent via actionlib that configures a link test.

duration (float, default: 0.0 (unlimited))

• Test duration in seconds. 0.0 means unlimited duration.

update_interval (float, default: 0.15 (stats are collected and reported every 150 ms))

• Interval between statistics collection and reporting (in seconds). Also, used an update interval of the adaptive bandwidth algorithm.

bw (float, default: 5000000.0 (the default start bandwidth is 5 Mbit/s))

• TX bandwidth (in bits per seconds). For the adaptive bandwidth algorithm this is the initial bandwidth.

bw_type (char, default: 'c' (constant bandwidth test))

• Bandwidth test type: constant ('c') or adaptive ('a').

latency_threshold (float, default: 0.01 (10ms))

• Latency threshold (in seconds). For the adaptive bandwidth algorithm this is the threshold under which latency must be maintained.

pktloss_threshold (float, default: 0.5 (0.5%))

• Packet loss threshold (percentage). For the adaptive bandwidth algorithm this is the threshold under which packet loss must be maintained.

tos (byte, default: 0x00)

• TOS (type of service) IP packet field. Note that superuser privilege is needed for non-zero values.

pktsize (int, default: 1500)

• UDP packet size in bytes.

ros_returnpath (boolean, default: False (return path is over UDP))

• Whether the return path should be over ROS topics (reliable) instead of the default UDP.

roundtrip (boolean, default: False (one-way measurements))

• Whether the measurements should be round-trip or just one-way (default).

max_return_time (float, default: 0.0)

• For one-way measurements, this specifies the maximum expected return path travel time for a packet. If the maximum total travel time (the highest bin in latencybins, see below) is exceeded due to return path time running over max_return_time, statistics will be incorrect.

rostopic_prefix (string, default: "")

• The ROS return path (i.e. udpmonsink's node udpsink_feedback topic) topic prefix used when namespaces are used because there are multiple udpmonsinks running concurrently.

sink_ip (string, default: "")

• The IP address which the udpmonsink for this test is bound to.

sink_port (int, default: 0)

• The UDP port the udpmonsink is listening on.

latency_bins (float[], default: [.005, .01, .025, .05, .075, .1] (the maximum allowed latency is 100ms))

• An array of floats (seconds) specifying the latency bins used when measuring travel time. The last (and maximum) value is the maximum allowed latency: if travel time is higher than this value, packets will be considered lost.

LinktestFeedback and LinktestResult: link test statistics periodic feedback and final results

latency (float)

• Average latency (in seconds) of restricted packets received in the last update window (or over the whole tests). Restricted packets are those packets whose total travel time is smaller than max_allowed_latency + max_return_time.

loss (float)

• Packet loss over the last update windows, or average over the whole test.

bandwidth (float)

• Received (RX) bandwidth in bps in the last update windows, or average over the whole test, respectively.

latency_histogram (float)

• Histogram of packet latencies. Count of packets that fell into each of the latency bins specified in the link test goal.

udpmonsink

udpmonsink is a lightweight node that echoes back received packets either over UDP or as messages via a ROS topic named udpsink_feedback. It takes a single command-line argument: the UDP port it should listen on.

Command-line tools

udpmoncli.py can also be used stand-alone, independent of ROS with udpmonserv as in the example below:

# rosrun network_monitor_udp udpmonserv 12345

# rosrun network_monitor_udp udpmoncli.py 127.0.0.1 12345 10 1500
  0.501: 100   0   0   /   0   0   0   0 avg:   0.3 ms avgr:   0.3 ms loss:   0.00 %
  1.001: 100   0   0   /   0   0   0   0 avg:   0.3 ms avgr:   0.3 ms loss:   0.00 %
  1.501: 100   0   0   /   0   0   0   0 avg:   0.3 ms avgr:   0.3 ms loss:   0.00 %
  2.001: 100   0   0   /   0   0   0   0 avg:   0.4 ms avgr:   0.4 ms loss:   0.00 %
  2.501: 100   0   0   /   0   0   0   0 avg:   0.4 ms avgr:   0.4 ms loss:   0.00 %
  3.000: 100   0   0   /   0   0   0   0 avg:   0.4 ms avgr:   0.4 ms loss:   0.00 %

Usage example

The following launch file starts a source and a sink node as well as a bandwidth test node:

<launch>
<node name="sink" pkg="network_monitor_udp" type="udpmonsink" args="12345" output="screen"/>
<node name="source" pkg="network_monitor_udp" type="udpmonsourcenode.py" output="screen"/>
<node name="test_node" pkg="network_monitor_udp" type="sample_bwtest.py" required="true" output="screen"/>
</launch> 

The test node starts a link capacity test on the loopback interface and prints the resulting capacity:

import roslib; roslib.load_manifest('network_monitor_udp')
import rospy

from network_monitor_udp.linktest import UdpmonsourceHandle
from network_monitor_udp.linktest import LinkTest
from network_monitor_udp.msg import LinktestGoal

if __name__ == '__main__':
    rospy.init_node('test_node')
        
    source = UdpmonsourceHandle() 
    source.cancel_all_tests()

    try:
        print "Link capacity: %.2fMbit/s"%(source.get_link_capacity(sink_ip="127.0.0.1", sink_port=12345)/1e6)
    finally:
        source.cancel_all_tests()

Here's an example run:

# roslaunch launch_nodes.launch

[...]

core service [/rosout] found
process[sink-1]: started with pid [20043]
process[source-2]: started with pid [20044]
process[test_node-3]: started with pid [20055]
Link capacity: 68.71Mbit/s

More usage examples with more complex configurations can be found in the network_control_tests package.

Tips

• if source/sink nodes are ran on different machines, these should be time synchronized if measurements are made on a single direction (as opposed to round-trip) so that latencies are correct