# 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 [#tracked-events] 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. ### AIGatewayKey [#aigatewaykey] Actions: `create`, `delete`

Field	Tracked
`created_at`	No
`hashed_secret`	Yes
`id`	Yes
`last_heartbeat_at`	No
`name`	Yes
`secret_prefix`	Yes

### AIProvider [#aiprovider] Actions: `create`, `write`, `delete`

Field	Tracked
`base_url`	Yes
`created_at`	No
`deleted`	Yes
`display_name`	Yes
`enabled`	Yes
`icon`	Yes
`id`	Yes
`name`	Yes
`settings`	Yes
`settings_key_id`	No
`type`	Yes
`updated_at`	No

### AIProviderKey [#aiproviderkey] Actions: `create`, `delete`

Field	Tracked
`api_key`	Yes
`api_key_key_id`	No
`created_at`	No
`id`	Yes
`provider_id`	Yes
`updated_at`	No

### AISeatState [#aiseatstate] Actions: `create`

Field	Tracked
`first_used_at`	Yes
`last_event_description`	Yes
`last_event_type`	Yes
`last_used_at`	No
`updated_at`	No
`user_id`	Yes

### APIKey [#apikey] Actions: `login`, `logout`, `register`, `create`, `write`, `delete`

Field	Tracked
`allow_list`	No
`created_at`	Yes
`expires_at`	Yes
`hashed_secret`	No
`id`	No
`ip_address`	No
`last_used`	Yes
`lifetime_seconds`	No
`login_type`	No
`scopes`	No
`token_name`	No
`updated_at`	No
`user_id`	Yes

### AuditOAuthConvertState [#auditoauthconvertstate]

Field	Tracked
`created_at`	Yes
`expires_at`	Yes
`from_login_type`	Yes
`to_login_type`	Yes
`user_id`	Yes

### AuditableChatProjectInstructions [#auditablechatprojectinstructions] Actions: `write`, `delete`

Field	Tracked
`created_at`	No
`instructions`	Yes
`organization_id`	No
`project_id`	No
`project_name`	No
`updated_at`	No
`updated_by`	No

### Group [#group] Actions: `create`, `write`, `delete`

Field	Tracked
`avatar_url`	Yes
`chat_spend_limit_micros`	Yes
`display_name`	Yes
`id`	Yes
`members`	Yes
`name`	Yes
`organization_id`	No
`quota_allowance`	Yes
`source`	No

### AuditableGroupAIBudget [#auditablegroupaibudget] Actions: `write`, `delete`

Field	Tracked
`created_at`	No
`group_id`	No
`group_name`	No
`spend_limit`	Yes
`spend_limit_micros`	No
`updated_at`	No

### AuditableOrganizationMember [#auditableorganizationmember]

Field	Tracked
`created_at`	Yes
`organization_id`	No
`roles`	Yes
`updated_at`	Yes
`user_id`	Yes
`username`	Yes

### AuditableOrganizationSkill [#auditableorganizationskill] Actions: `create`, `write`, `delete`

Field	Tracked
`content`	Yes
`created_at`	No
`description`	Yes
`enabled`	Yes
`group_acl`	Yes
`id`	Yes
`name`	Yes
`organization_id`	Yes
`project_id`	Yes
`updated_at`	No
`user_acl`	Yes
`user_id`	Yes

### AuditableUserAIBudgetOverride [#auditableuseraibudgetoverride] Actions: `write`, `delete`

Field	Tracked
`created_at`	No
`group_id`	Yes
`group_name`	Yes
`spend_limit`	Yes
`spend_limit_micros`	No
`updated_at`	No
`user_id`	No
`username`	No

### Chat [#chat] Actions: `create`, `write`

Field	Tracked
`agent_id`	No
`archived`	Yes
`build_id`	No
`client_type`	No
`compaction_requested_at`	No
`context_aggregate_hash`	No
`context_dirty_resources`	No
`context_dirty_since`	No
`context_error`	No
`created_at`	No
`dynamic_tools`	No
`generation_attempt`	No
`group_acl`	Yes
`heartbeat_at`	No
`history_version`	No
`id`	Yes
`labels`	Yes
`last_error`	No
`last_model_config_id`	No
`last_read_message_id`	No
`last_reasoning_effort`	No
`last_turn_summary`	No
`mcp_server_ids`	Yes
`mode`	Yes
`organization_id`	No
`owner_id`	Yes
`owner_name`	No
`owner_username`	No
`parent_chat_id`	No
`pin_order`	Yes
`plan_mode`	No
`project_id`	Yes
`queue_version`	No
`requires_action_deadline_at`	No
`retry_state`	No
`retry_state_version`	No
`root_chat_id`	No
`runner_id`	No
`snapshot_version`	No
`started_at`	No
`status`	No
`summary`	No
`summary_generated_at`	No
`title`	Yes
`title_source`	Yes
`title_updated_at`	No
`updated_at`	No
`user_acl`	Yes
`worker_id`	No
`workspace_id`	Yes

### ChatInstructionSettings [#chatinstructionsettings] Actions: `write`

Field	Tracked
`id`	No
`include_default_system_prompt`	Yes
`include_default_system_prompt_set`	Yes
`name`	No
`plan_mode_instructions`	Yes
`system_prompt`	Yes

### ChatModelConfig [#chatmodelconfig] Actions: `create`, `write`, `delete`

Field	Tracked
`ai_provider_id`	Yes
`compression_threshold`	Yes
`context_limit`	Yes
`created_at`	No
`created_by`	Yes
`deleted`	Yes
`deleted_at`	No
`display_name`	Yes
`enabled`	Yes
`group_acl`	Yes
`id`	No
`is_default`	Yes
`model`	Yes
`options`	Yes
`organization_id`	No
`updated_at`	No
`updated_by`	Yes
`user_acl`	Yes

### ChatOperationalSettings [#chatoperationalsettings] Actions: `write`

Field	Tracked
`chat_auto_archive_days`	Yes
`chat_debug_retention_days`	Yes
`chat_retention_days`	Yes
`computer_use_provider`	Yes
`debug_logging_allow_users`	Yes
`id`	No
`personal_model_overrides_enabled`	Yes
`workspace_ttl`	Yes

### ChatOrganizationSystemPrompt [#chatorganizationsystemprompt] Actions: `write`

Field	Tracked
`created_at`	No
`organization_id`	No
`system_prompt`	Yes
`updated_at`	No

### ChatProject [#chatproject] Actions: `create`, `write`, `delete`

Field	Tracked
`created_at`	No
`description`	Yes
`group_acl`	Yes
`icon`	Yes
`id`	Yes
`name`	Yes
`organization_id`	Yes
`owner_id`	Yes
`updated_at`	No
`user_acl`	Yes

### ChatProjectMemory [#chatprojectmemory] Actions: `create`, `delete`

Field	Tracked
`body`	Yes
`created_at`	No
`created_by`	Yes
`description`	Yes
`id`	Yes
`name`	Yes
`organization_id`	Yes
`project_id`	Yes

### CustomRole [#customrole]

Field	Tracked
`created_at`	No
`display_name`	Yes
`id`	No
`is_system`	No
`member_permissions`	Yes
`name`	Yes
`org_permissions`	Yes
`organization_id`	No
`site_permissions`	Yes
`updated_at`	No
`user_permissions`	Yes

### ExperimentRule [#experimentrule] Actions: `write`

Field	Tracked
`condition`	Yes
`experiment`	Yes
`id`	No
`mode`	Yes
`revision`	Yes

### GitSSHKey [#gitsshkey] Actions: `create`

Field	Tracked
`created_at`	No
`private_key`	Yes
`private_key_key_id`	No
`public_key`	Yes
`updated_at`	No
`user_id`	Yes

### GroupSyncSettings [#groupsyncsettings]

Field	Tracked
`auto_create_missing_groups`	Yes
`field`	Yes
`legacy_group_name_mapping`	No
`mapping`	Yes
`regex_filter`	Yes

### HealthSettings [#healthsettings]

Field	Tracked
`dismissed_healthchecks`	Yes
`id`	No

### License [#license] Actions: `create`, `delete`

Field	Tracked
`exp`	Yes
`id`	No
`jwt`	No
`uploaded_at`	Yes
`uuid`	Yes

### MCPServerConfig [#mcpserverconfig] Actions: `create`, `write`, `delete`

Field	Tracked
`allow_in_plan_mode`	Yes
`api_key_header`	Yes
`api_key_value`	Yes
`api_key_value_key_id`	No
`auth_type`	Yes
`availability`	Yes
`created_at`	No
`created_by`	Yes
`custom_headers`	Yes
`custom_headers_key_id`	No
`description`	Yes
`display_name`	Yes
`enabled`	Yes
`forward_coder_headers`	Yes
`group_acl`	Yes
`icon_url`	Yes
`id`	No
`model_intent`	Yes
`oauth2_auth_url`	Yes
`oauth2_client_id`	Yes
`oauth2_client_secret`	Yes
`oauth2_client_secret_key_id`	No
`oauth2_resource`	Yes
`oauth2_revocation_url`	Yes
`oauth2_scopes`	Yes
`oauth2_token_url`	Yes
`organization_id`	No
`signing_secret`	Yes
`signing_secret_key_id`	No
`slug`	Yes
`tool_allow_list`	Yes
`tool_deny_list`	Yes
`transport`	Yes
`updated_at`	No
`updated_by`	Yes
`url`	Yes
`user_acl`	Yes

### NotificationTemplate [#notificationtemplate]

Field	Tracked
`actions`	Yes
`body_template`	Yes
`enabled_by_default`	Yes
`group`	Yes
`id`	No
`kind`	Yes
`method`	Yes
`name`	Yes
`title_template`	Yes

### NotificationsSettings [#notificationssettings]

Field	Tracked
`id`	No
`notifier_paused`	Yes

### OAuth2ProviderApp [#oauth2providerapp]

Field	Tracked
`callback_url`	Yes
`client_id_issued_at`	No
`client_secret_expires_at`	Yes
`client_type`	Yes
`client_uri`	Yes
`contacts`	Yes
`created_at`	No
`dynamically_registered`	Yes
`grant_types`	Yes
`icon`	Yes
`id`	No
`jwks`	Yes
`jwks_uri`	Yes
`logo_uri`	Yes
`name`	Yes
`policy_uri`	Yes
`redirect_uris`	Yes
`registration_access_token`	Yes
`registration_client_uri`	Yes
`response_types`	Yes
`scope`	Yes
`software_id`	Yes
`software_version`	Yes
`token_endpoint_auth_method`	Yes
`tos_uri`	Yes
`updated_at`	No

### OAuth2ProviderAppSecret [#oauth2providerappsecret]

Field	Tracked
`app_id`	No
`created_at`	No
`display_secret`	No
`hashed_secret`	No
`id`	No
`last_used_at`	No
`secret_prefix`	No

### OAuth2ProviderSettings [#oauth2providersettings]

Field	Tracked
`dynamic_client_registration_enabled`	Yes
`id`	No

### Organization [#organization]

Field	Tracked
`created_at`	No
`default_org_member_roles`	Yes
`deleted`	Yes
`description`	Yes
`display_name`	Yes
`icon`	Yes
`id`	No
`is_default`	Yes
`name`	Yes
`shareable_workspace_owners`	Yes
`updated_at`	Yes

### OrganizationSyncSettings [#organizationsyncsettings]

Field	Tracked
`assign_default`	Yes
`field`	Yes
`mapping`	Yes

### PrebuildsSettings [#prebuildssettings]

Field	Tracked
`id`	No
`reconciliation_paused`	Yes

### RoleSyncSettings [#rolesyncsettings]

Field	Tracked
`field`	Yes
`mapping`	Yes

### Skill [#skill] Actions: `create`, `write`, `delete`

Field	Tracked
`content`	Yes
`created_at`	No
`description`	Yes
`enabled`	Yes
`group_acl`	Yes
`id`	Yes
`name`	Yes
`organization_id`	Yes
`project_id`	Yes
`updated_at`	No
`user_acl`	Yes
`user_id`	Yes

### Template [#template] Actions: `write`, `delete`

Field	Tracked
`active_version_id`	Yes
`activity_bump`	Yes
`agents_allowed`	Yes
`allow_user_autostart`	Yes
`allow_user_autostop`	Yes
`allow_user_cancel_workspace_jobs`	Yes
`allow_workspace_renames`	Yes
`autostart_block_days_of_week`	Yes
`autostop_requirement_days_of_week`	Yes
`autostop_requirement_weeks`	Yes
`cors_behavior`	Yes
`created_at`	No
`created_by`	Yes
`created_by_avatar_url`	No
`created_by_name`	No
`created_by_username`	No
`default_ttl`	Yes
`deleted`	No
`deprecated`	Yes
`description`	Yes
`disable_module_cache`	Yes
`display_name`	Yes
`failure_ttl`	Yes
`group_acl`	Yes
`icon`	Yes
`id`	Yes
`max_port_sharing_level`	Yes
`name`	Yes
`organization_display_name`	No
`organization_icon`	No
`organization_id`	No
`organization_name`	No
`provisioner`	Yes
`require_active_version`	Yes
`time_til_autostop_notify`	Yes
`time_til_dormant`	Yes
`time_til_dormant_autodelete`	Yes
`updated_at`	No
`use_classic_parameter_flow`	Yes
`user_acl`	Yes

### TemplateVersion [#templateversion] Actions: `create`, `write`

Field	Tracked
`archived`	Yes
`created_at`	No
`created_by`	Yes
`created_by_avatar_url`	No
`created_by_name`	No
`created_by_username`	No
`external_auth_providers`	No
`has_external_agent`	No
`id`	Yes
`job_id`	No
`message`	No
`name`	Yes
`organization_id`	No
`readme`	Yes
`script_order_data_source_count`	No
`script_order_rule_count`	No
`source_example_id`	No
`template_id`	Yes
`updated_at`	No

### User [#user] Actions: `create`, `write`, `delete`

Field	Tracked
`avatar_url`	No
`chat_spend_limit_micros`	Yes
`created_at`	No
`deleted`	Yes
`email`	Yes
`github_com_user_id`	No
`hashed_one_time_passcode`	No
`hashed_password`	Yes
`id`	Yes
`is_service_account`	Yes
`is_system`	Yes
`last_seen_at`	No
`login_type`	Yes
`name`	Yes
`one_time_passcode_expires_at`	Yes
`quiet_hours_schedule`	Yes
`rbac_roles`	Yes
`status`	Yes
`updated_at`	No
`username`	Yes

### UserSecret [#usersecret] Actions: `create`, `write`, `delete`

Field	Tracked
`created_at`	No
`description`	Yes
`enabled`	Yes
`env_name`	Yes
`file_path`	Yes
`id`	Yes
`name`	Yes
`updated_at`	No
`user_id`	Yes
`value`	Yes
`value_key_id`	No

### WorkspaceBuild [#workspacebuild] Actions: `start`, `stop`

Field	Tracked
`build_number`	No
`created_at`	No
`daily_cost`	No
`deadline`	No
`has_external_agent`	No
`id`	No
`initiator_by_avatar_url`	No
`initiator_by_name`	No
`initiator_by_username`	No
`initiator_id`	No
`job_id`	No
`max_deadline`	No
`notified_autostop_deadline`	No
`reason`	No
`template_version_id`	Yes
`template_version_preset_id`	No
`transition`	No
`updated_at`	No
`workspace_id`	No

### WorkspaceProxy [#workspaceproxy]

Field	Tracked
`created_at`	Yes
`deleted`	No
`derp_enabled`	Yes
`derp_only`	Yes
`display_name`	Yes
`icon`	Yes
`id`	Yes
`name`	Yes
`region_id`	Yes
`token_hashed_secret`	Yes
`updated_at`	No
`url`	Yes
`version`	Yes
`wildcard_hostname`	Yes

### WorkspaceTable [#workspacetable]

Field	Tracked
`automatic_updates`	Yes
`autostart_schedule`	Yes
`created_at`	No
`deleted`	No
`deleting_at`	Yes
`dormant_at`	Yes
`favorite`	Yes
`group_acl`	Yes
`id`	Yes
`last_used_at`	No
`name`	Yes
`next_start_at`	Yes
`organization_id`	No
`owner_id`	Yes
`template_id`	Yes
`ttl`	Yes
`updated_at`	No
`user_acl`	Yes

## 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. ## Capture and export audit logs [#capture-and-export-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/@main/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/@main/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/@main/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="" ``` ## Purge old audit logs [#purge-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/@main/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/@main/install/prepare/licensing/), and is automatically enabled.