# Audit Logs

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

## Tracked Events

We track the following resources:

| <b>Resource<b>                                             |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| APIKey<br /><i>login, logout, register, create, delete</i> | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created\_at</td><td>true</td></tr><tr><td>expires\_at</td><td>true</td></tr><tr><td>hashed\_secret</td><td>false</td></tr><tr><td>id</td><td>false</td></tr><tr><td>ip\_address</td><td>false</td></tr><tr><td>last\_used</td><td>true</td></tr><tr><td>lifetime\_seconds</td><td>false</td></tr><tr><td>login\_type</td><td>false</td></tr><tr><td>scope</td><td>false</td></tr><tr><td>token\_name</td><td>false</td></tr><tr><td>updated\_at</td><td>false</td></tr><tr><td>user\_id</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| AuditOAuthConvertState<br /><i></i>                        | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created\_at</td><td>true</td></tr><tr><td>expires\_at</td><td>true</td></tr><tr><td>from\_login\_type</td><td>true</td></tr><tr><td>to\_login\_type</td><td>true</td></tr><tr><td>user\_id</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| Group<br /><i>create, write, delete</i>                    | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>avatar\_url</td><td>true</td></tr><tr><td>display\_name</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>members</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>organization\_id</td><td>false</td></tr><tr><td>quota\_allowance</td><td>true</td></tr><tr><td>source</td><td>false</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| AuditableOrganizationMember<br /><i></i>                   | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created\_at</td><td>true</td></tr><tr><td>organization\_id</td><td>false</td></tr><tr><td>roles</td><td>true</td></tr><tr><td>updated\_at</td><td>true</td></tr><tr><td>user\_id</td><td>true</td></tr><tr><td>username</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| CustomRole<br /><i></i>                                    | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created\_at</td><td>false</td></tr><tr><td>display\_name</td><td>true</td></tr><tr><td>id</td><td>false</td></tr><tr><td>name</td><td>true</td></tr><tr><td>org\_permissions</td><td>true</td></tr><tr><td>organization\_id</td><td>false</td></tr><tr><td>site\_permissions</td><td>true</td></tr><tr><td>updated\_at</td><td>false</td></tr><tr><td>user\_permissions</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| GitSSHKey<br /><i>create</i>                               | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created\_at</td><td>false</td></tr><tr><td>private\_key</td><td>true</td></tr><tr><td>public\_key</td><td>true</td></tr><tr><td>updated\_at</td><td>false</td></tr><tr><td>user\_id</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| HealthSettings<br /><i></i>                                | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>dismissed\_healthchecks</td><td>true</td></tr><tr><td>id</td><td>false</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| License<br /><i>create, delete</i>                         | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>exp</td><td>true</td></tr><tr><td>id</td><td>false</td></tr><tr><td>jwt</td><td>false</td></tr><tr><td>uploaded\_at</td><td>true</td></tr><tr><td>uuid</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| NotificationTemplate<br /><i></i>                          | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>actions</td><td>true</td></tr><tr><td>body\_template</td><td>true</td></tr><tr><td>group</td><td>true</td></tr><tr><td>id</td><td>false</td></tr><tr><td>kind</td><td>true</td></tr><tr><td>method</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>title\_template</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| NotificationsSettings<br /><i></i>                         | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>id</td><td>false</td></tr><tr><td>notifier\_paused</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| OAuth2ProviderApp<br /><i></i>                             | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>callback\_url</td><td>true</td></tr><tr><td>created\_at</td><td>false</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>id</td><td>false</td></tr><tr><td>name</td><td>true</td></tr><tr><td>updated\_at</td><td>false</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| OAuth2ProviderAppSecret<br /><i></i>                       | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>app\_id</td><td>false</td></tr><tr><td>created\_at</td><td>false</td></tr><tr><td>display\_secret</td><td>false</td></tr><tr><td>hashed\_secret</td><td>false</td></tr><tr><td>id</td><td>false</td></tr><tr><td>last\_used\_at</td><td>false</td></tr><tr><td>secret\_prefix</td><td>false</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Organization<br /><i></i>                                  | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created\_at</td><td>false</td></tr><tr><td>description</td><td>true</td></tr><tr><td>display\_name</td><td>true</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>id</td><td>false</td></tr><tr><td>is\_default</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>updated\_at</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| Template<br /><i>write, delete</i>                         | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>active\_version\_id</td><td>true</td></tr><tr><td>activity\_bump</td><td>true</td></tr><tr><td>allow\_user\_autostart</td><td>true</td></tr><tr><td>allow\_user\_autostop</td><td>true</td></tr><tr><td>allow\_user\_cancel\_workspace\_jobs</td><td>true</td></tr><tr><td>autostart\_block\_days\_of\_week</td><td>true</td></tr><tr><td>autostop\_requirement\_days\_of\_week</td><td>true</td></tr><tr><td>autostop\_requirement\_weeks</td><td>true</td></tr><tr><td>created\_at</td><td>false</td></tr><tr><td>created\_by</td><td>true</td></tr><tr><td>created\_by\_avatar\_url</td><td>false</td></tr><tr><td>created\_by\_username</td><td>false</td></tr><tr><td>default\_ttl</td><td>true</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>deprecated</td><td>true</td></tr><tr><td>description</td><td>true</td></tr><tr><td>display\_name</td><td>true</td></tr><tr><td>failure\_ttl</td><td>true</td></tr><tr><td>group\_acl</td><td>true</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>max\_port\_sharing\_level</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>organization\_display\_name</td><td>false</td></tr><tr><td>organization\_icon</td><td>false</td></tr><tr><td>organization\_id</td><td>false</td></tr><tr><td>organization\_name</td><td>false</td></tr><tr><td>provisioner</td><td>true</td></tr><tr><td>require\_active\_version</td><td>true</td></tr><tr><td>time\_til\_dormant</td><td>true</td></tr><tr><td>time\_til\_dormant\_autodelete</td><td>true</td></tr><tr><td>updated\_at</td><td>false</td></tr><tr><td>user\_acl</td><td>true</td></tr></tbody></table> |
| TemplateVersion<br /><i>create, write</i>                  | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>archived</td><td>true</td></tr><tr><td>created\_at</td><td>false</td></tr><tr><td>created\_by</td><td>true</td></tr><tr><td>created\_by\_avatar\_url</td><td>false</td></tr><tr><td>created\_by\_username</td><td>false</td></tr><tr><td>external\_auth\_providers</td><td>false</td></tr><tr><td>id</td><td>true</td></tr><tr><td>job\_id</td><td>false</td></tr><tr><td>message</td><td>false</td></tr><tr><td>name</td><td>true</td></tr><tr><td>organization\_id</td><td>false</td></tr><tr><td>readme</td><td>true</td></tr><tr><td>template\_id</td><td>true</td></tr><tr><td>updated\_at</td><td>false</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| User<br /><i>create, write, delete</i>                     | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>avatar\_url</td><td>false</td></tr><tr><td>created\_at</td><td>false</td></tr><tr><td>deleted</td><td>true</td></tr><tr><td>email</td><td>true</td></tr><tr><td>github\_com\_user\_id</td><td>false</td></tr><tr><td>hashed\_one\_time\_passcode</td><td>false</td></tr><tr><td>hashed\_password</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>last\_seen\_at</td><td>false</td></tr><tr><td>login\_type</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>one\_time\_passcode\_expires\_at</td><td>true</td></tr><tr><td>quiet\_hours\_schedule</td><td>true</td></tr><tr><td>rbac\_roles</td><td>true</td></tr><tr><td>status</td><td>true</td></tr><tr><td>theme\_preference</td><td>false</td></tr><tr><td>updated\_at</td><td>false</td></tr><tr><td>username</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| WorkspaceBuild<br /><i>start, stop</i>                     | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>build\_number</td><td>false</td></tr><tr><td>created\_at</td><td>false</td></tr><tr><td>daily\_cost</td><td>false</td></tr><tr><td>deadline</td><td>false</td></tr><tr><td>id</td><td>false</td></tr><tr><td>initiator\_by\_avatar\_url</td><td>false</td></tr><tr><td>initiator\_by\_username</td><td>false</td></tr><tr><td>initiator\_id</td><td>false</td></tr><tr><td>job\_id</td><td>false</td></tr><tr><td>max\_deadline</td><td>false</td></tr><tr><td>provisioner\_state</td><td>false</td></tr><tr><td>reason</td><td>false</td></tr><tr><td>template\_version\_id</td><td>true</td></tr><tr><td>transition</td><td>false</td></tr><tr><td>updated\_at</td><td>false</td></tr><tr><td>workspace\_id</td><td>false</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| WorkspaceProxy<br /><i></i>                                | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>created\_at</td><td>true</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>derp\_enabled</td><td>true</td></tr><tr><td>derp\_only</td><td>true</td></tr><tr><td>display\_name</td><td>true</td></tr><tr><td>icon</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>name</td><td>true</td></tr><tr><td>region\_id</td><td>true</td></tr><tr><td>token\_hashed\_secret</td><td>true</td></tr><tr><td>updated\_at</td><td>false</td></tr><tr><td>url</td><td>true</td></tr><tr><td>version</td><td>true</td></tr><tr><td>wildcard\_hostname</td><td>true</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| WorkspaceTable<br /><i></i>                                | <table><thead><tr><th>Field</th><th>Tracked</th></tr></thead><tbody><tr><td>automatic\_updates</td><td>true</td></tr><tr><td>autostart\_schedule</td><td>true</td></tr><tr><td>created\_at</td><td>false</td></tr><tr><td>deleted</td><td>false</td></tr><tr><td>deleting\_at</td><td>true</td></tr><tr><td>dormant\_at</td><td>true</td></tr><tr><td>favorite</td><td>true</td></tr><tr><td>id</td><td>true</td></tr><tr><td>last\_used\_at</td><td>false</td></tr><tr><td>name</td><td>true</td></tr><tr><td>organization\_id</td><td>false</td></tr><tr><td>owner\_id</td><td>true</td></tr><tr><td>template\_id</td><td>true</td></tr><tr><td>ttl</td><td>true</td></tr><tr><td>updated\_at</td><td>false</td></tr></tbody></table>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |

## Filtering logs

In the Coder UI you can filter your audit logs using the pre-defined filter or
by using the Coder's filter query like the examples below:

* `resource_type:workspace action:delete` to find deleted workspaces
* `resource_type:template action:create` to find created templates

The supported filters are:

* `resource_type` - The type of the resource. It can be a workspace, template,
  user, etc. You can
  [find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#ResourceType)
  all the resource types that are supported.
* `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. You can
  [find here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#AuditAction)
  all the actions that are supported.
* `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` - To be used with `resource_type:workspace_build`, the
  [initiator](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#BuildReason)
  behind the build start or stop.

## Capturing/Exporting Audit Logs

In addition to the user interface, there are multiple ways to consume or query
audit trails.

## REST API

Audit logs can be accessed through our REST API. You can find detailed
information about this in our
[endpoint documentation](/docs/@v2.17.3/reference/api/audit/#get-audit-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](/docs/@v2.17.3/reference/cli/server/#--log-json) audit
log entry:

```json
{
	"ts": "2023-06-13T03:45:37.294730279Z",
	"level": "INFO",
	"msg": "audit_log",
	"caller": "/home/runner/work/coder/coder/enterprise/audit/backends/slog.go:36",
	"func": "github.com/coder/coder/enterprise/audit/backends.slogBackend.Export",
	"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": "{IPNet:{IP:\u003cnil\u003e Mask:\u003cnil\u003e} Valid:false}",
		"UserAgent": "{String: Valid:false}",
		"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](/docs/@v2.17.3/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=<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=""
```

## Enabling this feature

This feature is only available with an premium license.
[Learn more](/docs/@v2.17.3/admin/licensing/)
