Observe a running node as rosgraph_msgs/Node via ros2 nodl describe

[lsy3]

Implements "Observe" (#68): observe a running node → its runtime rosgraph_msgs/Node, published latched on /nodl/observed_node and rendered by ros2 nodl describe. The Node message is the contract that "Describe" (#53) consumes. Validated across humble, jazzy, kilted, lyrical, rolling × {fastrtps, cyclonedds, zenoh} with gtest unit + pytest integration layers.

Disclosure: developed with the assistance of Claude (Claude Code). I've reviewed the changes.

Important

Updated per the WG review: nodl_observe is now C++ (ament_cmake), not Python — covering review points #2–#5 (Humble support, MCAP fixtures, C++ reimpl, one-container RMW testing). The Python impl is kept locally as an untracked reference; the verb keeps its CLI and shells out to a C++ observe binary.

CLI

ros2 nodl describe NODE_NAME [--timeout SEC] [--no-params] [--topic NAME] [-o FILE]

NODE_NAME FQN (hidden nodes work); --timeout 5.0 (discovery + param ceiling); --no-params skips the only contact with the target; --topic /nodl/observed_node; -o format inferred from .yaml/.yml/.json (default stdout YAML). Output is the rendered Node, not yet a NoDL document — that's #53, behind this same verb.

Architecture

• Library-first — nodl_observe::observe_node(node, fqn, opts) uses a caller-provided node, never spins its own; pure builders underneath, so graph-monitor can link the library directly. An observe executable wraps it (observe + latch-publish).
• Verb ↔ C++ = shell-out — ros2 nodl describe spawns the binary, receives the latched Node, renders with rosidl_runtime_py. The serialized message is the only language boundary (no pybind).

Design decisions

• Observe records, Describe interprets — all endpoints reported unfiltered (/rosout, param services, …); filtering is "Describe": convert observed state to NoDL document #53's call. Schema exception: <action>/_action/* constituents fold into their Action; orphans stay flat.
• Actions drop to the rcl_action C API — no rclcpp_action wrapper for the action graph (issue below).
• Infinite/overflow QoS durations → {INT32_MAX, 0} uniformly — the rmw sentinel overflows Duration.sec (int32) and won't round-trip CDR/MCAP; this is valid, cross-distro-identical, and fixes Humble.
• Service QoS → *_UNKNOWN — no info-by-service API in rclcpp/rmw; honest-unknown over plausible-wrong. @emersonknapp input welcome.

Humble (pre-Iron): supported + tested

Message-identical to Iron+; the REP-2011 type hash and BEST_AVAILABLE enum are compiled out (ROS2_<DISTRO>), so on Humble the type hash is left unset (like services) — differences live only in unfilled fields. Built and observation-tested with its own fixtures, no longer gated out.

Testing

• Unit (gtest) — QoS mapping (incl. duration clamp), endpoint building + type hash, action folding incl. orphans, parameter pairing, FQN split, and the parameter-collection degradation path (absent target → empty, never throws).
• Integration (pytest) — 3 scenario graphs (minimal / full-surface / multi-node isolation) observed via the observe binary, compared field-by-field vs committed MCAP fixtures. The can't-observe limits are test-locked (services created with explicit QoS still read *_UNKNOWN).

MCAP fixtures (replacing the YAML goldens) — one .mcap per (distro, RMW), resolver <distro>_<rmw> → <rmw> → base, collapsing to 5 files:

Fixture	Covers
base.mcap	full observation — jazzy/kilted/lyrical/rolling, RMWs that propagate fully
rmw_cyclonedds_cpp.mcap	cyclonedds KEEP_ALL depth→0 (every distro)
jazzy_rmw_fastrtps_cpp.mcap	jazzy's older fastrtps drops history/depth
humble_rmw_{fastrtps,cyclonedds}_cpp.mcap	Humble (no type hash)

test/mcap_fixtures.py print\|diff is a human-readable viewer; regen with REGEN_FIXTURES=1. Everything else (reliability, durability, deadline, type name, RIHS hash, structure, folding, service *_UNKNOWN) is byte-identical, so kilted/lyrical/rolling resolve to base.mcap with no override. zenoh is Iron+ only (no Humble package); its CI leg starts rmw_zenohd.

Note

In C++ a missing rosgraph_msgs/Node.msg is a build failure, not a silent skip — so requires_node_msg is gone. CI still best-effort pulls the message from ros2-testing and installs mcap so the comparison actually runs.

Upstream issues to file

1. No service-QoS introspection — no rmw_get_*_info_by_service on any RMW.
2. rcl_action_*_get_names_and_types[_by_node] not wrapped in rclcpp_action — request parity.

Closes #68

[read-the-docs-community]

Documentation build overview

📚 nodl | 🛠️ Build #33224056 | 📁 Comparing 043df91 against latest (18bc7d5)

  🔍 Preview build  

2 files changed

± index.html
± schema.html

[lsy3]

@emersonknapp a quick note on scope.

The feature is kept minimal and faithful to #68 — the observer and the ros2 nodl describe verb. The testing is where it's extensive: a 3 RMW × 5 distro matrix, deduplicated goldens (one _base/ plus small per-(distro, RMW) overrides), a guard that fails CI loudly rather than skipping when Node.msg is missing where required, and pre-Iron handling so Humble builds and skips cleanly.

I'd prefer to keep the tests alongside the implementation they validate, but I can split the multi-RMW/distro coverage into a follow-up if you'd rather a leaner first pass — the commits are already separated for it.

[lsy3]

WG review - 9 June 2026

@emersonknapp feel free to add if i missed anything but below is a summary of related points raised during the WG meeting

1. Service QoS → *_UNKNOWN. No info_by_service introspection in RCL on any RMW — report unknown, not a blocker.
2. Humble stays message-identical. Pre-Iron gaps (no type hash; int32 Duration for the infinite-deadline sentinel) get a best-effort fill — no Humble-specific message changes.
3. Fixtures → MCAP. YAML goldens (~2k lines) are past the readability point. Switch to MCAP (schemas + packed structs, smaller on disk) + a short script using the mcap lib to print/diff them human-readably. Base fixture + edge-case copies.
4. Reimplement in C++ (rclcpp). Reusable directly in graph-monitor (no Python boundary). Observer takes a node interface in (doesn't own the node); CLI wraps a thin node. Action introspection via direct rcl_action C calls — the rclcpp wrapper gap is confirmed.
5. Test all 3 RMWs in one container, not a CI matrix. Build once, then re-run the RMW-sensitive tests under each RMW_IMPLEMENTATION (instead of a separate rebuilding container per RMW); drop the requires_node_msg guard.

[luke-alloy]

@emersonknapp this is ready for review.

Recap: nodl_observe is now C++ (ament_cmake) per the WG review — covering points #2–#5 (Humble support, MCAP fixtures replacing the YAML goldens, the C++ reimplementation, and one-container 3-RMW testing). The Python implementation is kept locally as an untracked reference, and ros2 nodl describe keeps its CLI and shells out to the new observe binary. Full details are in the PR description.

CI is green across all five distros — humble, jazzy, kilted, lyrical, rolling — each over its RMWs (fastrtps / cyclonedds, plus zenoh on Iron+).

One open question I'd value your take on (you wrote Service.msg and the rmw stats shim): service QoS is reported *_UNKNOWN because there is no info-by-service API in rclcpp/rmw — is that the right call, or is there a better play? It's one of the two upstream issues noted in the description to file.