Rosgraph Monitor

Provides a C++ library rosgraph_monitor with main class rosgraph_monitor::RosgraphMonitor, which watches the entire ROS application to create an up-to-date graph representation, running analyses to check whether it meets certain “healthy” criteria.

The library may be used directly by application code, or run standalone as a parameter-configurable ROS Node rosgraph_monitor_node.

Either way it’s used, the Graph Monitor provides a set of diagnostic_msgs/DiagnosticStatus summarizing the graph health. These Diagnostics are provided in a friendly format for DiagnosticAggregator to interpret as a toplevel health status.

A convenience launch file is provided which starts the graph monitor node and a properly configured diagnostic aggregator, and can be used directly or as an example for usage pattern.

Graph Representation

The monitor keeps track of the following entities and their relationships:

• Node
  • name
• Publisher
  • node
  • name
  • type
  • QoS profile
• Subscription
  • node
  • name
  • type
  • QoS profile

Health Checks

These health criteria are provided:

• Node Liveness: Report errors for nodes that were once present but are no longer in the graph
• Graph Continuity: report warnings for publishers or subscriptions that don’t have anything listening/sending on the other end
• Topic Frequencies: interpret /topic_statistics to determine whether certain topics aren’t going at the expected rate. See following section for more information.

This also provides a rosgraph_monitor_node for standalone use, for users who do not need custom integration of the RosgraphMonitor class.

Frequency Checks

To set expectations for Topic Statistics Diagnostics, you must:

1. Enable /topic_statistics, see rmw_stats_shim for how to do this
2. Set the Deadline QoS policy on Publishers that should be sending at a fixed period (inverse of frequency)
3. You do not need to set Deadline on Subscription or use DeadlineMissed callbacks. Repeat - Subscriptions do not need any special treatment.

Usage

API

See RosGraphMonitor

Node

Recommended: run the provided launchfile

ros2 launch rosgraph_monitor monitor_launch.yaml

But you can also just run the standalone node, if you want to perform separate diagnostics aggregation

ros2 run rosgraph_monitor rosgraph_monitor_node

Configuration

See params_decl.yaml for the full parameters for the rosgraph_monitor Node.

These parameters mirror the structure rosgraph_monitor::GraphMonitorConfiguration, for those using the class directly instead of in the wrapping Node.

Implementation Tidbits

The RosgraphMonitor class is built to not initiate any ROS communications, which means it can be used in any preexisting program or node. It is passed a NodeGraphInterface abstract class pointer to make queries about the graph structure, and is passed TopicStatistics messages

The RosgraphMonitor receives a shared pointer to a node’s NodeGraphInterface and receives /topic_statistics to monitor the ROS computation graph and produce /diagnostics (DiagnosticArray) about issues in the graph:

Changelog for package rosgraph_monitor

0.2.3 (2025-10-22)

0.2.2 (2025-10-16)

• Fix release builds (#36)
  • don't depend on ROS_DISTRO environment variable, instead use detected package versions
• Contributors: Emerson Knapp

0.2.1 (2025-10-15)

• Fix dependency spec in package xmls, for buildfarm fixing (#35)
• Contributors: Emerson Knapp

0.2.0 (2025-08-07)

• Node Parameters on [/rosgraph]{.title-ref} (#26)
  • Graph monitor asynchronously queries parameter list for each tracked node, to know parameter names in graph representation
• Implement publisher/subscriber attributes on [/rosgraph]{.title-ref} (#23)
  • Includes QoS profile mapping and enums
• Publish node info under [/rosgraph]{.title-ref} (#20)
• Update package maintainers (#19)
  • Update package maintainers and add some author attributions to package.xml
• Add useful set of precommit formatters and checks that enhance the ament linting (#21)
• Use DiagnosticAggregator instead of custom Analyzer (#16)
• Test the rmw_stats_shim topic_statistics in the CI build (#18)
• Update package maintainers (#19)
  • Update package maintainers and add some author attributions to package.xml
• Use new ParamListener usercallback to skip the additional OnSetParametersCallback logic (#13)
• Contributors: Emerson Knapp, Troy Gibb

0.1.2 (2025-05-12)

• Kilted support (#6)
• Contributors: Emerson Knapp

0.1.1 (2025-04-09)

• Remove telegraf bridge and update some language
• RAII initialization of RosgraphMonitor (#12)
• Fix build issues with latest generate_parameter_library (#11)
• Action CI - support Humble, Jazzy, Rolling (#1)
• Initial package setup
• Contributors: Emerson Knapp, Troy Gibb, Joshua Whitley