analyze_bag
Summarize a ROS 2 bag at a given path, returning storage format, duration, per-topic message rates, counts, and detected anomalies for debugging.
Instructions
Summarize a ROS 2 bag at path. Returns a BagAnalysis with storage format, duration, message count, per-topic stats, detected anomalies and mode_effective (live or mock). Per topic, frequency_hz is (n - 1) / (last - first message time) of that topic (frequency_basis topic_span), with first_timestamp_ns, last_timestamp_ns and latched; a latched topic whose messages all fall within 1 second (e.g. /tf_static, a start-up burst) has a null frequency_hz, while a latched topic published over a longer span keeps its rate. When the bag cannot be read locally, or is a large .mcap (over 200 MiB), the rate falls back to count / bag duration (bag_duration) and note says why. Live mode runs ros2 bag info and accepts .mcap and .db3 files plus rosbag2_* directories (ROS 1 .bag files are not readable by ros2 bag info; use peek_bag_samples for those); mock mode returns fixture data for any path suffix except clearly non-bag ones. Raises an MCP error if the path is malformed, missing in live mode, or unparseable, or if no ros2 CLI is available. Anomaly detection is available in mock mode only. Read-only; no side effects.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Path to a bag: a file ending in `.mcap` or `.db3`, or a `rosbag2_*` directory. `peek_bag_samples` also reads ROS 1 `.bag` files; `analyze_bag` does not (`ros2 bag info` cannot open them). Leading/trailing whitespace is stripped. Null bytes and otherwise malformed filesystem paths are rejected. Existence and bag format are validated by the live adapter (mock mode accepts any well-formed path). |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| note | No | Why the result is less detailed than usual, for example per-topic rates computed over the whole bag duration because the bag was too large to read per-topic message times. `None` when there is nothing to add. | |
| path | Yes | Path to the analyzed bag, as supplied by the caller. May point to a file (`.mcap`, `.db3`, or ROS 1 `.bag` for `peek_bag_samples`) or to a `rosbag2_*` directory. | |
| topics | Yes | Per-topic statistics for every topic present in the bag. | |
| anomalies | No | Human-readable notes about gaps, clock jumps, or other oddities. Populated in mock mode only; live mode does not detect anomalies. | |
| bag_format | No | Concrete bag container format detected by the reader: `mcap` (Foxglove MCAP), `db3` (ROS2 rosbag2 SQLite), `bag` (ROS1 legacy chunked), or `unknown` when the reader could not classify. `None` when the bag was summarized from `ros2 bag info` text, which carries no format information. | |
| message_count | Yes | Total number of messages across all recorded topics. | |
| mode_effective | Yes | Runtime mode the adapter served this response in: `live` (real ROS2 introspection) or `mock` (deterministic fixtures). Lets a caller tell a real graph from a demo one without calling `health_check`. | |
| storage_format | No | `mcap`, `sqlite3`, or other storage identifier when known. | |
| duration_seconds | Yes | Total bag duration, in seconds (wall clock between first and last message). | |
| participants_recorded | No | DDS participants recorded in the bag when the container format embeds participant metadata. MCAP can carry it via channel metadata records; ROS2 `.db3` and ROS1 `.bag` generally do not. Empty list when not available, which is the common case. | |
| recording_duration_ns | No | Recording duration in nanoseconds when readable from the bag's index. `None` when only `ros2 bag info` text was parsed; `duration_seconds` (float) is the always-populated fallback that downstream LLM consumers should prefer when this is `None`. | |
| samples_decoded_count | No | Total decoded sample count across all topics produced by the bag reader. `0` when the reader only parsed metadata or when `rosbags` is not installed on the host. Use `peek_bag_samples` to pull the actual sample payloads for a specific topic. |