ros2_tracing

Tracing tools for ROS 2.

Overview

ros2_tracing provides tracing instrumentation for the core ROS 2 packages. It also provides tools to configure tracing through a launch action and a ros2 CLI command.

ros2_tracing currently only supports the LTTng tracer. Consequently, it currently only supports Linux.

Note: make sure to use the right branch, depending on the ROS 2 distro: use rolling for Rolling, galactic for Galactic, etc.

Publications & presentations

Read the ros2_tracing paper! If you use or refer to ros2_tracing, please cite:

• C. Bédard, I. Lütkebohle, and M. Dagenais, “ros2_tracing: Multipurpose Low-Overhead Framework for Real-Time Tracing of ROS 2,” IEEE Robotics and Automation Letters, vol. 7, no. 3, pp. 6511–6518, 2022.

Also, check out the ROS World 2021 presentation titled “Tracing ROS 2 with ros2_tracing” (video, slides). Reference:

• C. Bédard, “Tracing ROS 2 with ros2_tracing,” in ROS World 2021. Open Robotics, October 2021. [Online]. Available: https://vimeo.com/652633418, (pdf)

Tutorials & demos

• ROS 2 documentation: Building ROS 2 with tracing
• Real-Time Working Group documentation tutorial: How to use ros2_tracing to trace and analyze an application
• ROS World 2021 demo: github.com/christophebedard/ros-world-2021-demo

Building

As of Iron, the LTTng tracer is a ROS 2 dependency. Therefore, ROS 2 can be traced out-of-the-box on Linux; this package does not need to be re-built.

To make sure that the instrumentation and tracepoints are available:

$ source /opt/ros/rolling/setup.bash  # With a binary install
$ source ./install/setup.bash  # When building from source
$ ros2 run tracetools status
Tracing enabled

A ROS 2 installation only includes the LTTng userspace tracer (LTTng-UST), which is all that is needed to trace ROS 2. To trace the Linux kernel, the LTTng kernel tracer must be installed separately:

$ sudo apt-get update
$ sudo apt-get install lttng-modules-dkms

For more information about LTTng, refer to its documentation.

Removing the instrumentation

To build and remove all instrumentation, use TRACETOOLS_DISABLED:

$ colcon build --cmake-args -DTRACETOOLS_DISABLED=ON

This will remove all instrumentation from the core ROS 2 packages, and thus they will not depend on or link against the shared library provided by the tracetools package. This also means that LTTng is not required at build-time or at runtime.

Excluding tracepoints

Alternatively, to only exclude the actual tracepoints, use TRACETOOLS_TRACEPOINTS_EXCLUDED:

$ colcon build --packages-select tracetools --cmake-clean-cache --cmake-args -DTRACETOOLS_TRACEPOINTS_EXCLUDED=ON

This will keep the instrumentation but remove all tracepoints. This also means that LTTng is not required at build-time or at runtime. This option can be useful, since tracepoints can be added back in or removed by simply replacing/re-building the shared library provided by the tracetools package.

Tracing

By default, trace data will not be generated, and thus these packages will have virtually no impact on execution.

File truncated at 100 lines see the full file

Any contribution that you make to this repository will be under the Apache 2 License, as dictated by that license:

5. Submission of Contributions. Unless You explicitly state otherwise,
   any Contribution intentionally submitted for inclusion in the Work
   by You to the Licensor shall be under the terms and conditions of
   this License, without any additional terms or conditions.
   Notwithstanding the above, nothing herein shall supersede or modify
   the terms of any separate license agreement you may have executed
   with Licensor regarding such Contributions.

Contributors must sign-off each commit by adding a Signed-off-by: ... line to commit messages to certify that they have the right to submit the code they are contributing to the project according to the Developer Certificate of Origin (DCO).