# Audit Logs (Premium) **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 [#tracked-events] We track the following resources: | Resource | | | | ----------------------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AIGatewayKey
create, delete | |

Field	Tracked
created\_at	false
hashed\_secret	true
id	true
last\_heartbeat\_at	false
name	true
secret\_prefix	true

| | AIProvider
create, write, delete | |

Field	Tracked
base\_url	true
created\_at	false
deleted	true
display\_name	true
enabled	true
icon	true
id	true
name	true
settings	true
settings\_key\_id	false
type	true
updated\_at	false

| | AIProviderKey
create, delete | |

Field	Tracked
api\_key	true
api\_key\_key\_id	false
created\_at	false
id	true
provider\_id	true
updated\_at	false

| | 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

| | 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

| | 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

| | AuditableGroupAIBudget
write, delete | |

Field	Tracked
created\_at	false
group\_id	false
group\_name	false
spend\_limit	true
spend\_limit\_micros	false
updated\_at	false

| | AuditableOrganizationMember
| |

Field	Tracked
created\_at	true
organization\_id	false
roles	true
updated\_at	true
user\_id	true
username	true

| | AuditableUserAIBudgetOverride
write, delete | |

Field	Tracked
created\_at	false
group\_id	true
group\_name	true
spend\_limit	true
spend\_limit\_micros	false
updated\_at	false
user\_id	false
username	false

| | Chat
create, write | |

Field	Tracked
agent\_id	false
archived	true
build\_id	false
client\_type	false
compaction\_requested\_at	false
context\_aggregate\_hash	false
context\_dirty\_resources	false
context\_dirty\_since	false
context\_error	false
created\_at	false
dynamic\_tools	false
generation\_attempt	false
group\_acl	true
heartbeat\_at	false
history\_version	false
id	true
labels	true
last\_error	false
last\_model\_config\_id	false
last\_read\_message\_id	false
last\_reasoning\_effort	false
last\_turn\_summary	false
mcp\_server\_ids	true
mode	true
organization\_id	false
owner\_id	true
owner\_name	false
owner\_username	false
parent\_chat\_id	false
pin\_order	true
plan\_mode	false
queue\_version	false
requires\_action\_deadline\_at	false
retry\_state	false
retry\_state\_version	false
root\_chat\_id	false
runner\_id	false
snapshot\_version	false
started\_at	false
status	false
summary	false
summary\_generated\_at	false
title	true
updated\_at	false
user\_acl	true
worker\_id	false
workspace\_id	true

| | ChatInstructionSettings
write | |

Field	Tracked
id	false
include\_default\_system\_prompt	true
include\_default\_system\_prompt\_set	true
name	false
plan\_mode\_instructions	true
system\_prompt	true

| | ChatModelConfig
create, write, delete | |

Field	Tracked
ai\_provider\_id	true
compression\_threshold	true
context\_limit	true
created\_at	false
created\_by	true
deleted	true
deleted\_at	false
display\_name	true
enabled	true
group\_acl	true
id	false
is\_default	true
model	true
options	true
organization\_id	false
updated\_at	false
updated\_by	true
user\_acl	true

| | ChatOperationalSettings
write | |

Field	Tracked
chat\_auto\_archive\_days	true
chat\_debug\_retention\_days	true
chat\_retention\_days	true
computer\_use\_provider	true
debug\_logging\_allow\_users	true
id	false
personal\_model\_overrides\_enabled	true
workspace\_ttl	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
private\_key\_key\_id	false
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

| | MCPServerConfig
create, write, delete | |

Field	Tracked
allow\_in\_plan\_mode	true
api\_key\_header	true
api\_key\_value	true
api\_key\_value\_key\_id	false
auth\_type	true
availability	true
created\_at	false
created\_by	true
custom\_headers	true
custom\_headers\_key\_id	false
description	true
display\_name	true
enabled	true
forward\_coder\_headers	true
group\_acl	true
icon\_url	true
id	false
model\_intent	true
oauth2\_auth\_url	true
oauth2\_client\_id	true
oauth2\_client\_secret	true
oauth2\_client\_secret\_key\_id	false
oauth2\_revocation\_url	true
oauth2\_scopes	true
oauth2\_token\_url	true
organization\_id	false
slug	true
tool\_allow\_list	true
tool\_deny\_list	true
transport	true
updated\_at	false
updated\_by	true
url	true
user\_acl	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

| | OAuth2ProviderSettings
| |

Field	Tracked
dynamic\_client\_registration\_enabled	true
id	false

| | Organization
| |

Field	Tracked
created\_at	false
default\_org\_member\_roles	true
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
agents\_allowed	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\_autostop\_notify	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
enabled	true
env\_name	true
file\_path	true
id	true
name	true
updated\_at	false
user\_id	true
value	true
value\_key\_id	false

| | UserSkill
create, write, delete | |

Field	Tracked
content	true
created\_at	false
description	true
id	true
name	true
updated\_at	false
user\_id	true

| | 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
notified\_autostop\_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 [#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 [#capturingexporting-audit-logs] In addition to the Coder dashboard, there are multiple ways to consume or query audit trails. ### REST API [#rest-api] You can retrieve audit logs via the Coder API. Visit the [`get-audit-logs` endpoint documentation](/beta-docs/reference/api/audit/#get-audit-logs) for details. ### Service Logs [#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](/beta-docs/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](/beta-docs/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 [#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 [#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](/beta-docs/admin/setup/data-retention/). ### Manual Purging [#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 [#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: ```sh 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: ```sh kubectl scale deployment coder --replicas= -n coder ``` ### Backup/Archive [#backuparchive] 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 [#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 [#how-to-enable-audit-logs] This feature is only available with a [Premium license](/beta-docs/admin/licensing/), and is automatically enabled.