ROS 2 rosbag2 Guide: Record, Inspect, and Replay Topics for Debugging

Desired Outcome

The goal is to capture a deterministic snapshot of selected ROS 2 topics during a test run, then replay that snapshot on a fresh or existing system to reproduce faults or validate fixes without needing to re‑run the hardware.

Prerequisites

• ROS 2 environment sourced (e.g., source /opt/ros/foxy/setup.bash).
• Rosbag2 packages installed: ros--rosbag2 and the appropriate transport plugins (e.g., ros--rosbag2-storage-default-plugins).
• Running system publishing the target topics. Use ros2 topic list to verify availability.
• Disk space sufficient for the expected data volume. High‑rate sensors (camera, lidar) can fill several gigabytes in minutes.

Procedure

1. Record Selected Topics

ros2 bag record -o my_bag /topic_a /topic_b

Use the -o flag to name the bag directory. Replace /topic_a and /topic_b with the actual topic names you want to capture. To record all topics, use -a instead of listing each one.

Stop the recording with Ctrl‑C when the desired duration has elapsed. The bag will contain a metadata.yaml file and one or more *.db3 files.

2. Inspect the Bag

ros2 bag info my_bag

This command prints a table of topics, message counts, and the overall duration. Verify that the number of messages matches the expected publish rate from ros2 topic hz:

ros2 topic hz /topic_a

Discrepancies may indicate dropped messages during recording.

3. Replay the Bag

ros2 bag play my_bag --rate 1.0 --loop

The --rate flag controls playback speed (1.0 = real time, 2.0 = twice as fast). --loop repeats the bag indefinitely, useful for continuous integration tests. To replay only a subset of topics, add --topics /topic_a.

When replaying into a live system, ensure that any live publishers on the same topic names are stopped or remapped to avoid conflicts. For example:

ros2 bag play my_bag --remap /topic_a:=/replay_topic_a

Expected Checks

• During replay, run ros2 topic hz /topic_a to confirm the message rate matches the recorded rate.
• Use ros2 topic echo /topic_a to verify that message contents and timestamps are preserved.
• Check that nodes consuming the replayed topics process the data without errors. If a node crashes, review the log for rosbag2 warnings about missing or corrupted messages.

Recovery Options

• If a bag fails to open, ensure that the directory contains a metadata.yaml and the corresponding *.db3 files. A missing metadata.yaml usually indicates an incomplete or interrupted recording.
• Reindex an interrupted recording: ros2 bag reindex my_bag. This rebuilds the metadata and can recover message counts.
• For long recordings, split the bag into smaller segments using ros2 bag record --split or by stopping and starting new bags manually. Smaller bags reduce the risk of corruption and simplify post‑processing.
• When replaying, if you encounter errors like “invalid bag file”, try deleting the metadata.yaml and reindexing, or use a fresh bag directory.

Limitations & Practical Checks

• Rosbag2’s default storage backend is SQLite3. For very high‑rate streams, consider the rosbag2_storage_ros2file backend or enable compression (e.g., --compression-mode zstd) to reduce disk usage.
• Replaying into a system that already has live publishers on the same topic names can cause duplicate messages. Remapping or isolating the replay environment is recommended.
• Always verify the ROS 2 distribution’s specific CLI flags by running ros2 bag --help on the target machine before scripting.