TopNode

A resource-monitoring component node for ROS 2.

Installation

On humble:

sudo apt install ros-humble-mcap-vendor

cd ~/ros2_ws/src
git clone https://github.com/safe-ros/topnode
cd ~/ros2_ws

colcon build
source ~/ros2_ws/install/setup.sh

On rolling:

sudo apt install ros-rolling-mcap-vendor 

cd ~/ros2_ws/src
git clone https://github.com/safe-ros/topnode
cd ~/ros2_ws

colcon build
source ~/ros2_ws/install/setup.sh

Usage

To see that the workspace was correctly built and installed, the component should appear in the component list

$ ros2 component types
topnode
  ResourceMonitorNode

Standalone Node

The standalone resource monitor may be started with

ros2 run topnode resource_monitor

Component Node

The primary intended use of the resource monitor is as a component node.

When the component is added to a running container, it will monitor the resource usage of that container.

Instrumenting a running container

To add the resource monitor node to an existing container:

ros2 component load $COMPONENT_MANAGER_NODE topnode ResourceMonitorNode

Instrumenting a container via launch

To add the resource monitor to a container via launch:

container = ComposableNodeContainer(
        name='instrumented_container',
        namespace='',
        package='rclcpp_components',
        executable='component_container',
        composable_node_descriptions=[
            ComposableNode(
                package='topnode',
                plugin='ResourceMonitorNode',
                name='resource_monitor',
                parameters=[{
                    "publish_cpu_memory_usage": True,
                    "publish_memory_state": True,
                    "publish_io_stats": True,
                    "publish_stat": True,
                    "publish_period_ms": 500,
                    "record_cpu_memory_usage": True,
                    "record_memory_state": True,
                    "record_io_stats": True,
                    "record_stat": True,
                }]),
        ],
        output='screen',
)

Controlling the monitor via lifecycle

The monitor is implemented as a managed node

When the node starts, it is in the unconfigured state. In this state, no parameters have been read and the topics/recording have not started.

To move the node to the configured state:

ros2 lifecycle set /resource_monitor configure

In the configured state, parameters are read and the requested topics/recording are initialized but not running.

To move the node to the active state:

ros2 lifecycle set /resource_monitor activate

In the active state, publication and recording is running

To stop recording, deactivate the node

ros2 lifecycle set /resource_monitor deactivate

Once deactivated, recording is finalized.

API

Parameters

• publish_period_ms (int): Statistics sample period
• publish_cpu_memory_usage (bool): Enable/disable CPU and memory usage statistics topic
• publish_memory_state (bool): Enable/disable memory state topic
• publish_io_stats (bool): Enable/disable IO statistics topic

• publish_stat (bool): Enable/disable stat topic

• record_file (string): filename to record to
• record_cpu_memory_usage (bool): Enable/disable CPU and memory usage statistics recording
• record_memory_state (bool): Enable/disable memory state recording
• record_io_stats (bool): Enable/disable IO statistics recording
• record_stat (bool): Enable/disable stat recording

Topics

• ~/cpu_memory_usage: CPU and memory usage statistics topic
• ~/memory_state: Memory state topic
• ~/io_stats: IO stats topic
• ~/stat: Stat topic

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).