ros2_medkit_graph_provider

Gateway plugin that builds a live ROS 2 topic dataflow graph per SOVD Function, enriched with frequency, latency, and drop-rate metrics sourced from /diagnostics. This is the default IntrospectionProvider - extracted from ros2_medkit_gateway into a standalone plugin package in v0.4.0.

What It Does

• Serves GET /api/v1/functions/{function_id}/x-medkit-graph, plus a cyclic-subscription sampler under the same resource name and a capability href on every Function’s detail response.
• Subscribes to /diagnostics and resolves the publishing node for each metrics sample (never a fabricated or hardcoded name).
• Builds a per-Function graph of Apps (nodes) and topic connections (edges) with per-edge frequency (Hz), latency (ms), and drop-rate (%) metrics. Drop-rate degradation only fires if your producer actually emits drop_rate_percent/drop_rate - the reference greenwave_monitor producer does not, so that rule is inert against it out of the box.
• Reports pipeline_status (healthy / degraded / broken) and, when degraded, the bottleneck_edge.
• Flags each edge’s live publisher count (publisher_count) and a rate_ambiguous warning when more than one publisher shares a topic, since the measured rate is then summed across publishers and can mask a slow pipeline as healthy.

The metrics require a real /diagnostics producer running elsewhere in your system - see the Graph Provider tutorial for the producer contract before doing anything else. Without one, every edge stays pending forever.

Configuration

Loaded as a gateway plugin. gateway.launch.py auto-detects and loads this plugin when the package is installed, with no configuration required. To load it manually:

plugins: ["graph_provider"]
plugins.graph_provider.path: "/path/to/lib/ros2_medkit_graph_provider/libros2_medkit_graph_provider_plugin.so"
plugins.graph_provider.expected_frequency_hz_default: 30.0

See the configuration reference for the full set of thresholds and per-function overrides.

Architecture

The plugin implements GatewayPlugin + IntrospectionProvider:

• GraphProviderPlugin - Main plugin class with ROS 2 subscriptions
• GraphBuildState - Per-request snapshot of topic metrics and app last-seen timestamps
• GraphBuildConfig - Resolved thresholds (expected frequency, degradation, freshness)

Entity cache is populated from the ROS 2 graph during each discovery cycle via the merge pipeline’s PluginLayer. The graph document itself is always rebuilt fresh from the live entity cache on every request - there is no cross-request cache to go stale.

Documentation

• Graph Provider Tutorial
• Graph Provider Configuration
• Plugin System Guide
• REST API Reference

License

Apache License 2.0

Changelog for package ros2_medkit_graph_provider

Forthcoming

• x-medkit-graph pipeline health rework: pipeline_status no longer misreports "broken" for edges with no /diagnostics coverage at all (the previous status model conflated "never observed" with "actively broken"). error_reason is now freshness-based and its only reachable value is metrics_stale; node_offline, topic_stale, and no_data_source are gone. metrics.source is now the actual resolved /diagnostics publisher node name (resolved per message via publisher GID matching against /diagnostics), omitted rather than hardcoded to "greenwave_monitor" when it cannot be resolved. Per-function threshold overrides (plugins.graph_provider.function_overrides.<function_id>.*) now take effect. schema_version bumped to "2.0.0" (#545)
• Robustness hardening for x-medkit-graph health signals: freshness and staleness are now computed against a monotonic clock, so a backward wall-clock step (e.g. an NTP correction) can no longer make a dead topic read as fresh; a new stale_grace_sec setting (default 2.0, per-function overridable) debounces a single late /diagnostics sample so pipeline_status does not flap to "broken" and back; a new multi_publisher_rate setting (default "annotate", per-function overridable) defends against a duplicate or leftover publisher inflating a topic's summed arrival rate and masking a slow pipeline as healthy, backed by new per-edge metrics.publisher_count and metrics.rate_ambiguous fields; metrics.source is now cleared - not retained - whenever the most recent sample's publisher cannot be resolved, matching its documented latest-wins contract; and invalid plugins.graph_provider.* configuration, including per-function override field-name typos and wrong-typed values, now logs a warning and falls back to the previous valid value instead of failing silently (#545)

0.6.0 (2026-06-22)

• No functional changes; version bump for the coordinated 0.6.0 release.
• Contributors: \@bburda

0.5.0 (2026-06-08)

• Migrated GraphProviderPlugin to the get_routes() plugin API and fixed a route-separator bug
• Added shutdown guards and noexcept destructors that reset rclcpp resources before member destruction, preventing teardown SIGSEGV
• Added post-shutdown guard unit tests; dropped the cpp-httplib source install from the Dockerfile (now vendored via ros2_medkit_cmake)
• Build: adopt the centralized ROS2MedkitWarnings cmake module
• Contributors: \@bburda

0.4.0 (2026-03-20)

• Initial release - extracted from ros2_medkit_gateway package
• GraphProviderPlugin for ROS 2 graph-based entity introspection
• Standalone external plugin package with independent build and test
• Locking support via PluginContext API
• Contributors: \@bburda