Practical Examples#

Quick Performance Check#

A 30-second snapshot to verify system health.

Prerequisites: ROS2 system running, monitoring stack installed.

  1. Source your ROS2 environment:

source /opt/ros/jazzy/setup.bash

source /opt/ros/humble/setup.bash

  1. Launch your ROS2 system:

ros2 launch my_robot robot.launch.py

  1. In a new terminal, run the quick check (completes automatically):

make quick-check

  1. Review auto-generated results:

ls monitoring_sessions/latest/visualizations/

Output files:

File

Contents

timing_delays.png

Processing delays per node

message_frequencies.png

Topic Hz over time

cpu_usage_timeline.png

CPU usage over time

cpu_heatmap.png

CPU distribution across cores

Monitor a Specific Node#

Detailed monitoring of a single ROS2 node for performance analysis.

Use when: Analyzing a particular node’s processing delays, CPU/memory usage, or identifying bottlenecks.

# 1. Find available nodes
ros2 node list

# 2. Start monitoring (runs until Ctrl+C)
make monitor NODE=/slam_toolbox

# 3. Let it run while your system operates normally

# 4. Press Ctrl+C — visualizations are auto-generated
ls monitoring_sessions/latest/visualizations/

With a fixed duration:

make monitor NODE=/slam_toolbox DURATION=120   # 2 minutes

Using Python directly for a named session:

uv run python src/monitor_stack.py --node /slam_toolbox --session slam_analysis

What to look for in results:

  • timing_delays.png — High delays indicate callback bottlenecks

  • cpu_usage_timeline.png — CPU spikes correlate with processing load

  • cpu_heatmap.png — Uneven distribution may indicate single-threaded bottlenecks

  • message_frequencies.png — Irregular rates can reveal queue or scheduling issues

Debug a Performance Issue#

Step-by-step guide to isolate and diagnose a performance problem.

Scenario: Your robot is running slowly and you suspect a specific node.

Step 1 — Identify the Problematic Process#

uv run python src/monitor_resources.py --list

Look for processes with unexpectedly high CPU usage.

Step 2 — Start Detailed Monitoring#

uv run python src/monitor_stack.py --node /problematic_node --session debug_session_1

Step 3 — Reproduce the Issue#

While monitoring is running, execute the operations that trigger the performance problem. Let it run for at least 30–60 seconds to collect representative data.

Step 4 — Stop and Analyze#

# Press Ctrl+C — visualizations are auto-generated
ls monitoring_sessions/debug_session_1/visualizations/

For deeper inspection:

# Inspect raw timing data
cat monitoring_sessions/debug_session_1/graph_timing.csv

# Check resource patterns
tail -100 monitoring_sessions/debug_session_1/resource_usage.log

Step 5 — Interpret Results#

Symptom

Possible causes

Next steps

Spikes in timing_delays.png

Heavy callback computation, blocking I/O

Profile the node’s code; check for synchronous I/O

Peaks in cpu_usage_timeline.png

Periodic heavy computation, message bursts

Review periodic timers; check queue sizes

Concentrated cpu_heatmap.png

Single-threaded bottleneck

Consider multi-threaded callbacks; review executor config

Irregular message_frequencies.png

Network latency, scheduler pressure

Check DDS QoS settings; review publisher rates

Step 6 — Validate a Fix#

After making changes, record a second session and compare:

uv run python src/monitor_stack.py --node /problematic_node --session debug_session_2 --duration 60

# Compare visualizations side by side
diff -r monitoring_sessions/debug_session_1/visualizations/ \
         monitoring_sessions/debug_session_2/visualizations/

Use make compare-sessions for an automated comparison report.

Monitor a Navigation Stack#

# Terminal 1: start the navigation stack
ros2 launch nav2_bringup tb3_simulation_launch.py

# Terminal 2: monitor interactively
./quickstart
# Choose: 1) Monitor my ROS2 application

Before/After Optimization Comparison#

# Before optimization
make monitor NODE=/my_node DURATION=120

# Make your code changes, then run again
make monitor NODE=/my_node DURATION=120

# Compare sessions
make compare-sessions