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. That href, and the Function detail’s top-level x-medkit-graph link, exist only while this plugin is loaded - a gateway without it omits both rather than publishing a URI nothing answers.
• Exports describe_plugin_routes, so the endpoint and the shape of the graph document are part of GET /api/v1/docs instead of being reachable but undocumented.
• 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

0.7.0 (2026-08-27)

• Breaking: the x-medkit-graph health model is reworked and schema_version is now "2.0.0". pipeline_status is derived from data freshness and node reachability instead of the previous status model, and no longer reports "broken" for an edge that simply has no /diagnostics coverage. The error_reason values node_offline, topic_stale and no_data_source are gone; metrics_stale is the only reachable value. A consumer that matched on the old values needs a change (#546, #545)
• metrics.source reports the resolved publisher rather than a placeholder, falling back to the single publisher of a topic where the RMW does not expose the identity directly, and the negotiation topic filter is anchored to path segments so an unrelated topic whose name merely contains the segment is no longer matched (#546)
• Per-function configuration overrides take effect, an invalid override warns instead of being applied silently, and the freshness clock is monotonic with a stateless stale grace, so a wall-clock step no longer moves an edge in or out of staleness (#546)
• Rate measurement is defended against multi-publisher inflation, state is bounded, and shutdown is guarded against callbacks firing on a partially destroyed provider (#546)
• The plugin and its robustness fields are documented, and the never-executed stale-topic path is removed rather than left as dead code (#546)
• Contributors: \@bburda

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