Skip to content

Add new ros2 bag Kilted features + updates #5771

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 5 commits into
base: rolling
Choose a base branch
from
Open

Add new ros2 bag Kilted features + updates #5771

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8eb3fee
Add --topics to ros2 bag record Commands
chen-harrison Jul 8, 2025
3f85c78
Change from Bag Files to Bag Directories
chen-harrison Jul 8, 2025
a3222d7
Update ros2 bag Command Output
chen-harrison Jul 8, 2025
7dd22c8
Add Multiple Bag Playback Explanation
chen-harrison Jul 8, 2025
4974e41
``Ctrl+C`` -> :kbd:`Ctrl-C`
chen-harrison Jul 10, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 90 additions & 19 deletions ...r-CLI-Tools/Recording-And-Playing-Back-Data/Recording-And-Playing-Back-Data.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,15 +135,15 @@ To record the data published to a topic use the command syntax:

.. code-block:: console

$ ros2 bag record <topic_name>
$ ros2 bag record --topics <topic_name>

Before running this command on your chosen topic, open a new terminal and move into the ``bag_files`` directory you created earlier, because the rosbag file will save in the directory where you run it.

Run the command:

.. code-block:: console

$ ros2 bag record /turtle1/cmd_vel
$ ros2 bag record --topics /turtle1/cmd_vel
[INFO] [rosbag2_storage]: Opened database 'rosbag2_2019_10_11-05_18_45'.
[INFO] [rosbag2_transport]: Listening for topics...
[INFO] [rosbag2_transport]: Subscribed to topic '/turtle1/cmd_vel'
Expand All @@ -155,40 +155,66 @@ The movements don't matter, but try to make a recognizable pattern to see when y

.. image:: images/record.png

Press ``Ctrl+C`` to stop recording.
Press :kbd:`Ctrl-C` to stop recording.

The data will be accumulated in a new bag directory with a name in the pattern of ``rosbag2_year_month_day-hour_minute_second``.
This directory will contain a ``metadata.yaml`` along with the bag file in the recorded format.

3.2 Record multiple topics
~~~~~~~~~~~~~~~~~~~~~~~~~~

You can also record multiple topics, as well as change the name of the file ``ros2 bag`` saves to.
You can also record multiple topics, as well as change the name of the bag directory ``ros2 bag`` saves to.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the previous file is not actually wrong, it saves the bag file with the specified name as well as bag directory. how about the following?

Suggested change
You can also record multiple topics, as well as change the name of the bag directory ``ros2 bag`` saves to.
You can also record multiple topics, as well as change the name of the destination ``ros2 bag`` saves to.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think what matters here is the directory. The files themselves are just a component of the bag; their name doesn't really matter. So I personally think we should keep "bag directory"

Copy link
Author

@chen-harrison chen-harrison Jul 17, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see that the help documentation for ros2 bag play says "destination", and maybe that helps clarify that it can also be a path? Would "bag directory path" accomplish that?

Also, since I'm still relatively new as a ROS contributor, I'm not really sure who to listen to as final say 😅


Run the following command:

.. code-block:: console

$ ros2 bag record -o subset /turtle1/cmd_vel /turtle1/pose
$ ros2 bag record -o subset --topics /turtle1/cmd_vel /turtle1/pose
[INFO] [rosbag2_storage]: Opened database 'subset'.
[INFO] [rosbag2_transport]: Listening for topics...
[INFO] [rosbag2_transport]: Subscribed to topic '/turtle1/cmd_vel'
[INFO] [rosbag2_transport]: Subscribed to topic '/turtle1/pose'
[INFO] [rosbag2_transport]: All requested topics are subscribed. Stopping discovery...

The ``-o`` option allows you to choose a unique name for your bag file.
The following string, in this case ``subset``, is the file name.
The ``-o`` option allows you to choose a unique name for your bag directory.
The following string, in this case ``subset``, is the bag directory name.
Comment on lines +179 to +180
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The ``-o`` option allows you to choose a unique name for your bag directory.
The following string, in this case ``subset``, is the bag directory name.
The ``-o`` option allows you to choose the destination for your bag directory and bag file name.
The following string, in this case ``subset``, is the bag directory name and bag file prefix name.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comment as above: https://github.com/ros2/ros2_documentation/pull/5771/files#r2211670982

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

At the end of section 3.1 when it says

This directory will contain a metadata.yaml along with the bag file in the recorded format.

We could replace it with

This directory will contain a bag file of the same name, with an index suffix "_0". It also contains a metadata.yaml file.

This would establish early on that the files use the name of the bag directory.


To record more than one topic at a time, simply list each topic separated by a space.
To record more than one topic at a time, simply list each topic separated by a space after ``--topics``.
In this case, the command output above confirms that both topics are being recorded.


You can move the turtle around and press ``Ctrl+C`` when you're finished.
You can move the turtle around and press :kbd:`Ctrl-C` when you're finished.

.. note::

There is another option you can add to the command, ``-a``, which records all the topics on your system.

3.3 Split recording into multiple files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can also divide your recording over multiple files, based on either recording duration or file size.
``-d <max_bag_duration>`` ensures that each file only lasts ``<max_bag_duration>`` seconds before it starts writing to
a new file, or ``-b <max_bag_size>`` ensures that each file does not exceed ``<max_bag_size>`` bytes in file size.

Run the following for at least 15 seconds, allowing for three 5-second bag files to be written:

.. code-block:: console

$ ros2 bag record -o subset_separate -d 5 --topics /turtle1/cmd_vel /turtle1/pose
[INFO] [rosbag2_recorder]: Press SPACE for pausing/resuming
[INFO] [rosbag2_recorder]: Listening for topics...
[INFO] [rosbag2_recorder]: Event publisher thread: Starting
[INFO] [rosbag2_recorder]: Recording...
[INFO] [rosbag2_recorder]: Subscribed to topic '/turtle1/cmd_vel'
[INFO] [rosbag2_recorder]: Subscribed to topic '/turtle1/pose'
[INFO] [rosbag2_recorder]: All requested topics are subscribed. Stopping discovery...
[INFO] [rosbag2_cpp]: Writing remaining messages from cache to the bag. It may take a while
[INFO] [rosbag2_cpp]: Writing remaining messages from cache to the bag. It may take a while
[INFO] [rosbag2_cpp]: Writing remaining messages from cache to the bag. It may take a while

Press :kbd:`Ctrl-C` when you're finished.
You should find a ``subset_separate`` directory with these files inside:
``subset_separate_0.mcap``, ``subset_separate_1.mcap``, and so on.

4 Inspect topic data
^^^^^^^^^^^^^^^^^^^^

Expand All @@ -198,12 +224,12 @@ You can see details about your recording by running:

$ ros2 bag info <bag_file_name>

Running this command on the ``subset`` bag file will return a list of information on the file:
Running this command on the ``subset/subset_0.mcap`` bag file will return a list of information on the file:

.. code-block:: console

$ ros2 bag info subset
Files: subset.mcap
$ ros2 bag info subset/subset_0.mcap
Files: subset_0.mcap
Comment on lines +227 to +232
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should keep subset here for simplicity.

Bag size: 228.5 KiB
Storage id: mcap
Duration: 48.47s
Expand All @@ -212,19 +238,41 @@ Running this command on the ``subset`` bag file will return a list of informatio
Messages: 3013
Topic information: Topic: /turtle1/cmd_vel | Type: geometry_msgs/msg/Twist | Count: 9 | Serialization Format: cdr
Topic: /turtle1/pose | Type: turtlesim_msgs/msg/Pose | Count: 3004 | Serialization Format: cdr
Services: 0
Service information:
Actions: 0
Action information:

Alternatively, you can also call ``ros2 bag info`` on a bag directory ``subset``,
and all bag files within it will be analyzed as one.

5 Play topic data
^^^^^^^^^^^^^^^^^

Before replaying the bag file, enter ``Ctrl+C`` in the terminal where the teleop is running.
5.1 Play a single bag file
~~~~~~~~~~~~~~~~~~~~~~~~~~
Comment on lines +252 to +253
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
5.1 Play a single bag file
~~~~~~~~~~~~~~~~~~~~~~~~~~
5.1 Play a single bag
~~~~~~~~~~~~~~~~~~~~~


Before replaying the bag file, enter :kbd:`Ctrl-C` in the terminal where the teleop is running.
Then make sure your turtlesim window is visible so you can see the bag file in action.

Enter the command:

.. code-block:: console

$ ros2 bag play subset
[INFO] [rosbag2_storage]: Opened database 'subset'.
$ ros2 bag play subset/subset_0.mcap
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Similar to my other comment, I think we should just keep subset here. The user just wants to "play the bag" and not really "play the bag file"

[INFO] [rosbag2_player]: Set rate to 1
[INFO] [rosbag2_player]: Adding keyboard callbacks.
[INFO] [rosbag2_player]: Press SPACE for Pause/Resume
[INFO] [rosbag2_player]: Press CURSOR_RIGHT for Play Next Message
[INFO] [rosbag2_player]: Press CURSOR_UP for Increase Rate 10%
[INFO] [rosbag2_player]: Press CURSOR_DOWN for Decrease Rate 10%
Progress bar enabled at 3 Hz.
Progress bar [?]: [R]unning, [P]aused, [B]urst, [D]elayed, [S]topped
[INFO] [rosbag2_player]: Playback until timestamp: -1


====== Playback Progress ======
[1751923361.427372456] Duration 0.00/48.47 [R]

Your turtle will follow the same path you entered while recording (though not 100% exactly; turtlesim is sensitive to small changes in the system's timing).

Expand All @@ -243,6 +291,29 @@ To get an idea of how often position data is published, you can run the command:

$ ros2 topic hz /turtle1/pose

5.2 Play multiple bag files
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Comment on lines +294 to +295
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
5.2 Play multiple bag files
~~~~~~~~~~~~~~~~~~~~~~~~~~~
5.2 Play multiple bags
~~~~~~~~~~~~~~~~~~~~~~


If you want to play multiple bag files that are all a part of the same recording,
simply call ``ros2 bag play`` on the bag directory, instead of a file:

.. code-block:: console

$ ros2 bag play subset_separate

This will play all the files inside of the ``subset_separate`` recording consecutively.

If you want to play a specific selection of files, that can be done by calling ``-i <bag_file_name>``
for each file.

.. code-block:: console

$ ros2 bag play -i subset_separate/subset_separate_0.mcap -i subset_separate/subset_separate_2.mcap

This will play the first and third bag files in ``subset_separate``, skipping the second.
They will play with the same relative time as when recorded, meaning there will be a 5 second pause
in between, where the ``subset_separate_1.mcap`` would have played if not omitted.
Comment on lines +297 to +315
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be reframed to not mention "the bag files inside the same recording." It should be about "playing multiple bags."

Your explanation here about "They will play with the same relative time as when recorded, meaning there will be a 5 second pause" is correct, but I don't think this is the goal of this feature.

The feature is about playing multiple bags that contain different topics recorded at the same time. This is intended for cases where a lot of data needs to be recorded at the same time, so multiple recorders run at the same time: each one records a subset of the topics. Individual .mcap files part of the same bag don't overlap in time (they're sequential), so they're not really separate bags.

This section should also mention how messages from separate bags are ordered when replayed. This is controlled by the --message-order option. By default, messages are ordered based on when they were received by the recorder node (which isn't quite the same as when they were recorded):

$ ros2 bag play --help
...
  --message-order {received,sent}
                        The reference to use for bag message chronological ordering. Choices: reception timestamp, publication timestamp. Default: reception timestamp. If messages are
                        significantly disordered (within a single bag or across multiple bags), replayed messages may not be correctly ordered. A possible solution could be to increase
                        the read_ahead_queue_size value to buffer (and order) more messages.
...

So I think it should be something like this:

Suggested change
If you want to play multiple bag files that are all a part of the same recording,
simply call ``ros2 bag play`` on the bag directory, instead of a file:
.. code-block:: console
$ ros2 bag play subset_separate
This will play all the files inside of the ``subset_separate`` recording consecutively.
If you want to play a specific selection of files, that can be done by calling ``-i <bag_file_name>``
for each file.
.. code-block:: console
$ ros2 bag play -i subset_separate/subset_separate_0.mcap -i subset_separate/subset_separate_2.mcap
This will play the first and third bag files in ``subset_separate``, skipping the second.
They will play with the same relative time as when recorded, meaning there will be a 5 second pause
in between, where the ``subset_separate_1.mcap`` would have played if not omitted.
Multiple bags may be recorded at the same time with different topics, for example to distribute the recording workload over multiple recorder processes.
To play multiple bags at the same time, simply call ``ros2 bag play`` and provide bags with ``-i``:
.. code-block:: console
$ ros2 bag play -i subset -i subset_separate
By default, this will play messages from both bags based on when they were originally received by the recorder.
The chronological ordering of messages can be changed with ``--message-order``.

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I see, that makes a lot more sense - I didn't fully understand the original motivations behind the implementation. I originally added the instructions for the subset_separate recording to generate multiple bags, which we'd then be able to use for this example.

Given that the best way to demonstrate its use case is two bags recorded simultaneously with different topics, should that subset_separate example change? Is it not "beginner enough" to start ros2 bag record -o vel --topics /turtle1/cmd_vel and ros2 bag record -o pose --topics /turtle1/pose at the same time? Or is it more helpful to learn how to split up bag files, and less so to see the bags playing simultaneously?


Managing Service Data
---------------------

Expand Down Expand Up @@ -340,7 +411,7 @@ Run the command:
[INFO] [1713995957.666092458] [rosbag2_recorder]: Recording...

Now ``ros2 bag`` is recording the service data published on the ``/add_two_ints`` service.
To stop the recording, enter ``Ctrl+C`` in the terminal.
To stop the recording, enter :kbd:`Ctrl-C` in the terminal.

The data will be accumulated in a new bag directory with a name in the pattern of ``rosbag2_year_month_day-hour_minute_second``.
This directory will contain a ``metadata.yaml`` along with the bag file in the recorded format.
Expand Down Expand Up @@ -368,7 +439,7 @@ You can see details about your recording by running:
5 Play service data
^^^^^^^^^^^^^^^^^^^

Before replaying the bag file, enter ``Ctrl+C`` in the terminal where ``introspection_client`` is running.
Before replaying the bag file, enter :kbd:`Ctrl-C` in the terminal where ``introspection_client`` is running.
When ``introspection_client`` stops running, ``introspection_service`` also stops printing the result because there are no incoming requests.

Replaying the service data from the bag file will start sending the requests to ``introspection_service``.
Expand Down Expand Up @@ -517,7 +588,7 @@ Run the command:
...

Now ``ros2 bag`` is recording the action data for the ``/fibonacci`` action: goal, result, and feedback.
To stop the recording, enter ``Ctrl+C`` in the terminal.
To stop the recording, enter :kbd:`Ctrl-C` in the terminal.

The data will be accumulated in a new bag directory with a name in the pattern of ``rosbag2_year_month_day-hour_minute_second``.
This directory will contain a ``metadata.yaml`` along with the bag file in the recorded format.
Expand Down