# Audit Logs **Audit Logs** allows Auditors to monitor user operations in their deployment. > [!NOTE] > 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 | | | |-----------------------------------------------------------------|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | AIProvider
create, write, delete | |
Field Tracked
base_url true
created_at false
deleted true
display_name true
enabled 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
| | 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
last_turn_summary 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](https://coder.com/docs/reference/api/audit.md#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](https://coder.com/docs/reference/cli/server.md#--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](https://coder.com/docs/reference/cli/server.md#--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 > [!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. ### 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](https://coder.com/docs/admin/setup/data-retention.md). ### 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 > [!NOTE] > `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 > [!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. ```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](https://coder.com/docs/admin/licensing.md), and is automatically enabled.

Field	Tracked
base_url	true
created_at	false
deleted	true
display_name	true
enabled	true
id	true
name	true
settings	true
settings_key_id	false
type	true
updated_at	false

Field	Tracked
api_key	true
api_key_key_id	false
created_at	false
id	true
provider_id	true
updated_at	false

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