Skip to content

Commit a4bb7c4

Browse files
ethanndicksonethanndickson
committed
docs: add connection logs
1 parent ab296c6 commit a4bb7c4

File tree

2 files changed

+109
-0
lines changed

2 files changed

+109
-0
lines changed

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

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Connection Logs
2+
3+
The Connection Log page in the dashboard 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. Results will
34+
not include SSH & IDE sessions.
35+
- `user_email`: The email of the user who initiated the connection. Results will
36+
not include SSH & IDE sessions.
37+
- `started_after`: The time after which the connection started. Uses the RFC3339Nano format.
38+
- `started_before`: The time before which the connection started. Uses the RFC3339Nano format.
39+
- `workspace_id`: The ID of the workspace being connected to.
40+
- `connection_id`: The ID of the connection.
41+
- `status`: The status of the connection, either `ongoing` or `completed`.
42+
Some events are neither ongoing nor completed, such as the opening of a
43+
workspace app.
44+
45+
## Capturing/Exporting Connection Logs
46+
47+
In addition to the user interface, there are multiple ways to consume or query
48+
connection events.
49+
50+
## REST API
51+
52+
Connection logs can be retrieved via our REST API. You can find detailed
53+
information about this in our
54+
[endpoint documentation](../../reference/api/enterprise.md#get-connection-logs).
55+
56+
## Service Logs
57+
58+
Connection events are also dispatched as service logs and can be captured and
59+
categorized using any log management tool such as [Splunk](https://splunk.com).
60+
61+
Example of a [JSON formatted](../../reference/cli/server.md#--log-json)
62+
connection log entry, when an SSH connection is made:
63+
64+
```json
65+
{
66+
"ts": "2025-07-03T05:09:41.929840747Z",
67+
"level": "INFO",
68+
"msg": "connection_log",
69+
"caller": "/home/coder/coder/enterprise/audit/backends/slog.go:38",
70+
"func": "github.com/coder/coder/v2/enterprise/audit/backends.(*SlogExporter).ExportStruct",
71+
"logger_names": ["coderd"],
72+
"fields": {
73+
"request_id": "2bd88dd5-f7a5-4e29-b5ba-543400798c8c",
74+
"ID": "b4f043e3-2010-4dd2-a1fe-a7c2c923e236",
75+
"Time": "2025-07-03T05:09:41.923468875Z",
76+
"OrganizationID": "0665a54f-0b77-4a58-94aa-59646fa38a74",
77+
"WorkspaceOwnerID": "6dea5f8c-ecec-4cf0-a5bd-bc2c63af2efa",
78+
"WorkspaceID": "3c0b37c8-e58c-4980-b9a1-2732410480a5",
79+
"WorkspaceName": "dev",
80+
"AgentName": "main",
81+
"Type": "ssh",
82+
"Code": null,
83+
"Ip": "fd7a:115c:a1e0:4afd:8ffb:2fc9:4b5:da61",
84+
"UserAgent": "",
85+
"UserID": null,
86+
"SlugOrPort": "",
87+
"ConnectionID": "dcfe943f-2afb-4e3f-8f00-3eb1718a3f8b",
88+
"CloseReason": "",
89+
"ConnectionStatus": "connected"
90+
}
91+
}
92+
```
93+
94+
Example of a [human readable](../../reference/cli/server.md#--log-human)
95+
connection log entry, when `code-server` is opened:
96+
97+
```console
98+
[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
99+
```
100+
101+
## Enabling this feature
102+
103+
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)