Audit retention

Overview

Audit events stay online in the database, where the Audit log searches them directly, for a set number of days. After that, the audit retention service moves them into encrypted archive files on the server’s disk and keeps those files for a set number of years. Use Admin → Audit Retention to set both periods to match your compliance requirements, to check that archiving is healthy, and to start an archive pass yourself.

Only administrators, with admin:manage, can open this page. Other people see an Access restricted page.

Screen tour

Click to enlarge

At the bottom of the Archive health card, View the audit log opens the audit log, where each archive run is recorded.

How archiving works

• Every day at 03:00 UTC, the audit retention service runs an archive pass for every organisation.
• The pass takes the events that are older than Keep audit logs online (days), writes them to an archive file encrypted with AES-256-GCM, and verifies the file and its checksum. Only then does it remove those events from the online audit log.
• Archive files are stored on the local server disk managed by the application, in the archive directory configured for the control plane.
• Each archive file is kept for Keep archived logs (years), counted from the day it was written. After that, the next archive pass removes it.
• Each pass records audit events of its own, such as audit.archive.completed and audit.archive.expired, so the audit log shows what was archived and when.

Archived events stay searchable. Administrators switch on Include archived logs on the audit log to search them together with online events. See Include archived logs.

Change the retention policy

1. Open Admin → Audit Retention.
2. In Keep audit logs online (days), enter a whole number of days from 1 to 3,650. The default is 365.
3. In Keep archived logs (years), enter a whole number of years from 1 to 20. The default is 7.
4. Click Save retention settings. The button shows Saving…, then the page confirms Retention settings saved.

The online period must fit inside the archive period, so the number of online days can’t be more than the archive years × 365. If a value is out of range, the field shows why when you leave it, and Save retention settings stays disabled until you fix it.

The new online period applies from the next archive pass. Shortening it moves more events to the archive on that pass. Every change is recorded in the audit log as audit.retention_settings.updated, with the old and new values.

Run an archive pass now

Use Run archive now to archive eligible events without waiting for the nightly pass, for example after you shorten the online period.

Click to enlarge

1. In the Archive health card, click Run archive now.
2. Read the dialog Run archive now?. It tells you that audit logs older than the online period are moved to the local archive and kept for the archive period, and that this can’t be undone from this page.
3. Click Run archive now to start, or Cancel to close the dialog.
4. While the pass runs, the button shows Running archive…. When it finishes, the card shows one of:
   • Archive run completed.: eligible events were archived. Last successful archive and the status update.
   • No audit logs are old enough to archive yet.: every event is still inside the online period, so there was nothing to move.

Each run is recorded in the audit log as audit.archive.run_requested.

Fields

Statuses

When a pass fails, check the control plane’s archive configuration and logs, then click Run archive now to retry. A successful pass clears the failed status.

Related pages

• Audit log
• Roles and permissions