Timeline Audit Retention

What It Checks

Verifies that Timeline exposes retention policies for every unified-audit classification (none, personal, sensitive, and restricted) and that each configured retention window meets the minimum platform baseline. The check warns when Timeline cannot be reached, the response cannot be parsed, a classification is missing, or a retention period is below the minimum.

Why It Matters

Audit retention is part of Stella Ops evidence accountability. If retention windows are missing or too short, release, security, and tenant-audit evidence can expire before operators, auditors, or incident responders can prove what happened.

Common Causes

Timeline:Url or Services:Timeline:Url points to the wrong Timeline service endpoint.
The tenant has an override in timeline.audit_retention_policies with a shorter retention window than the platform baseline.
Timeline migrations did not converge on startup, leaving the retention table or defaults absent.

How to Fix

Docker Compose

# Check the Timeline service and configured URL.
docker compose -f devops/compose/docker-compose.stella-ops.yml ps timeline
docker compose -f devops/compose/docker-compose.stella-ops.yml logs --tail=100 timeline

# Inspect the current retention policy.
docker compose -f devops/compose/docker-compose.stella-ops.yml exec postgres \
  psql -U stellaops -d stellaops_platform \
  -c "SELECT tenant_id, data_classification, retention_days FROM timeline.audit_retention_policies ORDER BY tenant_id, data_classification;"

Bare Metal / systemd

sudo systemctl status stellaops-timeline
journalctl -u stellaops-timeline -n 100 --no-pager

psql "$STELLAOPS_POSTGRES" \
  -c "SELECT tenant_id, data_classification, retention_days FROM timeline.audit_retention_policies ORDER BY tenant_id, data_classification;"

Kubernetes / Helm

kubectl -n stellaops get deploy timeline
kubectl -n stellaops logs deploy/timeline --tail=100

kubectl -n stellaops exec deploy/postgres -- \
  psql -U stellaops -d stellaops_platform \
  -c "SELECT tenant_id, data_classification, retention_days FROM timeline.audit_retention_policies ORDER BY tenant_id, data_classification;"

Verification

stella doctor run --check check.compliance.timeline-audit-retention

check.compliance.audit-readiness - verifies broader audit evidence readiness.
check.compliance.evidence-integrity - verifies evidence has not been tampered with.