Movatterモバイル変換

[0]ホーム
URL:

Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

 Sign up
Appearance settings

Commit0825d8a

Browse files
committed
docs: add data retention documentation
Document configurable retention policies for Audit Logs, Connection Logs,and API keys. Add new data-retention.md page and update existing docs toreference it.Depends on#21021Updates#20743
1 parent0e782ee commit0825d8a

File tree

5 files changed

+208
-2
lines changed

5 files changed

+208
-2
lines changed

‎docs/admin/monitoring/connection-logs.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -106,6 +106,14 @@ connection log entry, when `code-server` is opened:
106106
[API] 2025-07-03 06:57:16.157 [info] coderd: connection_log request_id=de3f6004-6cc1-4880-a296-d7c6ca1abf75 ID=f0249951-d454-48f6-9504-e73340fa07b7 Time="2025-07-03T06:57:16.144719Z" OrganizationID=0665a54f-0b77-4a58-94aa-59646fa38a74 WorkspaceOwnerID=6dea5f8c-ecec-4cf0-a5bd-bc2c63af2efa WorkspaceID=3c0b37c8-e58c-4980-b9a1-2732410480a5 WorkspaceName=dev AgentName=main Type=workspace_app Code=200 Ip=127.0.0.1 UserAgent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" UserID=6dea5f8c-ecec-4cf0-a5bd-bc2c63af2efa SlugOrPort=code-server ConnectionID=<nil> DisconnectReason="" ConnectionStatus=connected
107107
```
108108

109+
##Data Retention
110+
111+
Coder supports configurable retention policies that automatically purge old
112+
Connection Logs. To enable automated purging, configure the
113+
`--connection-logs-retention` flag or`CODER_CONNECTION_LOGS_RETENTION`
114+
environment variable. For comprehensive configuration options, see
115+
[Data Retention](../setup/data-retention.md).
116+
109117
##How to Enable Connection Logs
110118

111119
This feature is only available with a[Premium license](../licensing/index.md).

‎docs/admin/monitoring/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,3 +22,4 @@ Learn how to install & read the docs on the
2222
Coder deployment, regardless of your monitoring stack.
2323
-[Health Check](./health-check.md): Learn about the periodic health check and
2424
error codes that run on Coder deployments.
25+
-[Connection Logs](./connection-logs.md): Monitor connections to workspaces.

‎docs/admin/security/audit-logs.md‎

Lines changed: 15 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -132,8 +132,21 @@ log entry:
132132
>Audit Logs provide critical security and compliance information. Purging Audit Logs may impact your organization's ability
133133
>to investigate security incidents or meet compliance requirements. Consult your security and compliance teams before purging any audit data.
134134
135-
Audit Logs are not automatically purged from the database, though they can account for a large amount of disk usage.
136-
Use the following query to determine the amount of disk space used by the`audit_logs` table.
135+
###Automated Retention
136+
137+
Coder supports configurable retention policies that automatically purge old
138+
Audit Logs. To enable automated purging, configure the
139+
`--audit-logs-retention` flag or`CODER_AUDIT_LOGS_RETENTION` environment
140+
variable. For comprehensive configuration options, see
141+
[Data Retention](../setup/data-retention.md).
142+
143+
###Manual Purging
144+
145+
Alternatively, you can purge Audit Logs manually by running SQL queries
146+
directly against the database.
147+
148+
Audit Logs can account for a large amount of disk usage. Use the following
149+
query to determine the amount of disk space used by the`audit_logs` table.
137150

138151
```sql
139152
SELECT

‎docs/admin/setup/data-retention.md‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
#Data Retention
2+
3+
Coder supports configurable retention policies that automatically purge old
4+
Audit Logs, Connection Logs, and API keys. These policies help manage database
5+
growth by removing records older than a specified duration.
6+
7+
##Overview
8+
9+
Large deployments can accumulate significant amounts of data over time.
10+
Retention policies help you:
11+
12+
-**Reduce database size**: Automatically remove old records to free disk space.
13+
-**Improve performance**: Smaller tables mean faster queries and backups.
14+
-**Meet compliance requirements**: Configure retention periods that align with
15+
your organization's data retention policies.
16+
17+
>[!NOTE]
18+
>Retention policies are disabled by default (set to`0`) to preserve existing
19+
>behavior. The only exception is API keys, which defaults to 7 days.
20+
21+
##Configuration
22+
23+
You can configure retention policies using CLI flags, environment variables, or
24+
a YAML configuration file.
25+
26+
###Settings
27+
28+
| Setting| CLI Flag| Environment Variable| Default| Description|
29+
| ---------------| -----------------------------| ---------------------------------| ----------------| -------------------------------------------------------------------------|
30+
| Global|`--global-retention`|`CODER_GLOBAL_RETENTION`|`0` (disabled)| Default retention for all data types. Individual settings override this.|
31+
| Audit Logs|`--audit-logs-retention`|`CODER_AUDIT_LOGS_RETENTION`|`0` (use global)| How long to retain Audit Log entries.|
32+
| Connection Logs|`--connection-logs-retention`|`CODER_CONNECTION_LOGS_RETENTION`|`0` (use global)| How long to retain Connection Log entries.|
33+
| API Keys|`--api-keys-retention`|`CODER_API_KEYS_RETENTION`|`7d`| How long to retain expired API keys.|
34+
35+
###Duration Format
36+
37+
Retention durations use Go's duration format:
38+
39+
-`24h` - 24 hours
40+
-`168h` - 7 days
41+
-`720h` - 30 days
42+
-`2160h` - 90 days
43+
-`8760h` - 365 days
44+
45+
###CLI Example
46+
47+
```bash
48+
coder server \
49+
--global-retention=2160h \
50+
--audit-logs-retention=8760h \
51+
--api-keys-retention=168h
52+
```
53+
54+
###Environment Variables Example
55+
56+
```bash
57+
export CODER_GLOBAL_RETENTION=2160h
58+
export CODER_AUDIT_LOGS_RETENTION=8760h
59+
export CODER_API_KEYS_RETENTION=168h
60+
```
61+
62+
###YAML Configuration Example
63+
64+
```yaml
65+
retention:
66+
global:2160h
67+
audit_logs:8760h
68+
connection_logs:0s
69+
api_keys:168h
70+
```
71+
72+
## How Retention Works
73+
74+
### Background Purge Process
75+
76+
Coder runs a background process that periodically deletes old records. The
77+
purge process:
78+
79+
1. Runs approximately every 10 minutes.
80+
2. Processes records in batches to avoid database lock contention.
81+
3. Deletes records older than the configured retention period.
82+
4. Logs the number of deleted records for monitoring.
83+
84+
### Effective Retention
85+
86+
For each data type, the effective retention is determined as follows:
87+
88+
1. If the individual setting is non-zero, use that value.
89+
2. If the individual setting is zero, use the global retention value.
90+
3. If both are zero, retention is disabled (data is kept indefinitely).
91+
92+
### API Keys Special Behavior
93+
94+
API key retention only affects **expired** keys. A key is deleted only when:
95+
96+
1. The key has expired (past its`expires_at` timestamp).
97+
2. The key has been expired for longer than the retention period.
98+
99+
Setting `--api-keys-retention=7d` deletes keys that expired more than 7 days
100+
ago. Active keys are never deleted by the retention policy.
101+
102+
Keeping expired keys for a short period allows Coder to return a more helpful
103+
error message when users attempt to use an expired key.
104+
105+
## Best Practices
106+
107+
### Recommended Starting Configuration
108+
109+
For most deployments, we recommend:
110+
111+
```yaml
112+
retention:
113+
global: 2160h # 90 days
114+
audit_logs: 8760h # 1 year
115+
connection_logs: 0s # Use global
116+
api_keys: 168h # 7 days
117+
```
118+
119+
### Compliance Considerations
120+
121+
> [!WARNING]
122+
> Audit Logs provide critical security and compliance information. Purging
123+
> Audit Logs may impact your organization's ability to investigate security
124+
> incidents or meet compliance requirements. Consult your security and
125+
> compliance teams before configuring Audit Log retention.
126+
127+
Common compliance frameworks have varying retention requirements:
128+
129+
- **SOC 2**: Typically requires 1 year of audit logs.
130+
- **HIPAA**: Requires 6 years for certain records.
131+
- **PCI DSS**: Requires 1 year of audit logs, with 3 months immediately
132+
available.
133+
- **GDPR**: Requires data minimization but does not specify maximum retention.
134+
135+
### External Log Aggregation
136+
137+
If you use an external log aggregation system (Splunk, Datadog, etc.), you can
138+
configure shorter retention periods in Coder since logs are preserved
139+
externally. See
140+
[Capturing/Exporting Audit Logs](../security/audit-logs.md#capturingexporting-audit-logs)
141+
for details on exporting logs.
142+
143+
### Database Maintenance
144+
145+
After enabling retention policies, you may want to run a `VACUUM` operation on
146+
your PostgreSQL database to reclaim disk space. See
147+
[Maintenance Procedures](../security/audit-logs.md#maintenance-procedures-for-the-audit-logs-table)
148+
for guidance.
149+
150+
## Disabling Retention
151+
152+
Setting a retention value to `0` means "use global retention", not "disable".
153+
To disable all automatic purging, set global to `0` and leave individual
154+
settings at `0`:
155+
156+
```yaml
157+
retention:
158+
global: 0s
159+
audit_logs: 0s
160+
connection_logs: 0s
161+
api_keys: 0s
162+
```
163+
164+
There is no way to disable retention for a specific data type while global
165+
retention is enabled. If you need to retain one data type longer than others,
166+
set its individual retention to a larger value.
167+
168+
## Monitoring
169+
170+
The purge process logs deletion counts at the `DEBUG` level. To monitor
171+
retention activity, enable debug logging or search your logs for entries
172+
containing the table name (e.g., `audit_logs`, `connection_logs`, `api_keys`).
173+
174+
## Related Documentation
175+
176+
-[Audit Logs](../security/audit-logs.md):Learn about Audit Logs and manual
177+
purge procedures.
178+
-[Connection Logs](../monitoring/connection-logs.md):Learn about Connection
179+
Logs and monitoring.

‎docs/manifest.json‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -363,6 +363,11 @@
363363
"title":"Telemetry",
364364
"description":"Learn what usage telemetry Coder collects",
365365
"path":"./admin/setup/telemetry.md"
366+
},
367+
{
368+
"title":"Data Retention",
369+
"description":"Configure data retention policies for database tables",
370+
"path":"./admin/setup/data-retention.md"
366371
}
367372
]
368373
},

0 commit comments

Comments
 (0)
[8]ページ先頭
©2009-2025 Movatter.jp