HomeAdministrationSecurityAudit Logs

Audit Logs

Premium

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

APIKey
login, logout, register, create, 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
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

CustomRole

Field	Tracked

created_at	false
display_name	true
id	false
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
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
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
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
created_at	false
deleted	true
email	true
github_com_user_id	false
hashed_one_time_passcode	false
hashed_password	true
id	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

WorkspaceBuild
start, stop

Field	Tracked

ai_task_sidebar_app_id	false
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
provisioner_state	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.

Audit Logs are not automatically purged from the database, though they 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 mainteance 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.

Tracked Events

How to Filter Audit Logs

Capturing/Exporting Audit Logs

REST API

Service Logs

Purging Old Audit Logs

Maintenance Procedures for the Audit Logs Table

Backup/Archive

Permanent Deletion

How to Enable Audit Logs

On this page