# Audit Logs (Premium) **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 | | | |-----------------------------------------------------------------|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 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 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](../../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](../../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](../../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](../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: ```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 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](../licensing/index.md), and is automatically enabled.