Warning

You're reading the documentation for a version of ROS 2 that has reached its EOL (end-of-life), and is no longer officially supported. If you want up-to-date information, please have a look at Jazzy.

Building ROS 2 with tracing instrumentation

This guide shows you how to build ROS 2 with the tracing instrumentation provided by ros2_tracing. For more information, see the repository.

Instrumentation is included in the ROS 2 source code. However, if using the binaries or when building from source, the instrumentation does not actually trigger tracepoints by default. To get the tracepoints, the LTTng tracer needs to be installed, and then part of ROS 2 needs to be (re)built from source.

Note

This guide only applies to Linux systems and assumes that Ubuntu is used.

Prerequisites

Set up your system to build ROS 2 from source. See the source installation page for more information.

Installing the tracer

Install the LTTng tracer and related tools and dependencies.

sudo apt-get update
sudo apt-get install -y lttng-tools liblttng-ust-dev python3-lttng python3-babeltrace babeltrace

This only installs the LTTng userspace tracer, and not the LTTng kernel tracer, since it is not needed to trace ROS 2 applications.

Building

This step depends on whether you are building ROS 2 from source or using ROS 2 binaries.

With source installation

If you have already built ROS 2 from source before installing LTTng, you will need to re-build at least up to the tracetools package:

cd ~/ws
colcon build --packages-up-to tracetools --cmake-force-configure

With binary installation

If you rely on the ROS 2 binaries (Debian packages or “fat” archive), you will need to clone the ros2_tracing repository into your workspace and build at least up to the tracetools package:

cd ~/ws/src
git clone https://github.com/ros2/ros2_tracing.git
cd ../
colcon build --packages-up-to tracetools

Validating

Source and validate that tracing is enabled:

cd ~/ws
source install/setup.bash
ros2 run tracetools status

It should print out:

Tracing enabled

If something else is printed, then something went wrong.

Disabling tracing

If the LTTng userspace tracer is installed and found when building tracetools, tracing will be automatically enabled. Alternatively, to build and completely remove both the tracepoints and the tracing instrumentation from ROS 2, set the TRACETOOLS_DISABLED CMake option to ON:

colcon build --cmake-args -DTRACETOOLS_DISABLED=ON --no-warn-unused-cli