Skip to content

Monthly rollup and retention purge

The RollupManager service runs automatically on hook_cron (no Drush command). Each cron run does two things, in order:

  1. Roll up completed months. Any past month (not the current one) that has raw rows in ai_metering_usage but no completed rollup gets aggregated into ai_metering_rollup, grouped by user, provider, model, operation, provider type, and caller (sums of calls, input/output/cached tokens, cost, and latency). The operation is idempotent: existing rollup rows for that month are deleted and reinserted, so a rerun after late-arriving raw rows simply refreshes the aggregate. Once a month's rollup succeeds it is recorded in State under ai_metering.rollup_completed_months and is never rolled up again.
  2. Purge expired raw rows, governed by the Raw usage log retention (days) setting (usage_retention_days, in the Quota defaults section of Settings; 0 disables purging). Deletion runs in batches of 10,000 rows, capped at 20 batches per cron run so a large backlog never times out a single cron cycle. The purge cutoff is always clamped to the end of the newest completed rollup month, so raw rows can never be deleted before their month has been safely aggregated, making "purge before rollup" data loss structurally impossible.

Both dashboards read the raw usage table for the current (in-progress) month and the rollup table for any completed month, so purging old raw rows never erases historical totals on either dashboard, only the row-level detail behind them (and the per-call usage log, which is raw-log-only).