Make timestamp-indexed naming the default for split bagfiles

[Tiryoh]

Description

This proposal introduces a new --split-naming option to improve the usability of split bagfiles by allowing timestamps to be included directly in the filenames.

Note

Supplementary comment:

• This proposal changes course from adding a new CLI option to instead adopt timestamp-indexed naming (start-timestamp plus index) as the default behavior for split bagfiles. The goal is to improve human-readability and make filenames naturally sortable by time. To preserve backward compatibility during transition, an explicit flag to force the legacy serial naming (for example --split-naming=serial) may be provided, but the baseline behavior will be timestamp-indexed naming.

Currently, rosbag2 names split bagfiles using sequential numbering only (record_0.mcap, record_1.mcap, etc.). While this is functional, it makes it harder to quickly understand the time range each file covers when browsing files in a directory.

With the proposed --split-naming option, users could select between:

• serial (default): Current behavior with sequential numbering.
• timestamp-index: Each split bagfile name includes the start timestamp plus an index (e.g., record_2025-02-21-16-21-00_0.mcap).

This change would provide clearer, human-readable filenames, giving users immediate temporal context and helping those migrating from ROS1 workflows feel more at home. It is especially valuable in continuous operation scenarios, where stopping and restarting ros2 bag record frequently is not practical for systems with many topics or complex discovery.

Related Issues

This proposal is related to #1917 (Timestamp split bagfiles instead of serial numbering), which in turn is part of #1915 (Always-on recording). While all of these proposals aim to make bagfile naming more informative, they serve slightly different needs:

• Purpose: Timestamp split bagfiles instead of serial numbering #1917 is designed for always-on recording, where session boundaries do not apply. This proposal focuses on general split recording scenarios where timestamp context is important.
• Format: Timestamp split bagfiles instead of serial numbering #1917 suggests timestamp-only names (recording_20250221T162100Z.mcap). This proposal keeps both timestamp and index (recording_2025-02-21-16-21-00_0.mcap), ensuring both clarity and ordering.
• Compatibility: These approaches can coexist under a unified --split-naming interface, giving users flexibility to choose the scheme that best fits their workflow.

Completion Criteria

• Add --split-naming option to the ros2 bag record command.
• Implement serial mode (default, maintains current behavior).
• Implement timestamp-index mode with filesystem-safe timestamp format.
• Ensure compatibility with all splitting mechanisms (--max-bag-duration, --max-bag-size, manual splitting via ~/split_bagfile).
• Preserve backward compatibility by defaulting to serial.
• Add appropriate unit and integration tests.
• Update documentation and CLI help text.

Implementation Notes / Suggestions

• Timestamps should be filesystem-safe and sortable (suggested: YYYY-MM-DD-HH-mm-ss).
• Implementation would involve extending the SequentialWriter to handle naming modes.
• Use std::strftime or similar for formatting.
• Recommend UTC timestamps for consistency across environments.
• Timestamp should reflect the start time of each bagfile.
• Index should always be included to ensure uniqueness, even if multiple splits occur in the same second.

Testing Notes / Suggestions

• Unit tests: Verify filename generation for both modes.

• Integration tests: Confirm behavior with size, duration, and manual splits.

• Edge cases:

  • Rapid splits (sub-second).
  • Cross-platform filesystem compatibility.
  • Uniqueness guarantees under load.

• Backward compatibility: Verify unchanged behavior when --split-naming is not specified.

• Playback compatibility: Ensure generated bagfiles can be played back regardless of naming mode.

[fujitatomoya]

It is especially valuable in continuous operation scenarios, where stopping and restarting ros2 bag record frequently is not practical for systems with many topics or complex discovery.

i think this usecase is common in general, especially on simulation environment to check the repeated test running to make sure the behavior.

Add --split-naming option to the ros2 bag record command.

but i am not inclined to add more optional arguments because ros2 bag record has already many optional arguments... if that is not necessary, probably we would want to avoid this?

instead, maybe we can discuss on the default behavior.

what about the following?

• sequential incremental number at the begging(or end as currently implemeted) of the file name would be still useful, that indicates the absolute storage sequence agnostic from timestamp.
• timestamp prefix indicates when the file is created and started recording. and this could be affected by system time adjustment such as NTP. (but sequential incremental number shows the absolute order.)
• directory name indicates when the ros2 bag record command is issued.

rosbag2_2025_09_30-09_11_30/3_rosbag2_2025_09_30-09_14_30.mcap
rosbag2_2025_09_30-09_11_30/2_rosbag2_2025_09_30-09_13_30.mcap
rosbag2_2025_09_30-09_11_30/1_rosbag2_2025_09_30-09_12_30.mcap
rosbag2_2025_09_30-09_11_30/0_rosbag2_2025_09_30-09_11_30.mcap

[Tiryoh]

Thank you for the thoughtful feedback, @fujitatomoya! I really appreciate your perspective on this.

You're absolutely right that ros2 bag record already has many optional arguments, and I agree that avoiding unnecessary options is a good principle. I'm very open to discussing the default behavior instead.

Your proposed format makes a lot of sense to me:

• The sequential number provides the absolute storage order (especially useful when system time adjustments occur)
• The timestamp shows when each file was created and started recording
• The directory name indicates when the recording session began

rosbag2_2025_09_30-09_11_30/3_rosbag2_2025_09_30-09_14_30.mcap
rosbag2_2025_09_30-09_11_30/2_rosbag2_2025_09_30-09_13_30.mcap
rosbag2_2025_09_30-09_11_30/1_rosbag2_2025_09_30-09_12_30.mcap
rosbag2_2025_09_30-09_11_30/0_rosbag2_2025_09_30-09_11_30.mcap

This approach gives us the best of both worlds — clear temporal context from the timestamps while maintaining reliable ordering through the sequential numbers.

The main motivation for this proposal is to make timestamps available in the filenames. I’m flexible about the sequential numbering, so I’d be supportive of changing the default behavior in the way you suggest. It seems like a natural improvement that adds clarity without adding CLI complexity.

For example, if a custom output name is specified, the result could look like:

myrecord/3_myrecord_2025_09_30-09_14_30.mcap
myrecord/2_myrecord_2025_09_30-09_13_30.mcap
myrecord/1_myrecord_2025_09_30-09_12_30.mcap
myrecord/0_myrecord_2025_09_30-09_11_30.mcap

I’d love to hear what others think about making this the new default behavior.

[MichaelOrlov]

@Tiryoh @fujitatomoya, I agree that it would be better to change the default behavior to timestamp+index rather than add a new CLI parameter.
Format with index+name+timestamp looks more readable IMO.

myrecord/0_myrecord_2025_09_30-09_11_30.mcap
myrecord/1_myrecord_2025_09_30-09_12_30.mcap
myrecord/2_myrecord_2025_09_30-09_13_30.mcap

[Tiryoh]

@MichaelOrlov Thanks for your feedback! I'll write a patch and create a pull request.