# Audit Logs **Audit Logs** allows Auditors to monitor user operations in their deployment. Audit logs require a [Premium license](https://coder.com/pricing#compare-plans). For more details, [contact your account team](https://coder.com/contact). ## Tracked Events We track the following resources: | Resource | | | | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | APIKey
login, logout, register, create, write, delete | |
Field Tracked
allow\_list false
created\_at true
expires\_at true
hashed\_secret false
id false
ip\_address false
last\_used true
lifetime\_seconds false
login\_type false
scopes false
token\_name false
updated\_at false
user\_id true
| | AiSeatState
create | |
Field Tracked
first\_used\_at true
last\_event\_description true
last\_event\_type true
last\_used\_at false
updated\_at false
user\_id true
| | AuditOAuthConvertState
| |
Field Tracked
created\_at true
expires\_at true
from\_login\_type true
to\_login\_type true
user\_id true
| | Group
create, write, delete | |
Field Tracked
avatar\_url true
chat\_spend\_limit\_micros true
display\_name true
id true
members true
name true
organization\_id false
quota\_allowance true
source false
| | AuditableOrganizationMember
| |
Field Tracked
created\_at true
organization\_id false
roles true
updated\_at true
user\_id true
username true
| | Chat
create, write | |
Field Tracked
agent\_id false
archived true
build\_id false
client\_type false
created\_at false
dynamic\_tools false
heartbeat\_at false
id true
labels true
last\_error false
last\_injected\_context false
last\_model\_config\_id false
last\_read\_message\_id false
mcp\_server\_ids true
mode true
organization\_id false
owner\_id true
parent\_chat\_id false
pin\_order true
plan\_mode false
root\_chat\_id false
started\_at false
status false
title true
updated\_at false
worker\_id false
workspace\_id true
| | CustomRole
| |
Field Tracked
created\_at false
display\_name true
id false
is\_system false
member\_permissions true
name true
org\_permissions true
organization\_id false
site\_permissions true
updated\_at false
user\_permissions true
| | GitSSHKey
create | |
Field Tracked
created\_at false
private\_key true
public\_key true
updated\_at false
user\_id true
| | GroupSyncSettings
| |
Field Tracked
auto\_create\_missing\_groups true
field true
legacy\_group\_name\_mapping false
mapping true
regex\_filter true
| | HealthSettings
| |
Field Tracked
dismissed\_healthchecks true
id false
| | License
create, delete | |
Field Tracked
exp true
id false
jwt false
uploaded\_at true
uuid true
| | NotificationTemplate
| |
Field Tracked
actions true
body\_template true
enabled\_by\_default true
group true
id false
kind true
method true
name true
title\_template true
| | NotificationsSettings
| |
Field Tracked
id false
notifier\_paused true
| | OAuth2ProviderApp
| |
Field Tracked
callback\_url true
client\_id\_issued\_at false
client\_secret\_expires\_at true
client\_type true
client\_uri true
contacts true
created\_at false
dynamically\_registered true
grant\_types true
icon true
id false
jwks true
jwks\_uri true
logo\_uri true
name true
policy\_uri true
redirect\_uris true
registration\_access\_token true
registration\_client\_uri true
response\_types true
scope true
software\_id true
software\_version true
token\_endpoint\_auth\_method true
tos\_uri true
updated\_at false
| | OAuth2ProviderAppSecret
| |
Field Tracked
app\_id false
created\_at false
display\_secret false
hashed\_secret false
id false
last\_used\_at false
secret\_prefix false
| | Organization
| |
Field Tracked
created\_at false
deleted true
description true
display\_name true
icon true
id false
is\_default true
name true
shareable\_workspace\_owners true
updated\_at true
| | OrganizationSyncSettings
| |
Field Tracked
assign\_default true
field true
mapping true
| | PrebuildsSettings
| |
Field Tracked
id false
reconciliation\_paused true
| | RoleSyncSettings
| |
Field Tracked
field true
mapping true
| | TaskTable
| |
Field Tracked
created\_at false
deleted\_at false
display\_name true
id true
name true
organization\_id false
owner\_id true
prompt true
template\_parameters true
template\_version\_id true
workspace\_id true
| | Template
write, delete | |
Field Tracked
active\_version\_id true
activity\_bump true
allow\_user\_autostart true
allow\_user\_autostop true
allow\_user\_cancel\_workspace\_jobs true
autostart\_block\_days\_of\_week true
autostop\_requirement\_days\_of\_week true
autostop\_requirement\_weeks true
cors\_behavior true
created\_at false
created\_by true
created\_by\_avatar\_url false
created\_by\_name false
created\_by\_username false
default\_ttl true
deleted false
deprecated true
description true
disable\_module\_cache true
display\_name true
failure\_ttl true
group\_acl true
icon true
id true
max\_port\_sharing\_level true
name true
organization\_display\_name false
organization\_icon false
organization\_id false
organization\_name false
provisioner true
require\_active\_version true
time\_til\_dormant true
time\_til\_dormant\_autodelete true
updated\_at false
use\_classic\_parameter\_flow true
user\_acl true
| | TemplateVersion
create, write | |
Field Tracked
archived true
created\_at false
created\_by true
created\_by\_avatar\_url false
created\_by\_name false
created\_by\_username false
external\_auth\_providers false
has\_ai\_task false
has\_external\_agent false
id true
job\_id false
message false
name true
organization\_id false
readme true
source\_example\_id false
template\_id true
updated\_at false
| | User
create, write, delete | |
Field Tracked
avatar\_url false
chat\_spend\_limit\_micros true
created\_at false
deleted true
email true
github\_com\_user\_id false
hashed\_one\_time\_passcode false
hashed\_password true
id true
is\_service\_account true
is\_system true
last\_seen\_at false
login\_type true
name true
one\_time\_passcode\_expires\_at true
quiet\_hours\_schedule true
rbac\_roles true
status true
updated\_at false
username true
| | UserSecret
create, write, delete | |
Field Tracked
created\_at false
description true
env\_name true
file\_path true
id true
name true
updated\_at false
user\_id true
value true
value\_key\_id false
| | WorkspaceBuild
start, stop | |
Field Tracked
build\_number false
created\_at false
daily\_cost false
deadline false
has\_ai\_task false
has\_external\_agent false
id false
initiator\_by\_avatar\_url false
initiator\_by\_name false
initiator\_by\_username false
initiator\_id false
job\_id false
max\_deadline false
reason false
template\_version\_id true
template\_version\_preset\_id false
transition false
updated\_at false
workspace\_id false
| | WorkspaceProxy
| |
Field Tracked
created\_at true
deleted false
derp\_enabled true
derp\_only true
display\_name true
icon true
id true
name true
region\_id true
token\_hashed\_secret true
updated\_at false
url true
version true
wildcard\_hostname true
| | WorkspaceTable
| |
Field Tracked
automatic\_updates true
autostart\_schedule true
created\_at false
deleted false
deleting\_at true
dormant\_at true
favorite true
group\_acl true
id true
last\_used\_at false
name true
next\_start\_at true
organization\_id false
owner\_id true
template\_id true
ttl true
updated\_at false
user\_acl true
| ## 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](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#ResourceType). * `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](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#AuditAction). * `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](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#BuildReason) 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](/docs/@v2.33.6/reference/api/audit/#get-audit-logs) 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](https://splunk.com). Example of a [JSON formatted](/docs/@v2.33.6/reference/cli/server/#--log-json) audit log entry: ```json { "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](/docs/@v2.33.6/reference/cli/server/#--log-human) audit log entry: ```console 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= UserAgent= 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 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](/docs/@v2.33.6/admin/setup/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. ```sql 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 `VACUUM FULL` acquires an exclusive lock on the table, blocking all reads and writes. For more information, see the [PostgreSQL VACUUM documentation](https://www.postgresql.org/docs/current/sql-vacuum.html). 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: ```bash kubectl scale deployment coder --replicas=0 -n coder ``` * **Terminate lingering connections** before running the `VACUUM` operation to ensure it starts immediately ```sql SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = 'coder' AND pid <> pg_backend_pid(); ``` * **Only `coderd` needs to scale down** - external provisioner daemons, workspace proxies, and workspace agents don't connect to the database directly. After the vacuum completes, scale coderd back up: ```bash kubectl scale deployment coder --replicas= -n coder ``` ### Backup/Archive Consider exporting or archiving these records before deletion: ```sql -- 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 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. ```sql 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](/docs/@v2.33.6/admin/licensing/), and is automatically enabled.

Field	Tracked
allow\_list	false
created\_at	true
expires\_at	true
hashed\_secret	false
id	false
ip\_address	false
last\_used	true
lifetime\_seconds	false
login\_type	false
scopes	false
token\_name	false
updated\_at	false
user\_id	true

Field	Tracked
first\_used\_at	true
last\_event\_description	true
last\_event\_type	true
last\_used\_at	false
updated\_at	false
user\_id	true

Field	Tracked
avatar\_url	true
chat\_spend\_limit\_micros	true
display\_name	true
id	true
members	true
name	true
organization\_id	false
quota\_allowance	true
source	false

Field	Tracked
agent\_id	false
archived	true
build\_id	false
client\_type	false
created\_at	false
dynamic\_tools	false
heartbeat\_at	false
id	true
labels	true
last\_error	false
last\_injected\_context	false
last\_model\_config\_id	false
last\_read\_message\_id	false
mcp\_server\_ids	true
mode	true
organization\_id	false
owner\_id	true
parent\_chat\_id	false
pin\_order	true
plan\_mode	false
root\_chat\_id	false
started\_at	false
status	false
title	true
updated\_at	false
worker\_id	false
workspace\_id	true

Field	Tracked
created\_at	false
private\_key	true
public\_key	true
updated\_at	false
user\_id	true

Field	Tracked
auto\_create\_missing\_groups	true
field	true
legacy\_group\_name\_mapping	false
mapping	true
regex\_filter	true

Field	Tracked
actions	true
body\_template	true
enabled\_by\_default	true
group	true
id	false
kind	true
method	true
name	true
title\_template	true

Field	Tracked
callback\_url	true
client\_id\_issued\_at	false
client\_secret\_expires\_at	true
client\_type	true
client\_uri	true
contacts	true
created\_at	false
dynamically\_registered	true
grant\_types	true
icon	true
id	false
jwks	true
jwks\_uri	true
logo\_uri	true
name	true
policy\_uri	true
redirect\_uris	true
registration\_access\_token	true
registration\_client\_uri	true
response\_types	true
scope	true
software\_id	true
software\_version	true
token\_endpoint\_auth\_method	true
tos\_uri	true
updated\_at	false

Field	Tracked
app\_id	false
created\_at	false
display\_secret	false
hashed\_secret	false
id	false
last\_used\_at	false
secret\_prefix	false

Field	Tracked
created\_at	false
deleted	true
description	true
display\_name	true
icon	true
id	false
is\_default	true
name	true
shareable\_workspace\_owners	true
updated\_at	true

Field	Tracked
created\_at	false
deleted\_at	false
display\_name	true
id	true
name	true
organization\_id	false
owner\_id	true
prompt	true
template\_parameters	true
template\_version\_id	true
workspace\_id	true

Field	Tracked
active\_version\_id	true
activity\_bump	true
allow\_user\_autostart	true
allow\_user\_autostop	true
allow\_user\_cancel\_workspace\_jobs	true
autostart\_block\_days\_of\_week	true
autostop\_requirement\_days\_of\_week	true
autostop\_requirement\_weeks	true
cors\_behavior	true
created\_at	false
created\_by	true
created\_by\_avatar\_url	false
created\_by\_name	false
created\_by\_username	false
default\_ttl	true
deleted	false
deprecated	true
description	true
disable\_module\_cache	true
display\_name	true
failure\_ttl	true
group\_acl	true
icon	true
id	true
max\_port\_sharing\_level	true
name	true
organization\_display\_name	false
organization\_icon	false
organization\_id	false
organization\_name	false
provisioner	true
require\_active\_version	true
time\_til\_dormant	true
time\_til\_dormant\_autodelete	true
updated\_at	false
use\_classic\_parameter\_flow	true
user\_acl	true

Field	Tracked
build\_number	false
created\_at	false
daily\_cost	false
deadline	false
has\_ai\_task	false
has\_external\_agent	false
id	false
initiator\_by\_avatar\_url	false
initiator\_by\_name	false
initiator\_by\_username	false
initiator\_id	false
job\_id	false
max\_deadline	false
reason	false
template\_version\_id	true
template\_version\_preset\_id	false
transition	false
updated\_at	false
workspace\_id	false

Field	Tracked
automatic\_updates	true
autostart\_schedule	true
created\_at	false
deleted	false
deleting\_at	true
dormant\_at	true
favorite	true
group\_acl	true
id	true
last\_used\_at	false
name	true
next\_start\_at	true
organization\_id	false
owner\_id	true
template\_id	true
ttl	true
updated\_at	false
user\_acl	true