chore: remove global retention fallback for workspace agent logs

mafredri · mafredri · commit 9ccd75db0ce5 · 2025-12-02T10:59:05.000Z
Workspace agent logs retention is now explicit - it's enabled when
--workspace-agent-logs-retention is set to a non-zero duration
(default 7d), and disabled when set to 0. No fallback to global
retention.
diff --git a/coderd/database/dbpurge/dbpurge.go b/coderd/database/dbpurge/dbpurge.go
@@ -67,9 +67,6 @@ func New(ctx context.Context, logger slog.Logger, db database.Store, vals *coder
 			}
 
 			workspaceAgentLogsRetention := vals.Retention.WorkspaceAgentLogs.Value()
-			if workspaceAgentLogsRetention == 0 {
-				workspaceAgentLogsRetention = vals.Retention.Global.Value()
-			}
 			if workspaceAgentLogsRetention > 0 {
 				deleteOldWorkspaceAgentLogsBefore := start.Add(-workspaceAgentLogsRetention)
 				if err := tx.DeleteOldWorkspaceAgentLogs(ctx, deleteOldWorkspaceAgentLogsBefore); err != nil {
diff --git a/coderd/database/dbpurge/dbpurge_test.go b/coderd/database/dbpurge/dbpurge_test.go
@@ -423,15 +423,7 @@ func TestDeleteOldWorkspaceAgentLogsRetention(t *testing.T) {
 			logsAge:       60 * 24 * time.Hour, // 60 days ago
 			expectDeleted: false,
 		},
-		{
-			name: "GlobalRetentionFallback",
-			retentionConfig: codersdk.RetentionConfig{
-				Global:             serpent.Duration(14 * 24 * time.Hour), // 14 days global
-				WorkspaceAgentLogs: serpent.Duration(0),                   // Not set, falls back to global
-			},
-			logsAge:       15 * 24 * time.Hour, // 15 days ago
-			expectDeleted: true,
-		},
+
 		{
 			name: "CustomRetention30Days",
 			retentionConfig: codersdk.RetentionConfig{
diff --git a/coderd/database/queries/workspaceagents.sql b/coderd/database/queries/workspaceagents.sql
@@ -199,7 +199,7 @@ INSERT INTO
 -- name: GetWorkspaceAgentLogSourcesByAgentIDs :many
 SELECT * FROM workspace_agent_log_sources WHERE workspace_agent_id = ANY(@ids :: uuid [ ]);
 
--- If an agent hasn't connected in the last 7 days, we purge it's logs.
+-- If an agent hasn't connected within the retention period, we purge its logs.
 -- Exception: if the logs are related to the latest build, we keep those around.
 -- Logs can take up a lot of space, so it's important we clean up frequently.
 -- name: DeleteOldWorkspaceAgentLogs :exec
diff --git a/docs/admin/setup/data-retention.md b/docs/admin/setup/data-retention.md
@@ -26,12 +26,12 @@ a YAML configuration file.
 
 ### Settings
 
-| Setting              | CLI Flag                           | Environment Variable                   | Default        | Description                              |
-|----------------------|------------------------------------|----------------------------------------|----------------|------------------------------------------|
-| Audit Logs           | `--audit-logs-retention`           | `CODER_AUDIT_LOGS_RETENTION`           | `0` (disabled) | How long to retain Audit Log entries     |
-| Connection Logs      | `--connection-logs-retention`      | `CODER_CONNECTION_LOGS_RETENTION`      | `0` (disabled) | How long to retain Connection Logs       |
-| API Keys             | `--api-keys-retention`             | `CODER_API_KEYS_RETENTION`             | `7d`           | How long to retain expired API keys      |
-| Workspace Agent Logs | `--workspace-agent-logs-retention` | `CODER_WORKSPACE_AGENT_LOGS_RETENTION` | `7d`           | How long to retain workspace agent logs  |
+| Setting              | CLI Flag                           | Environment Variable                   | Default        | Description                             |
+|----------------------|------------------------------------|----------------------------------------|----------------|-----------------------------------------|
+| Audit Logs           | `--audit-logs-retention`           | `CODER_AUDIT_LOGS_RETENTION`           | `0` (disabled) | How long to retain Audit Log entries    |
+| Connection Logs      | `--connection-logs-retention`      | `CODER_CONNECTION_LOGS_RETENTION`      | `0` (disabled) | How long to retain Connection Logs      |
+| API Keys             | `--api-keys-retention`             | `CODER_API_KEYS_RETENTION`             | `7d`           | How long to retain expired API keys     |
+| Workspace Agent Logs | `--workspace-agent-logs-retention` | `CODER_WORKSPACE_AGENT_LOGS_RETENTION` | `7d`           | How long to retain workspace agent logs |
 
 ### Duration Format
 
@@ -107,13 +107,14 @@ error message when users attempt to use an expired key.
 
 ### Workspace Agent Logs Behavior
 
-Workspace agent logs are retained based on the retention period, but **logs from
-the latest build of each workspace are always retained** regardless of age. This
-ensures you can always debug issues with active workspaces.
+Workspace agent logs are deleted based on when the agent last connected, not the
+age of the logs themselves. **Logs from the latest build of each workspace are
+always retained** regardless of when the agent last connected. This ensures you
+can always debug issues with active workspaces.
 
-Only logs from non-latest workspace builds that are older than the retention
-period are deleted. Setting `--workspace-agent-logs-retention=7d` keeps all logs
-from the latest build plus logs from previous builds for up to 7 days.
+For non-latest builds, logs are deleted if the agent hasn't connected within the
+retention period. Setting `--workspace-agent-logs-retention=7d` deletes logs for
+agents that haven't connected in 7 days (excluding those from the latest build).
 
 ## Best Practices
 
@@ -183,4 +184,4 @@ containing the table name (e.g., `audit_logs`, `connection_logs`, `api_keys`).
 - [Audit Logs](../security/audit-logs.md): Learn about Audit Logs and manual
   purge procedures.
 - [Connection Logs](../monitoring/connection-logs.md): Learn about Connection
-  Logs and monitoring.
+  Logs and monitoring.
diff --git a/docs/reference/api/general.md b/docs/reference/api/general.md
diff --git a/docs/reference/api/schemas.md b/docs/reference/api/schemas.md

Original file line number	Diff line number	Diff line change
`@@ -67,9 +67,6 @@ func New(ctx context.Context, logger slog.Logger, db database.Store, vals *coder`
`67`	`67`	`}`
`68`	`68`
`69`	`69`	`workspaceAgentLogsRetention := vals.Retention.WorkspaceAgentLogs.Value()`
`70`		`- if workspaceAgentLogsRetention == 0 {`
`71`		`- workspaceAgentLogsRetention = vals.Retention.Global.Value()`
`72`		`- }`
`73`	`70`	`if workspaceAgentLogsRetention > 0 {`
`74`	`71`	`deleteOldWorkspaceAgentLogsBefore := start.Add(-workspaceAgentLogsRetention)`
`75`	`72`	`if err := tx.DeleteOldWorkspaceAgentLogs(ctx, deleteOldWorkspaceAgentLogsBefore); err != nil {`