+ Bounds how much Docker history is stored. Raw per-sample container metrics are
+ kept for the raw window, then rolled up into hourly averages kept for the
+ rollup window; lifecycle events are kept for the events window. Applied by the
+ hourly cleanup task — a change takes effect on its next run.
+
+
+ {{ days("Raw metrics", "docker_metrics_raw_days", "docker.retention.metrics_raw_days",
+ "Keep per-sample container CPU/memory points this long, then roll up to hourly.") }}
+ {{ days("Rolled-up metrics", "docker_metrics_rollup_days", "docker.retention.metrics_rollup_days",
+ "Keep the hourly-averaged series this long for multi-day history.") }}
+ {{ days("Lifecycle events", "docker_events_days", "docker.retention.events_days",
+ "Keep container start/stop/die/health history this long.") }}
+
+
Takes effect immediately — no restart.
diff --git a/tests/integration/test_docker.py b/tests/integration/test_docker.py
index 21accd5..8e98265 100644
--- a/tests/integration/test_docker.py
+++ b/tests/integration/test_docker.py
@@ -86,6 +86,15 @@ def _persist_fn(app):
return persist_host_docker
+def _retention_fn(app):
+ """Resolve run_docker_retention via capability (or direct import if unloaded)."""
+ from steward.core.capabilities import has_capability, get_capability
+ if has_capability("docker.run_retention"):
+ return get_capability("docker.run_retention").fn
+ from plugins.docker.retention import run_docker_retention
+ return run_docker_retention
+
+
@_NEEDS_DB
def test_persist_scopes_containers_by_host(app):
from sqlalchemy import text
@@ -219,3 +228,90 @@ def test_swarm_topology_persisted(app):
assert svc[0] == "replicated" and svc[1] == 3 and svc[2] == 2 and svc[3] == "nginx"
assert "n1" in svc[4] # placement JSON carries the node id
assert node[0] == "manager" and node[2] == "ready" and node[3] is True
+
+
+@_NEEDS_DB
+def test_retention_rollup_and_prune(app):
+ """Old raw metrics roll up to hourly averages then delete; stale rollup +
+ events prune; recent rows survive."""
+ from sqlalchemy import text
+ from steward.models.hosts import Host
+
+ run_retention = _retention_fn(app)
+ now = datetime(2026, 6, 19, 12, 0, 0, tzinfo=timezone.utc)
+ # One old hour (10 days back) with three samples → one rolled-up bucket.
+ old_hour = datetime(2026, 6, 9, 9, 0, 0, tzinfo=timezone.utc)
+ recent = datetime(2026, 6, 19, 11, 0, 0, tzinfo=timezone.utc) # inside raw window
+ ancient_bucket = datetime(2026, 3, 1, 0, 0, 0, tzinfo=timezone.utc) # > rollup window
+ old_event = datetime(2026, 5, 1, 0, 0, 0, tzinfo=timezone.utc) # > events window
+ new_event = datetime(2026, 6, 18, 0, 0, 0, tzinfo=timezone.utc) # inside events window
+
+ async def _go():
+ async with app.db_sessionmaker() as s:
+ async with s.begin():
+ await s.execute(text("DELETE FROM docker_metrics_hourly"))
+ await s.execute(text("DELETE FROM docker_metrics"))
+ await s.execute(text("DELETE FROM docker_events"))
+ h = Host(id=str(uuid.uuid4()), name="ret", address="10.7.7.7")
+ s.add(h)
+ await s.flush()
+ hid = h.id
+ # Three raw samples in the old hour: cpu 10/20/30, mem 40/50/60.
+ for i, (ts, cpu, mem, usage) in enumerate([
+ (old_hour, 10.0, 40.0, 100),
+ (old_hour.replace(second=30), 20.0, 50.0, 200),
+ (old_hour.replace(minute=1), 30.0, 60.0, 300),
+ ]):
+ await s.execute(text(
+ "INSERT INTO docker_metrics "
+ "(id, host_id, container_name, scraped_at, cpu_pct, mem_pct, mem_usage_bytes) "
+ "VALUES (:id,:h,'web',:ts,:cpu,:mem,:usage)"),
+ {"id": str(uuid.uuid4()), "h": hid, "ts": ts,
+ "cpu": cpu, "mem": mem, "usage": usage})
+ # A recent sample (within the 7-day raw window) — must survive raw.
+ await s.execute(text(
+ "INSERT INTO docker_metrics "
+ "(id, host_id, container_name, scraped_at, cpu_pct, mem_pct, mem_usage_bytes) "
+ "VALUES (:id,:h,'web',:ts,5.0,5.0,50)"),
+ {"id": str(uuid.uuid4()), "h": hid, "ts": recent})
+ # A pre-existing rollup row older than the 90-day rollup window.
+ await s.execute(text(
+ "INSERT INTO docker_metrics_hourly "
+ "(id, host_id, container_name, bucket, cpu_pct, mem_pct, mem_usage_bytes, sample_count) "
+ "VALUES (:id,:h,'ancient',:b,1,1,1,1)"),
+ {"id": str(uuid.uuid4()), "h": hid, "b": ancient_bucket})
+ # Events either side of the 30-day events window.
+ for ev_at, ev in [(old_event, "stop"), (new_event, "start")]:
+ await s.execute(text(
+ "INSERT INTO docker_events (id, host_id, container_name, event, at) "
+ "VALUES (:id,:h,'web',:ev,:at)"),
+ {"id": str(uuid.uuid4()), "h": hid, "ev": ev, "at": ev_at})
+
+ async with s.begin():
+ counts = await run_retention(
+ s, events_days=30, metrics_raw_days=7,
+ metrics_rollup_days=90, now=now,
+ )
+
+ raw_left = (await s.execute(text(
+ "SELECT COUNT(*) FROM docker_metrics WHERE host_id=:h"), {"h": hid})).scalar()
+ bucket = (await s.execute(text(
+ "SELECT cpu_pct, mem_pct, mem_usage_bytes, sample_count "
+ "FROM docker_metrics_hourly WHERE host_id=:h AND container_name='web'"),
+ {"h": hid})).first()
+ ancient_left = (await s.execute(text(
+ "SELECT COUNT(*) FROM docker_metrics_hourly "
+ "WHERE host_id=:h AND container_name='ancient'"), {"h": hid})).scalar()
+ events_left = (await s.execute(text(
+ "SELECT COUNT(*) FROM docker_events WHERE host_id=:h"), {"h": hid})).scalar()
+ return counts, raw_left, bucket, ancient_left, events_left
+
+ counts, raw_left, bucket, ancient_left, events_left = asyncio.run(_go())
+ assert raw_left == 1 # only the recent sample survives raw
+ assert bucket is not None
+ assert bucket[0] == 20.0 and bucket[1] == 50.0 # avg cpu / mem over the 3 samples
+ assert bucket[2] == 200 and bucket[3] == 3 # avg usage + sample_count
+ assert ancient_left == 0 # stale rollup pruned
+ assert events_left == 1 # only the in-window event survives
+ assert counts["buckets_rolled"] == 1 and counts["raw_rows_rolled"] == 3
+ assert counts["events_pruned"] == 1 and counts["rollup_pruned"] == 1
diff --git a/tests/plugins/docker/test_retention.py b/tests/plugins/docker/test_retention.py
new file mode 100644
index 0000000..262d9c3
--- /dev/null
+++ b/tests/plugins/docker/test_retention.py
@@ -0,0 +1,45 @@
+"""Unit tests for the docker plugin's retention cutoff/bucketing helpers.
+
+_hour_floor and _rollup_cutoff are pure (no DB); retention.py imports its models
+lazily inside run_docker_retention, so importing them here doesn't register ORM
+tables — safe for the no-DB unit lane. The DB-backed rollup/prune itself is
+covered in tests/integration/test_docker.py.
+"""
+from datetime import datetime, timedelta, timezone
+
+from plugins.docker.retention import _hour_floor, _rollup_cutoff
+
+
+def test_hour_floor_drops_sub_hour_components():
+ dt = datetime(2026, 6, 19, 14, 37, 52, 123456, tzinfo=timezone.utc)
+ assert _hour_floor(dt) == datetime(2026, 6, 19, 14, 0, 0, 0, tzinfo=timezone.utc)
+
+
+def test_hour_floor_on_exact_hour_is_identity():
+ dt = datetime(2026, 6, 19, 14, 0, 0, tzinfo=timezone.utc)
+ assert _hour_floor(dt) == dt
+
+
+def test_rollup_cutoff_is_hour_aligned():
+ now = datetime(2026, 6, 19, 14, 37, 52, tzinfo=timezone.utc)
+ cutoff = _rollup_cutoff(now, raw_days=7)
+ # 7 days back from 14:37 is 14:37 on the 12th, floored to 14:00.
+ assert cutoff == datetime(2026, 6, 12, 14, 0, 0, tzinfo=timezone.utc)
+ # No sub-hour remainder — only whole elapsed hours get rolled up.
+ assert cutoff.minute == 0 and cutoff.second == 0 and cutoff.microsecond == 0
+
+
+def test_rollup_cutoff_scales_with_raw_days():
+ now = datetime(2026, 6, 19, 0, 0, 0, tzinfo=timezone.utc)
+ assert _rollup_cutoff(now, 1) == now - timedelta(days=1)
+ assert _rollup_cutoff(now, 30) == now - timedelta(days=30)
+
+
+def test_rollup_cutoff_sample_classification():
+ """A sample inside the raw window is kept; one before the aligned cutoff rolls up."""
+ now = datetime(2026, 6, 19, 14, 37, 0, tzinfo=timezone.utc)
+ cutoff = _rollup_cutoff(now, raw_days=7)
+ recent = datetime(2026, 6, 19, 12, 0, 0, tzinfo=timezone.utc) # within window
+ old = datetime(2026, 6, 10, 9, 0, 0, tzinfo=timezone.utc) # older than cutoff
+ assert not (recent < cutoff) # kept raw
+ assert old < cutoff # rolled up