Files
coder/docs/admin/monitoring/connection-logs.md
T
Jaayden HalkoandJake Howell d1a58b9f5d feat: add script to check for title case (#21484)
Historically, much of the UI used title case. This PR adds a lint check
that reports title case UI text so it can be converted to sentence case,
and converts the existing text.

- `site/scripts/check-sentence-case.mjs` runs as `pnpm
lint:sentence-case` and is part of `pnpm lint`. It reads JSX text and
string/template literals from the TypeScript AST and skips literals that
are code rather than UI text (imports, types, property names, tagged
templates, values of JSX attributes that are not displayed such as
`className` or `style`, and operands of `===`/`case` comparisons). JSX
text across inline elements and conditional JSX is checked as one
phrase. `--fix` lowercases the reported words. The checker is a
heuristic: it is not meant to model every code shape, so use a
`sentence-case-expect` comment where it guesses wrong.
- Proper nouns (Coder products, role names, third-party products,
protocols, font names) live in `PROPER_NOUNS`. For other deliberate
exceptions, a `sentence-case-expect` comment on the line above
suppresses the report and fails when that line no longer needs it.
- Existing UI text is converted to sentence case, and tests that assert
on it are updated.
- Deployment option lookups (`useDeploymentOptions`) now use CLI flags
instead of display names, so they do not depend on UI wording.

## Performance

`pnpm lint:sentence-case` takes **1.6 s** and is 2% to 4.5% of `pnpm
lint`. Measured on 82317c925e in a dev workspace (Xeon Platinum 8375C,
16 vCPUs, Node 22.23.4, TypeScript 6.0.2, warm file cache). CI buffers
the output of the lint steps, so its log has no per-step times to
compare against.

| Measurement (20 runs) | Result |
|---|---|
| Wall time | 1.64 s mean, 0.03 s standard deviation, 1.62 s to 1.71 s |
| CPU time | 3.0 s |
| Peak memory (RSS) | 154 MB, of which 116 MB is Node with `typescript`
loaded |
| Input | 1,301 of the 2,199 `.ts` and `.tsx` files in `site/src` (the
rest are excluded), 210,684 lines, 6.1 MB |
| Throughput | About 130,000 lines per second |
| Time per file | 0.5 ms median, 3 ms at the 95th percentile, 76 ms
maximum (`src/api/api.ts`, 121 KB) |

Each step of `pnpm lint`, median wall time of 5 runs:

| Step | Wall time |
|---|---|
| `lint:check` (Biome) | 0.96 s |
| `lint:oxlint` | 0.32 s |
| `lint:types` (`tsc`) | 5.8 s with its incremental cache, 45 s without
|
| `lint:circular-deps` | 5.7 s |
| `lint:compiler` | 15.6 s |
| `lint:sentence-case` | 1.6 s |
| `knip` | 6.6 s |
| All of `pnpm lint` | 37 s with the `tsc` cache, 76 s without |

<details>
<summary>Where the time goes, scaling, and limits</summary>

Phases of one run, from in-process timers. The split between parsing and
checking is approximate.

| Phase | Time | Share |
|---|---|---|
| Node startup | 0.03 s | 2% |
| Load the `typescript` module | 0.32 s | 20% |
| Find and read the files | 0.04 s | 2% |
| Parse (`ts.createSourceFile`) | 0.83 s | 52% |
| Check logic | 0.38 s | 24% |

Scaling, from synthetic inputs passed to `checkSource` (median of 3 to 5
warm runs):

- Clean input is linear in size: 0.2 ms to 0.35 ms per KB for one file
from 54 KB to 7 MB. 100,000 string literals take 0.3 s, 100,000 sibling
JSX elements take 0.8 s, and JSX nested 800 levels deep takes 10 ms.
- Conditional JSX stays bounded by the 64-variant cap: 1 to 48
conditional children in one element take at most 3.4 ms.
- Reporting and fixing add no measurable time. On the merge base with
`main` (378 reports in 175 files), a check, `--fix`, and a second
`--fix` each take 1.6 s to 1.7 s.
- The 21 unit tests run in about 30 ms, 1.7 s including Vitest startup.

Two limits, neither reachable with the current source:

- Time is quadratic in the reports for one file, because the fixed text
is rebuilt once per report. A 3.5 MB file takes 0.7 s clean and 18.0 s
with 12,800 reports. The most reports in one file on the merge base is
16.
- One JSX element with more than about 120,000 text phrases fails with
`RangeError: Maximum call stack size exceeded`, because the phrases are
spread into `push`.

</details>

---------

Co-authored-by: Jake Howell <jake@hwll.me>
2026-11-18 13:36:16 +07:00

13 KiB

title
title
Connection logs

Note

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

The Connection log page in the dashboard allows Auditors to monitor workspace agent connections.

Workspace App Connections

The connection log contains a complete record of all workspace app connections. These originate from within the Coder deployment, and thus the connection log is a source of truth for these events.

Browser Port Forwarding

The connection log contains a complete record of all workspace port forwarding performed via the dashboard.

SSH and IDE Sessions

The connection log aims to capture a record of all workspace SSH and IDE sessions. These events are reported by workspace agents, and their receipt by the control plane is not guaranteed.

Agent-reported events do not identify the Coder user who connected. To attribute SSH and IDE activity to a user, correlate them with tunnel events for the same workspace and agent.

The Coder CLI attaches a client session ID to the SSH and reconnecting pseudo-terminal (PTY) connections it opens. Tools that launch the CLI, such as IDE extensions, can reuse one ID across launches to group their connections. The client sets the ID, so it isn't guaranteed to be unique, and connections that share one can overlap or have gaps. To list connections in the same workspace that share an ID, open an entry's details and select View related connections.

Tunnel Connections

The connection log records the authorization decision for each request to add a tunnel to a workspace agent. Accepted requests have status code 101, and denied requests have status code 403. Tunnel events include the authenticated user's identity, IP address, and user agent.

Keep the following in mind when interpreting tunnel events:

  • A tunnel event records an authorization decision, not how the tunnel was used. Clients such as coder ssh, coder port-forward, coder ping, coder speedtest, Coder Desktop, and IDE extensions can request tunnels.
  • Tunnel events are deduplicated per workspace agent, actor, IP address, client, and authorization result. Clients automatically re-request tunnels after network interruptions or server restarts. These requests do not produce new events while a session is active. A new event is recorded after one hour of inactivity, or when the actor, IP address, client, or result changes.
  • Like workspace app connections, tunnel events are point-in-time records. They have no close time and are excluded from status: filter results.

How to Filter Connection Logs

You can filter connection logs by the following parameters:

  • organization - The name or ID of the organization of the workspace being connected to.
  • workspace_owner - The username of the owner of the workspace being connected to.
  • method - How the connection was established, such as ssh, reconnecting_pty, or workspace_app. For every method, refer to the codersdk.ConnectionLogMethod schema. For example, method:ssh matches every SSH connection, whichever app made it.
  • app - The name of the application that made an SSH or reconnecting pseudo-terminal (PTY) connection, such as cursor. Repeat the filter to match any of several apps, for example app:vscode app:cursor. Some clients report only vscode or jetbrains instead of their own name, so app:vscode and app:jetbrains can also include other VS Code-based editors and JetBrains IDEs. Coder lowercases the value and replaces hyphens with underscores before it matches. Workspace app slugs and forwarded ports don't match this filter.
  • type - Deprecated and will be removed in a future release. Use method and app instead, as described in Replace the type filter.
  • username: The name of the user who initiated the connection. Results do not include agent-reported SSH or IDE sessions.
  • user_email: The email of the user who initiated the connection. Results do not include agent-reported SSH or IDE sessions.
  • connected_after: The time after which the connection started. Uses the RFC3339Nano format.
  • connected_before: The time before which the connection started. Uses the RFC3339Nano format.
  • workspace_id: The ID of the workspace being connected to.
  • connection_id: The ID of the connection.
  • client_session_id: Exact, case-insensitive match for a 32-character hexadecimal client session ID. Entries without a client session ID don't match.
  • status: The status of the connection, either ongoing or completed. Only SSH and reconnecting PTY connections have a status. A connection is completed after Coder receives its disconnect event, and ongoing until then. Workspace app, port forwarding, and tunnel events never match a status filter.

Replace the type filter

If you have saved searches or scripts that use the type filter, replace it with method and app:

type filter Replacement
type:ssh method:ssh, which also matches SSH connections from VS Code and JetBrains apps
type:vscode method:ssh with an app filter for each VS Code-based app, for example app:vscode app:cursor
type:jetbrains method:ssh app:jetbrains, plus an app filter for any JetBrains IDE that reports its own name
type:reconnecting_pty, type:workspace_app, type:port_forwarding, type:tunnel method with the same value, for example method:workspace_app

Capture and export connection logs

In addition to the Coder dashboard, there are multiple ways to consume or query connection events.

REST API

You can retrieve connection logs via the Coder API. Visit the get-connection-logs endpoint documentation for details.

Each connection log in the response describes the connection with these fields:

  • connection_method: How the connection was established, with the same values as the method filter.
  • app_name: The name of the application that made an SSH or reconnecting PTY connection, such as vscode. The client reports this name, so treat it as a label rather than a verified identity. The response omits this field when the app isn't known, and for workspace app, port forwarding, and tunnel connections.
  • web_info.slug_or_port: The workspace app slug or forwarded port, for workspace app and port forwarding connections.
  • ssh_info.client_session_id: The optional client session ID for SSH or reconnecting PTY connections. Omitted when the client didn't supply an ID.
  • type: Deprecated. Use connection_method and app_name instead. It will be removed in a future release.

If you read type, map its values to the new fields as follows:

type connection_method app_name
ssh ssh Omitted, or an app outside the VS Code and JetBrains families
vscode ssh An app in the VS Code family, such as vscode
jetbrains ssh An app in the JetBrains family, such as jetbrains
reconnecting_pty reconnecting_pty Omitted unless the app is known
workspace_app, port_forwarding, tunnel Same as type Omitted

The type field keeps the same values, but the API schema describes it as a string rather than an enum.

Connection durations

For SSH and reconnecting PTY connections, the duration is ssh_info.disconnect_time minus connect_time.

Timestamps Meaning Connection log page shows
No disconnect_time No disconnect recorded yet Ongoing
connect_time equals disconnect_time Disconnect recorded without its connect Unknown start
disconnect_time before connect_time Disconnect recorded before connect Disconnect recorded before connect
Otherwise Both events recorded The duration

Equal timestamps don't mean a zero-length connection. When Coder receives a disconnect without its connect, it stores the disconnect time as connect_time.

Service Logs

Connection events are also dispatched as service logs and can be captured and categorized using any log management tool such as Splunk.

Each connection_log entry describes the connection with these fields:

  • ConnectionMethod: How the connection was established, with the same values as the API connection_method field.
  • AppNameOrPort: The name of the connecting application for SSH and reconnecting PTY connections, or the workspace app slug or forwarded port for workspace app and port forwarding connections. The value is an empty string when there is nothing to report.
  • ClientSessionID: The client session ID for SSH and reconnecting PTY connections, or an empty string. To follow a session across client, coderd, and agent logs, refer to Trace workspace connections.
  • RxBytes and TxBytes: The bytes the agent received and sent over an SSH or reconnecting PTY connection. They're set only on disconnected entries, and are null (<nil> in human-readable logs) otherwise or for older agents. They aren't in the API or the dashboard.

If your log pipeline reads the Type or SlugOrPort fields, update it to read ConnectionMethod and AppNameOrPort, because entries no longer include the old fields. For SSH connections from a VS Code or JetBrains family app, ConnectionMethod is ssh and AppNameOrPort holds the app name, such as vscode. Every other former Type value matches ConnectionMethod directly.

Example of a JSON formatted connection log entry, when VS Code connects over SSH:

{
    "ts": "2026-10-07T11:34:37.428786242Z",
    "level": "INFO",
    "msg": "connection_log",
    "caller": "/home/coder/coder/enterprise/audit/backends/slog.go:36",
    "func": "github.com/coder/coder/v2/enterprise/audit/backends.(*SlogExporter).ExportStruct",
    "logger_names": ["coderd"],
    "fields": {
        "ID": "2e3b3337-77ab-4677-b39f-ba98df4e8ae4",
        "OrganizationID": "8654721b-2d93-4559-afdb-bdbdc2acbdc2",
        "WorkspaceOwnerID": "1a7edc8c-b712-4a1f-9d8f-7727127912e2",
        "WorkspaceID": "59d3e101-2d07-40c8-9bcd-d5fff4cc5266",
        "WorkspaceName": "dev",
        "AgentName": "main",
        "ConnectionMethod": "ssh",
        "Code": null,
        "IP": "fd7a:115c:a1e0:4b86:9046:80e:6c70:33b7",
        "UserAgent": "",
        "UserID": null,
        "AppNameOrPort": "vscode",
        "ConnectionID": "875ee185-cdf7-4cd1-98d7-d8a415e42a26",
        "DisconnectReason": "",
        "ClientSessionID": "",
        "Time": "2026-10-07T11:34:37.428771813Z",
        "ConnectionStatus": "connected"
    }
}

Example of a human readable connection log entry, when a user opens code-server:

2026-10-07 11:34:37.428 [info]  coderd: connection_log  ID=909a0310-a14c-4761-89d3-9779a328f14f  OrganizationID=dc39157d-b298-415d-8fc7-590e9055f244  WorkspaceOwnerID=17f1cc14-ac7a-4703-976e-73ea4547dceb  WorkspaceID=f2e648d4-95bc-4df3-a5c2-ee5be991da29  WorkspaceName=dev  AgentName=main  ConnectionMethod=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=17f1cc14-ac7a-4703-976e-73ea4547dceb  AppNameOrPort=code-server  ConnectionID=<nil>  DisconnectReason=""  ClientSessionID=""  Time="2026-10-07 11:34:37.428773435 +0000 UTC"  ConnectionStatus=connected

Data Retention

Coder supports configurable retention policies that automatically purge old Connection Logs. To enable automated purging, configure the --connection-logs-retention flag or CODER_CONNECTION_LOGS_RETENTION environment variable. For comprehensive configuration options, see Data Retention.

How to Enable Connection Logs

This feature is only available with a Premium license.