Add circular logging by split count

- Add StorageOptions.max_splits (+ YAML/params, Python bindings)
- CLI: --max-splits (before size/duration)
- Writer: delete oldest files when exceeding size, duration, or split count

Author: luke-alloy

ros2bag/ros2bag/verb/record.py

@@ -159,6 +159,11 @@ def add_recorder_arguments(parser: ArgumentParser) -> None:
              'Default: %(default)d, recording written in single bagfile and splitting '
              'is disabled. If both splitting by size and duration are enabled, '
              'the bag will split at whichever threshold is reached first.')
+    parser.add_argument(
+        '--max-splits', type=int, default=0,
+        help='Maximum number of splits to retain before deleting the oldest bagfile '
+             '(circular logging). Default: %(default)d, unlimited. '
+             'Requires --max-bag-size or --max-bag-duration to be set.')
     parser.add_argument(
         '--max-record-size', type=int, default=0,
         help='Maximum total size in bytes for the entire recording across all splits. '
@@ -376,6 +381,7 @@ def main(self, *, args):  # noqa: D102
             max_bagfile_size=args.max_bag_size,
             max_bagfile_duration=args.max_bag_duration,
             max_cache_size=args.max_cache_size,
+            max_splits=args.max_splits,
             max_record_size=args.max_record_size,
             max_record_duration=args.max_record_duration,
             storage_preset_profile=args.storage_preset_profile,

rosbag2_cpp/src/rosbag2_cpp/reindexer.cpp

@@ -182,6 +182,7 @@ void Reindexer::aggregate_metadata(
       storage_options.storage_id,
       storage_options.max_bagfile_size,
       storage_options.max_bagfile_duration,
+      storage_options.max_splits,
       storage_options.max_record_size,
       storage_options.max_record_duration,
       storage_options.max_cache_size,

rosbag2_cpp/src/rosbag2_cpp/writers/sequential_writer.cpp

@@ -552,16 +552,18 @@ uint64_t SequentialWriter::get_total_record_duration() const
 
 void SequentialWriter::delete_oldest_files_if_needed()
 {
-  // Only delete if max_record_size or max_record_duration is set (circular buffer mode)
+  // Only delete if any circular buffer limit is set (size, duration, or split count)
   // Note: This is only called after split_bagfile(), so max_bagfile_size is guaranteed to be set
-  if (storage_options_.max_record_size == 0 && storage_options_.max_record_duration == 0) {
+  if (storage_options_.max_record_size == 0 &&
+      storage_options_.max_record_duration == 0 &&
+      storage_options_.max_splits == 0) {
     return;
   }
 
   // Protect metadata access with mutex to prevent race conditions
   std::lock_guard<std::mutex> lock(topics_info_mutex_);
 
-  // Delete oldest files until we're under both limits (if set)
+  // Delete oldest files until we're under all configured limits (if set)
   // Note: We just split, so we have at least 2 files and the oldest is definitely not current
   while (metadata_.files.size() > 1) {
     // Check if we need to delete based on size limit
@@ -572,8 +574,12 @@ void SequentialWriter::delete_oldest_files_if_needed()
     bool exceeds_duration_limit = (max_record_duration_ns_ != 0 &&
       get_total_record_duration() > max_record_duration_ns_);
 
-    // If we're under both limits (or they're not set), stop deleting
-    if (!exceeds_size_limit && !exceeds_duration_limit) {
+    // Check if we need to delete based on split-count limit
+    bool exceeds_split_limit = (storage_options_.max_splits != 0 &&
+      metadata_.files.size() > storage_options_.max_splits);
+
+    // If we're under all limits (or they're not set), stop deleting
+    if (!exceeds_size_limit && !exceeds_duration_limit && !exceeds_split_limit) {
       break;
     }
 

rosbag2_py/rosbag2_py/_storage.pyi

@@ -103,13 +103,16 @@ class StorageOptions:
     max_bagfile_duration: int
     max_bagfile_size: int
     max_cache_size: int
+    max_splits: int
+    max_record_size: int
+    max_record_duration: int
     snapshot_mode: bool
     start_time_ns: int
     storage_config_uri: str
     storage_id: str
     storage_preset_profile: str
     uri: str
-    def __init__(self, uri: str, storage_id: str = ..., max_bagfile_size: int = ..., max_bagfile_duration: int = ..., max_cache_size: int = ..., storage_preset_profile: str = ..., storage_config_uri: str = ..., snapshot_mode: bool = ..., start_time_ns: int = ..., end_time_ns: int = ..., custom_data: Dict[str, str] = ...) -> None: ...
+    def __init__(self, uri: str, storage_id: str = ..., max_bagfile_size: int = ..., max_bagfile_duration: int = ..., max_splits: int = ..., max_record_size: int = ..., max_record_duration: int = ..., max_cache_size: int = ..., storage_preset_profile: str = ..., storage_config_uri: str = ..., snapshot_mode: bool = ..., start_time_ns: int = ..., end_time_ns: int = ..., custom_data: Dict[str, str] = ...) -> None: ...
 
 class TopicInformation:
     message_count: int

rosbag2_py/src/rosbag2_py/_storage.cpp

@@ -82,12 +82,13 @@ PYBIND11_MODULE(_storage, m) {
   pybind11::class_<rosbag2_storage::StorageOptions>(m, "StorageOptions")
   .def(
     pybind11::init<
-      std::string, std::string, uint64_t, uint64_t, uint64_t, uint64_t, uint64_t, std::string, std::string, bool,
+      std::string, std::string, uint64_t, uint64_t, uint64_t, uint64_t, uint64_t, uint64_t, std::string, std::string, bool,
       int64_t, int64_t, KEY_VALUE_MAP>(),
     pybind11::arg("uri"),
     pybind11::arg("storage_id") = "",
     pybind11::arg("max_bagfile_size") = 0,
     pybind11::arg("max_bagfile_duration") = 0,
+    pybind11::arg("max_splits") = 0,
     pybind11::arg("max_record_size") = 0,
     pybind11::arg("max_record_duration") = 0,
     pybind11::arg("max_cache_size") = 0,
@@ -105,6 +106,9 @@ PYBIND11_MODULE(_storage, m) {
   .def_readwrite(
     "max_bagfile_duration",
     &rosbag2_storage::StorageOptions::max_bagfile_duration)
+  .def_readwrite(
+    "max_splits",
+    &rosbag2_storage::StorageOptions::max_splits)
   .def_readwrite(
     "max_record_size",
     &rosbag2_storage::StorageOptions::max_record_size)

rosbag2_storage/include/rosbag2_storage/storage_options.hpp

@@ -39,6 +39,11 @@ struct StorageOptions
   // A value of 0 indicates that bagfile splitting will not be used.
   uint64_t max_bagfile_duration = 0;
 
+  // The maximum number of bagfile splits to retain before the oldest bagfile is deleted.
+  // A value of 0 indicates that no deletion based on split count will occur.
+  // This feature is only available if either max_bagfile_size or max_bagfile_duration is set.
+  uint64_t max_splits = 0;
+
   // The maximum size a record can be, in bytes, before the oldest bagfile is deleted.
   // A value of 0 indicates that oldest bagfile is not deleted.
   // This feature is only available if either max_bagfile_size or max_bagfile_duration is set.

rosbag2_storage/src/rosbag2_storage/storage_options.cpp

@@ -28,6 +28,7 @@ Node convert<rosbag2_storage::StorageOptions>::encode(
   node["storage_id"] = storage_options.storage_id;
   node["max_bagfile_size"] = storage_options.max_bagfile_size;
   node["max_bagfile_duration"] = storage_options.max_bagfile_duration;
+  node["max_splits"] = storage_options.max_splits;
   node["max_record_size"] = storage_options.max_record_size;
   node["max_record_duration"] = storage_options.max_record_duration;
   node["max_cache_size"] = storage_options.max_cache_size;
@@ -47,6 +48,7 @@ bool convert<rosbag2_storage::StorageOptions>::decode(
   optional_assign<std::string>(node, "storage_id", storage_options.storage_id);
   optional_assign<uint64_t>(node, "max_bagfile_size", storage_options.max_bagfile_size);
   optional_assign<uint64_t>(node, "max_bagfile_duration", storage_options.max_bagfile_duration);
+  optional_assign<uint64_t>(node, "max_splits", storage_options.max_splits);
   optional_assign<uint64_t>(node, "max_record_size", storage_options.max_record_size);
   optional_assign<uint64_t>(node, "max_record_duration", storage_options.max_record_duration);
   optional_assign<uint64_t>(node, "max_cache_size", storage_options.max_cache_size);

rosbag2_storage_sqlite3/test/rosbag2_storage_sqlite3/storage_test_fixture.hpp

@@ -284,7 +284,7 @@ class StorageTestFixture : public TemporaryDirectoryFixture
       out << config_yaml;
     }
 
-    rosbag2_storage::StorageOptions storage_options{storage_uri, plugin_id, 0, 0, 0, 0, 0,
+    rosbag2_storage::StorageOptions storage_options{storage_uri, plugin_id, 0, 0, 0, 0, 0, 0,
       "", yaml_config};
     return storage_options;
   }

rosbag2_storage_sqlite3/test/rosbag2_storage_sqlite3/test_sqlite_storage.cpp

@@ -524,7 +524,7 @@ TEST_F(StorageTestFixture, storage_preset_profile_applies_over_defaults) {
 
   auto temp_dir = std::filesystem::path(temporary_dir_path_);
   const auto storage_uri = (temp_dir / "rosbag").generic_string();
-  rosbag2_storage::StorageOptions options{storage_uri, kPluginID, 0, 0, 0, 0, 0, "", ""};
+  rosbag2_storage::StorageOptions options{storage_uri, kPluginID, 0, 0, 0, 0, 0, 0, "", ""};
 
   options.storage_preset_profile = "resilient";
   writable_storage->open(options, rosbag2_storage::storage_interfaces::IOFlag::READ_WRITE);

rosbag2_transport/src/rosbag2_transport/config_options_from_node_params.cpp

@@ -416,6 +416,10 @@ get_storage_options_from_node_params(rclcpp::Node & node)
     node, "storage.max_bagfile_duration", 0,
     std::numeric_limits<int64_t>::max(), storage_options.max_bagfile_duration);
 
+  storage_options.max_splits = param_utils::declare_integer_node_params<uint64_t>(
+    node, "storage.max_splits", 0,
+    std::numeric_limits<int64_t>::max(), storage_options.max_splits);
+
   storage_options.max_record_size = param_utils::declare_integer_node_params<uint64_t>(
     node, "storage.max_record_size", 0,
     std::numeric_limits<int64_t>::max(), storage_options.max_record_size);