Coder powers secure, scalable development across key industries — automotive, finance, government, and technology — enabling faster builds, tighter compliance, and seamless AI adoption in enterprise-grade cloud environments.
Coder records audit log entries for the resources below.
Each section lists the actions that produce an entry, followed by the resource's fields.
When a tracked field changes, the change appears in the entry's diff, and untracked fields are left out.
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 of
resource_id.
action- The action applied to a resource, such as create or delete.
For more actions, refer to the
CoderSDK package documentation.
username - The username of the user who triggered the action. You can also
use me 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 format YYYY-MM-DD.
date_to - The inclusive end date with format YYYY-MM-DD.
build_reason - The reason for the workspace build, if resource_type is
workspace_build. Refer to the
CoderSDK package documentation
for a list of valid build reasons.
Capture and export audit logs
In addition to the Coder dashboard, there are multiple ways to consume or query
audit trails.
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.
Data Retention
Coder supports configurable retention policies that automatically purge old
Audit Logs. To enable automated purging, configure the
--audit-logs-retention flag or CODER_AUDIT_LOGS_RETENTION environment
variable. For comprehensive configuration options, see
Data Retention.
Manual Purging
Alternatively, you can purge Audit Logs manually by running SQL queries
directly against the database.
Audit Logs 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.
Maintenance Procedures for the Audit Logs Table
Note
VACUUM FULL acquires an exclusive lock on the table, blocking all reads and writes. For more information, see the PostgreSQL VACUUM documentation.
You may choose to run a VACUUM or VACUUM FULL operation on the audit logs table to reclaim disk space. If you choose to run the FULL operation, consider the following when doing so:
Run during a planned maintenance window to ensure ample time for the operation to complete and minimize impact to users
Stop all running instances of coderd to prevent connection errors while the table is locked. The actual steps for this will depend on your particular deployment setup. For example, if your coderd deployment is running on Kubernetes:
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.
