Skip to content

Commit 3a92c1f

Browse files
ethanndicksonethanndickson
committed
docs: add connection logs
1 parent 9ab9c52 commit 3a92c1f

File tree

2 files changed

+107
-0
lines changed

2 files changed

+107
-0
lines changed

‎docs/admin/security/connection-logs.md

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Connection Logs
2+
3+
Connection Logs allows **Auditors** to monitor workspace agent connections.
4+
5+
## Workspace app connections
6+
7+
The connection log contains a complete record of all **workspace app** connections.
8+
These originate from within the Coder deployment, and thus the connection log
9+
is a source of truth for these events.
10+
11+
## Browser port forwarding
12+
13+
The connection log contains a complete record of all workspace port forwarding
14+
performed via the web dashboard.
15+
16+
## SSH & IDE sessions
17+
18+
The connection log aims to capture a record of SSH & IDE sessions to workspaces.
19+
These events are reported by workspace agents, and their receipt by the server
20+
is not guaranteed.
21+
22+
## Filtering logs
23+
24+
Connection logs can be filtered with the following parameters:
25+
26+
- `organization` - The name or ID of the organization of the workspace being
27+
connected to.
28+
- `workspace_owner` - The username of the owner of the workspace being connected
29+
to.
30+
- `type` - The type of the connection (i.e. SSH, VSCode, Workspace App).
31+
An exhaustive list is
32+
[available here](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#ConnectionType).
33+
- `username`: The name of the user who initiated the connection.
34+
- `user_email`: The email of the user who initiated the connection.
35+
- `started_after`: The time after which the connection started. Uses the RFC3339Nano format.
36+
- `started_before`: The time before which the connection started. Uses the RFC3339Nano format.
37+
- `workspace_id`: The ID of the workspace being connected to.
38+
- `connection_id`: The ID of the connection.
39+
- `status`: The status of the connection, either `ongoing` or `completed`.
40+
Some events are neither ongoing nor completed, such as the opening of a
41+
workspace app.
42+
43+
## Capturing/Exporting Connection Logs
44+
45+
In addition to the user interface, there are multiple ways to consume or query
46+
connection events.
47+
48+
## REST API
49+
50+
Connection logs can be retrieved via our REST API. You can find detailed
51+
information about this in our
52+
[endpoint documentation](../../reference/api/enterprise.md#get-connection-logs).
53+
54+
## Service Logs
55+
56+
Connection events are also dispatched as service logs and can be captured and
57+
categorized using any log management tool such as [Splunk](https://splunk.com).
58+
59+
Example of a [JSON formatted](../../reference/cli/server.md#--log-json)
60+
connection log entry, when an SSH connection is made:
61+
62+
```json
63+
{
64+
"ts": "2025-07-03T05:09:41.929840747Z",
65+
"level": "INFO",
66+
"msg": "connection_log",
67+
"caller": "/home/coder/coder/enterprise/audit/backends/slog.go:38",
68+
"func": "github.com/coder/coder/v2/enterprise/audit/backends.(*SlogExporter).ExportStruct",
69+
"logger_names": ["coderd"],
70+
"fields": {
71+
"request_id": "2bd88dd5-f7a5-4e29-b5ba-543400798c8c",
72+
"ID": "b4f043e3-2010-4dd2-a1fe-a7c2c923e236",
73+
"Time": "2025-07-03T05:09:41.923468875Z",
74+
"OrganizationID": "0665a54f-0b77-4a58-94aa-59646fa38a74",
75+
"WorkspaceOwnerID": "6dea5f8c-ecec-4cf0-a5bd-bc2c63af2efa",
76+
"WorkspaceID": "3c0b37c8-e58c-4980-b9a1-2732410480a5",
77+
"WorkspaceName": "dev",
78+
"AgentName": "main",
79+
"Type": "ssh",
80+
"Code": null,
81+
"Ip": "fd7a:115c:a1e0:4afd:8ffb:2fc9:4b5:da61",
82+
"UserAgent": "",
83+
"UserID": null,
84+
"SlugOrPort": "",
85+
"ConnectionID": "dcfe943f-2afb-4e3f-8f00-3eb1718a3f8b",
86+
"CloseReason": "",
87+
"ConnectionStatus": "connected"
88+
}
89+
}
90+
```
91+
92+
Example of a [human readable](../../reference/cli/server.md#--log-human)
93+
connection log entry, when `code-server` is opened:
94+
95+
```console
96+
[API] 2025-07-03 06:57:16.157 [info] coderd: connection_log request_id=de3f6004-6cc1-4880-a296-d7c6ca1abf75 ID=f0249951-d454-48f6-9504-e73340fa07b7 Time="2025-07-03T06:57:16.144719Z" OrganizationID=0665a54f-0b77-4a58-94aa-59646fa38a74 WorkspaceOwnerID=6dea5f8c-ecec-4cf0-a5bd-bc2c63af2efa WorkspaceID=3c0b37c8-e58c-4980-b9a1-2732410480a5 WorkspaceName=dev AgentName=main Type=workspace_app Code=200 Ip=127.0.0.1 UserAgent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/100.0.4896.127 Safari/537.36" UserID=6dea5f8c-ecec-4cf0-a5bd-bc2c63af2efa SlugOrPort=code-server ConnectionID=<nil> CloseReason="" ConnectionStatus=connected
97+
```
98+
99+
## Enabling this feature
100+
101+
This feature is only available with a premium license.

‎docs/manifest.json

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -796,6 +796,12 @@
796796
"path": "./admin/security/audit-logs.md",
797797
"state": ["premium"]
798798
},
799+
{
800+
"title": "Connection Logs",
801+
"description": "Monitor connections to workspaces",
802+
"path": "./admin/security/connection-logs.md",
803+
"state": ["premium"]
804+
},
799805
{
800806
"title": "Secrets",
801807
"description": "Use sensitive variables in your workspaces",

0 commit comments

Comments
 (0)