Audit Logs
Audit Logs allows Auditors to monitor user operations in their deployment.
Note
Audit logs require a Premium license. For more details, contact your account team.
Tracked Events
We track the following resources:
Resource | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
APIKey login, logout, register, create, delete |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AuditOAuthConvertState |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Group create, write, delete |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
AuditableOrganizationMember |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
CustomRole |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
GitSSHKey create |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
GroupSyncSettings |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
HealthSettings |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
License create, delete |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
NotificationTemplate |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
NotificationsSettings |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
OAuth2ProviderApp |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
OAuth2ProviderAppSecret |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Organization |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
OrganizationSyncSettings |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
PrebuildsSettings |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
RoleSyncSettings |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Template write, delete |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
TemplateVersion create, write |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
User create, write, delete |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
WorkspaceBuild start, stop |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
WorkspaceProxy |
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
WorkspaceTable |
|
How to Filter Audit Logs
You can filter audit logs by the following parameters:
resource_type
- The type of the resource, such as a workspace, template, or user. For more resource types, refer to the CoderSDK package documentation.resource_id
- The ID of the resource.resource_target
- The name of the resource. Can be used instead ofresource_id
.action
- The action applied to a resource, such ascreate
ordelete
. For more actions, refer to the CoderSDK package documentation.username
- The username of the user who triggered the action. You can also useme
as a convenient alias for the logged-in user.email
- The email of the user who triggered the action.date_from
- The inclusive start date with formatYYYY-MM-DD
.date_to
- The inclusive end date with formatYYYY-MM-DD
.build_reason
- The reason for the workspace build, ifresource_type
isworkspace_build
. Refer to the CoderSDK package documentation for a list of valid build reasons.
Capturing/Exporting Audit Logs
In addition to the Coder dashboard, there are multiple ways to consume or query audit trails.
REST API
You can retrieve audit logs via the Coder API.
Visit the
get-audit-logs
endpoint documentation
for details.
Service Logs
Audit trails are also dispatched as service logs and can be captured and categorized using any log management tool such as Splunk.
Example of a JSON formatted audit log entry:
{
"ts": "2023-06-13T03:45:37.294730279Z",
"level": "INFO",
"msg": "audit_log",
"caller": "/home/coder/coder/enterprise/audit/backends/slog.go:38",
"func": "github.com/coder/coder/v2/enterprise/audit/backends.(*SlogExporter).ExportStruct",
"logger_names": ["coderd"],
"fields": {
"ID": "033a9ffa-b54d-4c10-8ec3-2aaf9e6d741a",
"Time": "2023-06-13T03:45:37.288506Z",
"UserID": "6c405053-27e3-484a-9ad7-bcb64e7bfde6",
"OrganizationID": "00000000-0000-0000-0000-000000000000",
"Ip": null,
"UserAgent": null,
"ResourceType": "workspace_build",
"ResourceID": "ca5647e0-ef50-4202-a246-717e04447380",
"ResourceTarget": "",
"Action": "start",
"Diff": {},
"StatusCode": 200,
"AdditionalFields": {
"workspace_name": "linux-container",
"build_number": "9",
"build_reason": "initiator",
"workspace_owner": ""
},
"RequestID": "bb791ac3-f6ee-4da8-8ec2-f54e87013e93",
"ResourceIcon": ""
}
}
Example of a human readable audit log entry:
2023-06-13 03:43:29.233 [info] coderd: audit_log ID=95f7c392-da3e-480c-a579-8909f145fbe2 Time="2023-06-13T03:43:29.230422Z" UserID=6c405053-27e3-484a-9ad7-bcb64e7bfde6 OrganizationID=00000000-0000-0000-0000-000000000000 Ip=<nil> UserAgent=<nil> ResourceType=workspace_build ResourceID=988ae133-5b73-41e3-a55e-e1e9d3ef0b66 ResourceTarget="" Action=start Diff="{}" StatusCode=200 AdditionalFields="{\"workspace_name\":\"linux-container\",\"build_number\":\"7\",\"build_reason\":\"initiator\",\"workspace_owner\":\"\"}" RequestID=9682b1b5-7b9f-4bf2-9a39-9463f8e41cd6 ResourceIcon=""
Purging Old Audit Logs
Warning
Audit Logs provide critical security and compliance information. Purging Audit Logs may impact your organization's ability to investigate security incidents or meet compliance requirements. Consult your security and compliance teams before purging any audit data.
Audit Logs are not automatically purged from the database, though they can account for a large amount of disk usage.
Use the following query to determine the amount of disk space used by the audit_logs
table.
SELECT
relname AS table_name,
pg_size_pretty(pg_total_relation_size(relid)) AS total_size,
pg_size_pretty(pg_relation_size(relid)) AS table_size,
pg_size_pretty(pg_indexes_size(relid)) AS indexes_size,
(SELECT COUNT(*) FROM audit_logs) AS total_records
FROM pg_catalog.pg_statio_user_tables
WHERE relname = 'audit_logs'
ORDER BY pg_total_relation_size(relid) DESC;
Should you wish to purge these records, it is safe to do so. This can only be done by running SQL queries
directly against the audit_logs
table in the database. We advise users to only purge old records (>1yr)
and in accordance with your compliance requirements.
Backup/Archive
Consider exporting or archiving these records before deletion:
-- Export to CSV
COPY (SELECT * FROM audit_logs WHERE time < CURRENT_TIMESTAMP - INTERVAL '1 year')
TO '/path/to/audit_logs_archive.csv' DELIMITER ',' CSV HEADER;
-- Copy to archive table
CREATE TABLE audit_logs_archive AS
SELECT * FROM audit_logs WHERE time < CURRENT_TIMESTAMP - INTERVAL '1 year';
Permanent Deletion
Note
For large audit_logs
tables, consider running the DELETE
operation during maintenance windows as it may impact
database performance. You can also batch the deletions to reduce lock time.
DELETE FROM audit_logs WHERE time < CURRENT_TIMESTAMP - INTERVAL '1 year';
-- Consider running `VACUUM VERBOSE audit_logs` afterwards for large datasets to reclaim disk space.
How to Enable Audit Logs
This feature is only available with a Premium license, and is automatically enabled.