Metadata-Version: 2.5
Name: rostainer-archive
Version: 0.0.4
Summary: rostainer plugin: rotate ROS logs and bags into archives, and fetch them from robots
License-Expression: MIT
Keywords: docker,logs,ros,ros2,rostainer
Requires-Python: >=3.7
Requires-Dist: rostainer
Requires-Dist: rostainer-deploy
Description-Content-Type: text/markdown

# rostainer-archive

A [rostainer](https://git.whoi.edu/bmillerklugman/rostainer) plugin that
archives a workspace's ROS logs and bags, and fetches the archives from
deployed robots.

- **On every container start** (dev containers and packages alike), the
  contents of the log directories move into an archive, with a snapshot of
  the workspace's SQLite databases, and are tarred to
  `<archive_dir>/tar/<time>.tar.gz`. Anything still open by a process (a
  node's log, a bag being recorded) is left for the next rotation, so
  nothing is archived half-written.
- **`rostainer archive rotate`** rotates now, while ROS keeps running.
  **`rostainer archive snapshot`** tars a copy of the logs as they are now,
  including what's still being written, and leaves them in place. Both
  run here (in the workspace's running dev containers) by default, or on
  deployed robots when you name them (`rostainer archive snapshot robot1`,
  `... all`). On a robot, the installed package's own
  **`./rostainer archive rotate`** and **`./rostainer archive snapshot`**
  do the same.
- **`rostainer archive fetch [TARGET_OR_GROUP ...]`** downloads the tarballs
  from the robots `rostainer deploy` deploys to, over the same ssh
  connections: every one not already here. There's no second list of hosts.

## Install

```bash
pipx inject rostainer rostainer-archive     # or: pip install rostainer-archive
```

It needs the deploy plugin (`rostainer-deploy`), which pip installs with it.
In the workspace's `.rostainer.toml`:

```toml
# Refuse to start without it, rather than run without log rotation.
requires_plugins = ["archive"]

[plugins.archive]
dirs = [".ros/log", "bags"]   # archived; in the container, relative to the user's home
database_dir = "database"     # SQLite *.db snapshotted (not moved) into each archive; "" for none
archive_dir = "archive"       # where archives go
keep_unpacked = true          # keep each archive's directory next to its tarball
download_dir = "~/rostainer-logs"   # where 'fetch' saves, in a directory per target
```

`rostainer init --with archive` adds the table, with each setting described.

Mount the directories from the host with `volume_mappings`, so the logs and
archives outlive the container, and `fetch` can reach them:

```toml
volume_mappings = [
    "data/logs:/home/$USER/.ros/log",
    "data/bags:/home/$USER/bags",
    "data/archive:/home/$USER/archive",
]
```

rostainer's own ROS log pruning starts before the plugin's rotation, so it
could delete logs before they're archived. Turn it off:

```toml
ros_log_max_size_mb = 0
ros_log_max_age_days = 0
```

## Rotation

The plugin's `rotate.sh` runs as a post-build hook: on every start, before
the workspace's own post-build script. Its files are at
`/usr/local/lib/rostainer/plugins/archive/` in the container. A failed
rotation is a warning, and the start goes on.

Archives go to `<archive_dir>/<time>/{log,bags,database}/` and
`<archive_dir>/tar/<time>.tar.gz`. The time is the newest archived file's
modification time, in the container's timezone (UTC by default). Only the
top-level entries of each directory are considered, so a bag directory or
a launch's run directory is archived whole or not at all. Hidden entries
and symlinks (ROS 1's `latest`) stay.

## Rotating and snapshotting on demand

`rotate` and `snapshot` take the same arguments. With none, they run on
this machine. Name robots, and they run there instead:

```bash
rostainer archive rotate                      # every running dev container of the workspace
rostainer archive rotate --container my_pkg   # a container here with the plugin's files (e.g. a package's)
rostainer archive rotate all                  # every enabled robot
rostainer archive snapshot vehicles diver81   # a group, and a robot
./rostainer archive snapshot                  # on a robot, in the installed package's directory
```

Here, the archives land in `archive_dir`, which is already on your disk
through `volume_mappings`. On robots, `fetch` brings them back (or use
`fetch --rotate` / `fetch --snapshot`, below, to do both at once).

Robots are picked as `rostainer deploy` (and `fetch`) picks them: by
name, by group from `[plugins.deploy.groups]`, or `all`. On each, over
deploy's ssh connection, it runs the installed package's own `./rostainer
archive rotate` (or `snapshot`), so the robot's package must be running.
Several are reached at once, and one that fails doesn't stop the others.

Either way, the command runs inside the container, with the settings that
container (or package) was started or made with. None needs a TTY, so any
can run from cron or a systemd timer.

### Snapshots

A snapshot is `<archive_dir>/tar/<time>_snapshot.tar.gz`, laid out as a
rotation's archive (`log/`, `bags/`, `database/`). The time is when it
was taken. Nothing is moved and there's no unpacked copy, so:

- **It's an extra copy.** The next rotation archives the same logs again.
  Delete snapshots once you have them (`fetch --delete` does it for
  robots).
- **Files still being written are copied as they are.** A node's log can
  end mid-line. A bag being recorded may need repair once it's here:
  `mcap recover` for MCAP, `rosbag reindex` for a ROS 1 `.bag.active`.
  Databases in `database_dir` are copied safely, as in a rotation.
- **It waits for a rotation that's running** (up to 10 minutes), so
  nothing is moved away while it's tarred. A rotation that starts during
  a snapshot is skipped, as when two rotations overlap.

## Fetching

```bash
rostainer archive fetch                     # every archive not already here, from every enabled robot
rostainer archive fetch all                 # the same
rostainer archive fetch divers --latest     # only the newest archive, from a group
rostainer archive fetch robot1 --since 2026-10-23T00:00:00Z
rostainer archive fetch robot1 --rotate --delete
rostainer archive fetch robot1 --snapshot --latest   # the logs as they are right now
rostainer archive fetch --yes               # don't ask (cron, scripts)
```

Robots are picked as `rostainer deploy` picks them: by name, by group from
`[plugins.deploy.groups]`, or `all`. Unlike `rotate` and `snapshot`,
`fetch` only works with robots (this machine's archives are already
here), so with no robots named it means `all`. Several are reached at
once, and one that fails doesn't stop the others.

On each robot, `fetch` finds the package's container (`./rostainer
container`), and where `archive_dir` is mounted from on the robot
(`docker inspect`). It then downloads the tarballs into
`<download_dir>/<target>/`, or `--output-dir DIR`.

- `--latest` takes only the newest tarball, and `--since TIME` every
  tarball modified at or after TIME (an ISO 8601 time with a timezone).
  Either one says which older tarballs it leaves out that aren't here yet:
  a container start archives the session before it, so a session's logs
  can be in an archive older than the newest one (made by later restarts).
- It first looks on every robot, then says how much it will download, all
  robots together, and asks once, as apt does: `Need to get 1.2 GB in 5
  archives (laptop71: 3, 1.1 GB; laptop72: 2, 96 MB)` `Do you want to
  continue? [Y/n]`. Nothing new, nothing to ask. `-y`/`--yes` doesn't ask;
  without a terminal to ask in, it needs `--yes`.
- `--rotate` rotates first, in the package's running container
  (`./rostainer archive rotate`, with the package's own settings).
  `--snapshot` takes a snapshot first instead. With `--latest`, that's
  all it downloads: the logs as they are now.
- `--delete` deletes each tarball on the robot once it's here and verified,
  after checking the robot's copy again. The unpacked directories stay.

In a terminal, each robot's row shows how far its downloads are, as
`rostainer deploy` shows a pull: `Downloading 2 of 5: 12.4 of 35.5 MB
(35%), 120.0 kB/s, 4m 10s left`. The rate is over the last 20 seconds.

On a link that drops, a download carries on from where it stopped: only
what's missing is sent again (`tail -c +N` over ssh, so robots need
nothing more). It keeps carrying on for as long as each attempt gets
something, waiting deploy's `connect_retry_delay` in between. It gives up
after `connect_attempts` attempts in a row that get nothing. What came
stays (as a hidden `.part` file next to the download), so the next
`fetch` carries on from there, and its `Need to get` counts only what's
missing.

Each download is checked against the robot's SHA-256 before it takes its
name, so a file is never left half-written. A `.part` left from something
else fails that check and is dropped, and the next fetch starts over. A tarball that's already here
with the same hash is skipped. One that's here but different is never
overwritten.

`fetch` uses the settings of this checkout: keep `archive_dir` as it was
when the robot's package was made.

## Tests

```bash
python -m unittest discover tests
```
