docs(fault_manager): clarify the capture pool parallelizes snapshots only

Document that capture_pool_size parallelizes freeze-frame snapshot capture only -
rosbag is single-writer and records one fault at a time regardless of pool size -
and that the capture_* parameters govern the shared pool, which is created when
snapshots or rosbag is enabled.

Author: bburda

docs/config/fault-manager.rst

@@ -207,7 +207,10 @@ Basic Snapshot Settings
        new snapshots for that fault are rejected. Set to 0 for unlimited.
    * - ``snapshots.capture_pool_size``
      - ``2``
-     - Max concurrent capture threads under a fault storm (>= 1).
+     - Max concurrent capture threads under a fault storm (>= 1). The capture pool is
+       shared and created when snapshots **or** rosbag is enabled, so these parameters
+       bound both. ``capture_pool_size`` parallelizes freeze-frame snapshot capture
+       only; rosbag is single-writer and records one fault at a time regardless.
    * - ``snapshots.capture_queue_depth``
      - ``16``
      - Max pending captures before the full-queue policy applies (>= 1).

docs/tutorials/snapshots.rst

@@ -92,7 +92,9 @@ Configure snapshot capture via fault manager parameters:
        new snapshots for that fault are rejected. Set to 0 for unlimited.
    * - ``snapshots.capture_pool_size``
      - ``2``
-     - Max concurrent capture threads under a fault storm (>= 1).
+     - Max concurrent capture threads under a fault storm (>= 1). This parallelizes
+       freeze-frame snapshot capture only; rosbag capture is single-writer and
+       records one fault at a time regardless of this value.
    * - ``snapshots.capture_queue_depth``
      - ``16``
      - Max pending captures before the full-queue policy applies (>= 1).

src/ros2_medkit_fault_manager/README.md

@@ -70,7 +70,7 @@ ros2 service call /fault_manager/clear_fault ros2_medkit_msgs/srv/ClearFault \
 
 Snapshots capture topic data when faults are confirmed for post-mortem debugging.
 
-Under a fault storm, captures are bounded by a worker pool (`capture_pool_size`) draining a bounded queue (`capture_queue_depth`); excess captures are dropped per `capture_queue_full_policy` and logged (throttled).
+Under a fault storm, captures are bounded by a worker pool (`capture_pool_size`) draining a bounded queue (`capture_queue_depth`); excess captures are dropped per `capture_queue_full_policy` and logged (throttled). The pool is shared and is created when snapshots **or** rosbag is enabled, so these parameters bound both. `capture_pool_size` parallelizes freeze-frame snapshot capture only - rosbag is single-writer and records one fault at a time regardless of pool size.
 
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
@@ -82,7 +82,7 @@ Under a fault storm, captures are bounded by a worker pool (`capture_pool_size`)
 | `snapshots.config_file` | string | `""` | Path to YAML config for `fault_specific` and `patterns` |
 | `snapshots.recapture_cooldown_sec` | double | `60.0` | Min seconds between captures for the same fault code. |
 | `snapshots.max_per_fault` | int | `10` | Max snapshots retained per fault. |
-| `snapshots.capture_pool_size` | int | `2` | Max concurrent capture threads under a fault storm (>= 1). |
+| `snapshots.capture_pool_size` | int | `2` | Max concurrent capture threads under a fault storm (>= 1). Parallelizes snapshot capture only; rosbag stays single-writer. |
 | `snapshots.capture_queue_depth` | int | `16` | Max pending captures before the full-queue policy applies (>= 1). |
 | `snapshots.capture_queue_full_policy` | string | `reject_newest` | Policy when the queue is full: `reject_newest` or `drop_oldest`. |
 

src/ros2_medkit_fault_manager/config/fault_manager.yaml

@@ -20,7 +20,10 @@ fault_manager:
     # storage backend is usable).
     snapshots.rosbag.enabled: false
 
-    # Capture concurrency bound under fault storms (issue #441):
+    # Capture concurrency bound under fault storms (issue #441). These govern the
+    # shared capture pool, which is created when snapshots OR rosbag is enabled, so
+    # they also bound rosbag capture. Note: pool_size parallelizes freeze-frame
+    # snapshots only - rosbag is single-writer and records one fault at a time.
     # snapshots.capture_pool_size: 2                  # max concurrent capture threads (>= 1)
     # snapshots.capture_queue_depth: 16               # max pending captures (>= 1)
     # snapshots.capture_queue_full_policy: reject_newest  # reject_newest | drop_oldest

src/ros2_medkit_gateway/README.md

@@ -932,7 +932,7 @@ Snapshots are configured via FaultManager parameters:
 | `snapshots.config_file` | string | `""` | Path to YAML config file for `fault_specific` and `patterns` |
 | `snapshots.recapture_cooldown_sec` | double | `60.0` | Min seconds between captures for the same fault code. |
 | `snapshots.max_per_fault` | int | `10` | Max snapshots retained per fault. |
-| `snapshots.capture_pool_size` | int | `2` | Max concurrent capture threads under a fault storm (>= 1). |
+| `snapshots.capture_pool_size` | int | `2` | Max concurrent capture threads under a fault storm (>= 1). Parallelizes snapshot capture only; rosbag stays single-writer (one fault at a time). |
 | `snapshots.capture_queue_depth` | int | `16` | Max pending captures before the full-queue policy applies (>= 1). |
 | `snapshots.capture_queue_full_policy` | string | `reject_newest` | Policy when the queue is full: `reject_newest` or `drop_oldest`. |