Data Retention & Housekeeping

An Athena server accumulates operational data as it runs — resolved alerts, session recordings, rotating log files, finished commands, scheduled-job history, and rows for agents that never come back. On an air-gapped, on-premises box with a fixed disk, it helps to know exactly what grows, what removes it, whether that removal happens automatically or is something you have to schedule, and which setting governs each window. This page pulls all of that into one place. Each area also has its own dedicated page for the full detail — this is the map that ties them together.

Nothing here touches your evidence trail

The audit log is deliberately not pruned by any of these windows — it is your permanent record of who did what. And every automatic purge below writes its own audit entry, so cleanup is itself accountable. Move audit data off-box with audit forwarding if you need it long-term.

Two kinds of cleanup#

Athena removes aged data in two different ways, and the difference matters when you are planning capacity:

Automatic sweeps run on their own, on a built-in hourly timer, as soon as the server is running. You configure the age window; the sweep does the rest. Today two things are cleaned this way: resolved alerts and session recordings.
Scheduled cleanups only run when you create a recurring scheduled job for them. Until you do, the data is kept indefinitely. Log files, finished commands, and inactive-agent rows are cleaned this way, along with database backups and dynamic-collection refresh.

A useful rule of thumb: the automatic sweeps protect you even if you never open the console again; the scheduled cleanups are opt-in, so on a fresh install nothing is being deleted until you set up the jobs.

At a glance#

Every place data builds up, what clears it, and the default window:

What grows	Cleared by	How	Setting	Default
Resolved alerts	Alert retention sweep	Automatic · hourly	`Alerts:RetentionDays`	90 days
Session recordings (video files)	Recording retention sweep	Automatic · hourly	`Recording:RetentionDays`	30 days
Server log files	`LogCleanup` scheduled job	Scheduled	Log Retention (`logRetentionDays`)	30 days
Finished commands & their results	`CommandsCleanup` scheduled job	Scheduled	Command History Retention (`commandRetentionDays`)	30 days
Inactive agents (offline, no heartbeat)	`AgentsCleanup` scheduled job	Scheduled	Cleanup Inactive Days (`cleanupInactiveDays`)	30 days
Scheduled-job history	Job history retention	Scheduled	History Retention (`historyRetentionDays`)	30 days
Database backups (files on disk)	You (manual)	Manual	—	Kept until removed

The rest of this page explains each row: where the setting lives, exactly what is deleted, and how to turn a window off entirely.

Resolved alerts#

A background sweep runs about once an hour and permanently removes resolved alerts whose start time is older than Alerts:RetentionDays (default 90). This keeps the Alerts history from growing without bound while leaving every live incident intact.

Firing and acknowledged alerts are never aged out

The sweep only ever deletes alerts in the Resolved state. An alert that is still firing — or that has been acknowledged but not yet resolved — is a live incident and is kept no matter how old it is. Only a manual delete by an Admin can remove one of those.

Where it is set: this window is a configuration-file value (Alerts:RetentionDays), not one of the Settings-screen fields — set it in appsettings.json or with the environment variable Alerts__RetentionDays.
Keep alerts forever: set the value to 0 (or leave it blank). The sweep then does nothing and no alert is ever purged.
Audited: each purge is written to the audit trail so the removal of history is itself on the record.

See Monitoring & Alerts → Alert retention for the full picture.

Session recordings#

Session recordings are video files on disk and are the fastest-growing thing on most servers. A second background sweep runs about once an hour and purges recordings whose start time is older than Recording:RetentionDays (default 30), deleting the video file first and then its metadata row, and writing an audit entry for each removal.

Where it is set: Recording:RetentionDays in appsettings.json, or the environment variable Recording__RetentionDays.
Keep recordings forever: set it to 0 (or blank) — the sweep becomes a no-op.
Cap individual size, too: recordings also have a per-session size ceiling (Recording:MaxSessionSizeMB, default 2048 MB) so a single long session can't run away with the disk.

See Session Recordings → Storage & retention for storage paths and the recording lifecycle.

These two run on their own

Alert and recording sweeps are the only cleanups that need no configuration beyond the age window — they start with the server. Everything below is opt-in and won't run until you create a scheduled job for it.

Server log files#

The server writes rotating .log files to its log directory (see Server Logging). These are cleaned by a LogCleanup scheduled job: when it runs, it deletes *.log files older than the Log Retention window (logRetentionDays, default 30) from the log directory.

Where the window is set: Settings → Logging in the console (the Retention Days field), or over the API / PowerShell under the Logging settings category.
What actually deletes them: the LogCleanup job. Create it once (for example, a nightly recurrence) on the Scheduled Jobs screen. Without that job, the retention window is just a number and old logs stay on disk.

Finished commands#

Every remote command you run leaves a record — the command, its target, output, and exit code. A CommandsCleanup scheduled job removes commands (and their results) older than the Command History Retention window (commandRetentionDays, default 30).

Where the window is set: Settings → Scheduler (see Scheduler Settings), field Command History Retention.
What actually deletes them: the CommandsCleanup job — create it on the Scheduled Jobs screen.

Inactive agents#

Machines that were decommissioned or re-imaged leave behind an agent row that will never send another heartbeat. An AgentsCleanup scheduled job removes agents that are not currently online and whose last heartbeat is older than the Cleanup Inactive Days window (cleanupInactiveDays, default 30).

Only offline, stale agents are removed

An agent that is online is never removed by this job, however long ago it first enrolled — the check requires the machine to be both offline and past the window. This is a convenience cleanup, not a substitute for retiring an agent deliberately when you decommission a machine.

Where the window is set: Settings → Scheduler (see Scheduler Settings), field Cleanup Inactive Days.
What actually deletes them: the AgentsCleanup job.

Scheduled-job history#

The scheduler keeps an execution history for your recurring jobs so you can see when each one last ran and whether it succeeded. The History Retention window (historyRetentionDays, default 30) on Settings → Scheduler governs how long that history is kept. See Scheduler Settings for this and the other server-wide scheduler defaults.

Database backups#

Backups produced by the DatabaseBackup scheduled job (or on demand) are written as files to the backup directory and are not pruned automatically — Athena never deletes a backup for you. That is deliberate: a backup you didn't expect to lose is worse than a full disk. Decide your own rotation and remove old backup files as part of your operational routine. See Database Backup & Maintenance.

Turning a window off#

There are two ways to stop something being deleted, depending on which kind of cleanup it is:

Automatic sweeps (alerts, recordings): set the retention value to 0 (or leave it blank) in appsettings.json. The sweep then keeps everything forever.
Scheduled cleanups (logs, commands, inactive agents, backups): simply don't create the corresponding scheduled job, or pause it. The retention window has no effect until a job runs it.

Keeping everything has a cost

Disabling retention on an air-gapped server means recordings, logs and command history grow until the disk fills. Watch free space on the Server Health screen and size your volumes for the busiest data — usually session recordings.

PowerShell#

The Athena PowerShell module reads and writes the Settings-driven retention windows (logs, commands, inactive agents, job history) with Get-AthenaSettings and Set-AthenaSettings. Sign in with Connect-Athena as an Admin first. The alert and recording sweep windows live in appsettings.json instead, so they are not set this way.

# Connect as an Admin
Connect-Athena -Server "athena.contoso.com"

# Keep server logs for 14 days, commands for 60, remove agents offline 45+ days
$logging = Get-AthenaSettings -Category Logging
$logging.LogRetentionDays = 14
Set-AthenaSettings -Category Logging -Settings $logging

$scheduler = Get-AthenaSettings -Category Scheduler
$scheduler.CommandRetentionDays = 60
$scheduler.CleanupInactiveDays  = 45
$scheduler.HistoryRetentionDays = 30
Set-AthenaSettings -Category Scheduler -Settings $scheduler

Set-AthenaSettings supports -WhatIf/-Confirm, so you can preview a change or gate it in a script. Remember these windows only take effect when the matching cleanup job runs.

Quick answers#

Question	Answer
What cleans up on its own, out of the box?	Only resolved alerts (90 days) and session recordings (30 days), on an hourly sweep.
Why aren't my old logs / commands being deleted?	Those are scheduled cleanups — you must create a `LogCleanup` / `CommandsCleanup` job.
Will Athena delete my database backups?	No. Backup files are kept until you remove them.
Is the audit log ever pruned by these windows?	No — the audit trail is not aged out here, and each purge is itself audited.
How do I keep something forever?	Set the retention value to `0` (automatic sweeps) or don't schedule the cleanup job (scheduled cleanups).
Which data grows fastest?	Usually session recordings — size that volume accordingly.

Scheduled Jobs — create the LogCleanup, CommandsCleanup, AgentsCleanup and DatabaseBackup jobs that run the scheduled cleanups.
Scheduler Settings — the command-history, inactive-agent and job-history retention windows.
Session Recordings — the recording storage sweep and per-session size cap.
Monitoring & Alerts — the resolved-alert sweep.
Server Logging — where log files are written and how the log retention window applies.
Database Backup & Maintenance — backups and database upkeep.
Audit & SIEM and Audit Forwarding — the record that is not pruned, and how to ship it off-box.