ros2_perf

A small ROS 2 throughput / latency benchmarking tool. The command-line interface intentionally mimics ddsperf from Eclipse Cyclone DDS so people familiar with ddsperf can use this tool with little or no relearning.

Layout

Standard ROS 2 workspace layout:

ros2_perf/                          # workspace root (this git repo)
├── src/
│   └── ros2_perf/                  # ament package
│       ├── CMakeLists.txt
│       ├── package.xml
│       ├── msg/Uks.msg
│       ├── include/ros2_perf/      # mode.hpp, mode_utils.hpp, …
│       ├── src/
│       │   ├── main.cpp
│       │   ├── args.cpp
│       │   ├── stats.cpp
│       │   ├── report.cpp
│       │   └── mode/
│       │       ├── pub_mode.cpp
│       │       ├── sub_mode.cpp
│       │       ├── ping_mode.cpp
│       │       └── pong_mode.cpp
│       └── test/
├── build/                         (generated by colcon)
├── install/                       (generated by colcon)
├── log/                           (generated by colcon)
├── LICENSE
└── CONTRIBUTING.md

Build

Source a ROS 2 underlay first:

source /opt/ros/jazzy/setup.bash
# or: source ~/ros2_jazzy/install/setup.bash

cd ~/ros2_ws/ros2_perf
colcon build --packages-select ros2_perf --merge-install
source install/setup.bash

Run:

ros2 run ros2_perf ros2_perf help
# or: ./install/ros2_perf/lib/ros2_perf/ros2_perf help

(--merge-install puts all packages under a single install/ prefix; omit it if you prefer colcon's per-package layout under install/ros2_perf/.)

Configure options

Pass CMake arguments through colcon:

colcon build --packages-select ros2_perf --cmake-args -DBUILD_TESTING=ON
# or:
colcon build --symlink-install --mixin release compile-commands build-testing-on

Option	Default	Meaning
BUILD_TESTING	OFF	Build test_args / test_stats / test_report(gtest)

Unit tests:

colcon build --symlink-install --mixin release compile-commands build-testing-on
source install/setup.bash
cd build/ros2_perf && ctest --output-on-failure

Usage

ros2_perf MODE [OPTIONS]...

OPTIONS (may appear before, after, or in between MODE keywords):

Option	Meaning
-h, --help, help	print usage and exit 0
--version	print version and exit 0
-t NAME	data topic name (default /ros2_perf; ping/pong derive _ping / _pong)
-u	best-effort instead of reliable
-k all|N	keep-all or keep-last-N history (default all)
-D DUR	run at most DUR seconds (default: forever)
-L	enable intra-process communication (disabled for waitset triggers)
-l	sub reports one-way latency
-1	sub/ping/pong print stats every second even with no traffic
-i ID	set ROS_DOMAIN_ID before rclcpp::init (0–232)
-E E	executor: single / multi / static (default multi)

MODEs:

MODE	Sub-args
pub	[R[Hz|kHz]|inf] [size S] [burst N]
sub	[listener|waitset]
ping	[R[Hz]] [size S] [listener|waitset]
pong	[listener|waitset]
sanity	shortcut for ping 1Hz
help	print usage and exit 0

Anything after --ros-args is passed through to rclcpp::init unchanged.

Suffixes: Hz, kHz, inf; size B / k / M / kB / KiB / MB / MiB (all multi-byte suffixes are 1024-based, matching ddsperf).

Examples

ros2 run ros2_perf ros2_perf pub size 1k 1kHz
ros2 run ros2_perf ros2_perf sub

ros2 run ros2_perf ros2_perf ping size 1k 1kHz
ros2 run ros2_perf ros2_perf pong

Output

Banner:

==== ros2_perf 0.0.1 ====
modes: sub  topic: /ros2_perf  qos: reliable/keep_all/0  ipc: off  executor: multi  rmw: rmw_fastrtps_cpp  domain: -1  pid: 1150664

Per-second lines:

[t=1.000] sub: 9050a9facb5b77840000000000000000  1024 B/pkt  996 pkt/s  8.2 Mb/s  8.2 Mb/s avg  lost/s 0 (0.00%)  lost total 0 (0.00%)  pkts total 996
[t=1.000] sub: 9050a9facb5b77840000000000000000  oneway(us) cnt 996  min 18.0  mean 21.7  50% 20.0  90% 23.6  95% 31.8  99% 41.5  99.9% 55.2  max 309.5  stddev 10.1
[t=2.000] sub: 9050a9facb5b77840000000000000000  1024 B/pkt  1000 pkt/s  8.2 Mb/s  8.2 Mb/s avg  lost/s 0 (0.00%)  lost total 0 (0.00%)  pkts total 1996
[t=2.000] sub: 9050a9facb5b77840000000000000000  oneway(us) cnt 1000  min 17.7  mean 21.1  50% 19.9  90% 22.6  95% 30.6  99% 41.4  99.9% 46.4  max 58.4  stddev 4.2
[t=3.000] sub: 9050a9facb5b77840000000000000000  1024 B/pkt  1000 pkt/s  8.2 Mb/s  8.2 Mb/s avg  lost/s 0 (0.00%)  lost total 0 (0.00%)  pkts total 2996
[t=3.000] sub: 9050a9facb5b77840000000000000000  oneway(us) cnt 1000  min 18.2  mean 20.5  50% 19.8  90% 21.3  95% 27.3  99% 33.1  99.9% 41.9  max 43.7  stddev 2.9
[t=4.000] sub: 9050a9facb5b77840000000000000000  1024 B/pkt  1000 pkt/s  8.2 Mb/s  8.2 Mb/s avg  lost/s 0 (0.00%)  lost total 0 (0.00%)  pkts total 3996
[t=4.000] sub: 9050a9facb5b77840000000000000000  oneway(us) cnt 1000  min 17.8  mean 21.1  50% 19.9  90% 22.9  95% 31.6  99% 37.3  99.9% 48.7  max 49.4  stddev 3.9
[t=5.000] sub: 9050a9facb5b77840000000000000000  1024 B/pkt  1000 pkt/s  8.2 Mb/s  8.2 Mb/s avg  lost/s 0 (0.00%)  lost total 0 (0.00%)  pkts total 4996
[t=5.000] sub: 9050a9facb5b77840000000000000000  oneway(us) cnt 1000  min 18.5  mean 23.6  50% 20.5  90% 32.1  95% 33.2  99% 41.9  99.9% 56.8  max 267.0  stddev 9.5

Peer presence (pub / sub / ping / pong; ROS graph endpoint discovery):

sub [/ros2_perf]: 9050a9facb5b77840000000000000000 matched
sub [/ros2_perf]: 9050a9facb5b77840000000000000000 gone

matched when a remote endpoint appears on the topic in the graph (may occur before the first message). gone when it disappears from the graph, or on clean shutdown via flush_gone.

## Switching RMW

```bash
RMW_IMPLEMENTATION=rmw_cyclonedds_cpp ros2 run ros2_perf ros2_perf -D 5 sub

The active RMW is shown in the startup banner.

Future work

• Add support for zero-copy pub loan.