HomeAdministrationSecurityAudit Logs

Audit Logs

Premium

On this page

Audit Logs allows Auditors to monitor user operations in their deployment.

Note

Audit logs require a Premium license. For more details, contact your account team.

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

Example of a JSON formatted audit log entry:

{
    "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 audit log entry:

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=<nil>  UserAgent=<nil>  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.

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.

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.

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:

kubectl scale deployment coder --replicas=0 -n coder
Terminate lingering connections before running the VACUUM operation to ensure it starts immediately

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:

kubectl scale deployment coder --replicas= -n coder

Backup/Archive

Consider exporting or archiving these records before deletion:

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

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, and is automatically enabled.