LiveKit Portal for ROS diagnostics

Overview

The LiveKit Portal for ROS publishes standard ROS diagnostics on topic /diagnostics. Use them to confirm that a node initialized, is connected to its LiveKit room, and can forward topics, services, video, and remote ROS CLI calls. Diagnostics publish periodically and they help you identify connection instability or growing failure counts, as well as other issues, while a robot is in the field. See the diagnostics ROS wiki for more information.

Inspect the latest diagnostic array with:

ros2 topic echo /diagnostics --once

Each status is named ros_portal: <task> and uses the standard ROS diagnostic levels: OK, WARN, and ERROR.

Troubleshooting fields

Start with these statuses and fields when troubleshooting:

Status	Check	Indicates
`ros_portal_status`	`initialized`, `components_inactive`, `graph_discovery_active`	Whether LiveKit Portal for ROS completed local initialization, all expected components are active, and the ROS graph discovery worker runs. `connection_health` reports the room connection separately.
`ros_portal_status`	`config_path`, `local_identity`	Which configuration the node loaded and its LiveKit participant identity.
`connection_health`	`state`, `room_name`, `num_peers`	Whether the node is connected to the expected room and can see remote participants.
`connection_health`	`reconnect_count`, `connection_loss_count`	Whether an otherwise connected node has experienced unstable connectivity.
`connection_health`	`rtc.transport.current_round_trip_time_ms`, `rtc.traffic.packets_lost`, `rtc.traffic.max_jitter_ms`	Network quality signals that can help explain delayed or unreliable realtime traffic.
`topic_forwarder`	`outbound.failures`, `inbound.failures`	Whether topic forwarding failed in either direction. The node logs each failure with its cause, for example a schema mismatch or a JPEG frame that does not decode.
`topic_forwarder`	`outbound.video_tracks`, `inbound.video_tracks`, `inbound.video_tracks_paused`	How many image topics the node sends as video, and how many remote video tracks it republishes. A paused inbound track has no ROS subscribers.
`topic_forwarder`	`inbound.video_stamp_fallbacks`	How many inbound video frames had no sender metadata, so `header.stamp` comes from the receiver's clock.
`latched_topic_forwarder`	`rpc_registered`, `peers.behind`, `peers.given_up`	Whether latched topics, such as `/tf_static`, reach every remote peer.
`service_forwarder`	`routes_configured`, `services_created`, `request_failures`, `response_failures`	Whether every configured service route exists and forwarded calls succeed. `last_failure_reason` names the most recent failure category.
`cli_manager`	`topic_pub_cache_full_rejections`, `service_call_cache_full_rejections`	Whether remote publish or service-call requests are being rejected because a cache is full.
`cli_manager`	`rpc_failures`	How many remote ROS CLI requests failed. The node logs each failure with its RPC method and cause.
`video_source/<track_name>/<index>`	`state`, `error`	The state of a video source: `starting`, `running`, `stopped`, `end_of_stream`, or `error`. A source that ends or fails keeps that state until the room session ends. When the node reconnects to the room, it starts every source again.
`video_source/<track_name>/<index>`	`source_type`, `frames_captured`	The source type and how many frames it captured. The count stays `0` until the source stops or reaches end-of-stream.

The build_info status reports the LiveKit Portal for ROS, LiveKit SDK, and ROS distribution versions. Include it when collecting diagnostic output for support or when comparing environments.

Aggregate diagnostics

The LiveKit Portal for ROS publishes raw diagnostics. To group them under a single LiveKit Portal for ROS tree on /diagnostics_agg, run the standard diagnostic_aggregator node alongside it.

For example, save this configuration as ros_portal_diagnostics_aggregator.yaml:

/**:
  ros__parameters:
    path: ROS Portal
    connection_health:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Connection Health
      contains: ['connection_health']
    ros_portal_status:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Node Status
      contains: ['ros_portal_status']
    video_sources:
      type: diagnostic_aggregator/GenericAnalyzer
      path: Video Sources
      contains: ['video_source/']

Then start the aggregator and inspect its output:

ros2 run diagnostic_aggregator aggregator_node \
  --ros-args --params-file ros_portal_diagnostics_aggregator.yaml

ros2 topic echo /diagnostics_agg --once

Add analyzers for topic_forwarder, latched_topic_forwarder, service_forwarder, cli_manager, or build_info when those statuses are relevant to your deployment. The node publishes latched_topic_forwarder only when you configure a latched topic, and one video_source/<track_name>/<index> status for each entry in video_sources.

Additional resources

The following resources provide more information about diagnostics.