How darshan-stack/ros2_watch works
This repository is a Python-based CLI tool that runs inside a sourced ROS2 environment and provides unified health monitoring + debugging for ROS2 robotic systems.
• introspects the ROS2 graph (nodes/topics/QoS),
• optionally observes message flows to approximate end-to-end latency,
• analyzes recorded data (MCAP) for regression (diff),
• produces human-readable console output (and possibly structured output later).
File tree → inferred architecture
Top-level structure:
• robowatch/ is the package.
• Each top-level CLI command has its own module:
• pulse.py, watch.py, trace_cmd.py, diff_cmd.py, doctor.py
• CLI orchestration:
• __main__.py (enables python -m robowatch ...)
• cli.py (command routing / argument parsing)
• ROS2 integration / shell-outs:
• ros2_command.py (likely wrapper around invoking ROS2 CLI or querying graph)
• “Glue / shared logic”:
• pulse.py (snapshot aggregation)
• Tests:
• tests/test_pulse.py, tests/test_diff_cmd.py (non-ROS specific logic)
Meta/build:
• setup.py, setup.cfg → Python packaging
• package.xml → ROS2 package metadata (ament/colcon ecosystem compatibility)
• requirements.txt → Python deps (but ROS deps like rclpy come from ROS install)
Command module → integrations
• ROS2 graph queries, subscriptions, QoS checks (via rclpy or ros2_command.py)
• Filesystem reads for MCAP (diff)
• OS metrics collection (pulse/watch)
Command-specific dataflows (make these explicit)
• pulse
• Queries ROS graph → list nodes, topics, pub/sub relationships
• Pulls lightweight resource usage → CPU/mem (host-level and/or node processes)
• Produces “pipeline overview” → a derived graph summary
• watch
• Targets a node name → resolves publishers/subscribers and QoS
• Live loop: periodically polls/observes → emits updates
• trace
• Takes a topic chain string "/a -> /b -> /c"
• Subscribes/observes timestamps at each hop (approximation)
• Computes hop-by-hop and total latency
• diff
• Reads MCAP A and MCAP B
• Computes per-topic frequency deltas and regression report
• doctor
• Runs audits on graph structure (e.g., disconnected graphs, missing pubs/subs, QoS mismatches)
• --deep potentially invokes heavier checks (call this out as “optional deeper probes”)
Command pattern / subcommand architecture
• cli.py dispatches to per-command modules.
• Each command is independently testable (seen in tests/).
Adapter/Facade for ROS2 interaction
• ros2_command.py suggests abstraction over ROS2 CLI or graph querying.
• Helps later swap/extend implementation (e.g., C++ backend or tracing).
Separation of concerns
• (a) CLI parsing/dispatch
• (b) data collection (ROS2, OS, MCAP)
• (c) analysis/derivation (latency, diff, audits)
• (d) presentation (console report)
Technologies & artifacts to label
• Python 3.10+
• ROS2 (rclpy, ROS graph concepts: nodes/topics/QoS)
• DDS (as underlying transport; not necessarily directly called today)
• MCAP (offline recording format)
• Packaging: setup.py/setup.cfg + package.xml (signals both pip and ROS2 ecosystem)
• Tests: pytest
Artifacts:
• MCAP files as data inputs for diff
• Terminal stdout as primary output channel