feat: log tailnet tunnels to the connection log (#27423)

Co-authored-by: Chris DiGiamo <cd@anthropic.com>
Co-authored-by: Chris DiGiamo <cdigiamo@anthropic.com>

docs/admin/monitoring/connection-logs.md

@@ -24,6 +24,37 @@ The connection log aims to capture a record of all workspace SSH and IDE session
 These events are reported by workspace agents, and their receipt by the server
 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.
+
+## Tunnel Connections
+
+The connection log records a tunnel event each time a client
+establishes a tunnel to a workspace agent, carrying the identity, IP
+address, and user agent of the authenticated user who opened it. Tunnels
+carry SSH and IDE traffic, so these events provide the user attribution
+that agent-reported events lack.
+
+Keep the following in mind when interpreting tunnel events:
+
+- A tunnel event records that a tunnel was established, not what it was
+  used for. Any client that dials a workspace agent produces one,
+  including `coder ssh`, `coder port-forward`, `coder ping`,
+  `coder speedtest`, and IDE extensions. One tunnel may carry many
+  sessions, or none.
+- Tunnel events are deduplicated per user, workspace agent, IP address,
+  and client. Clients automatically re-establish tunnels after network
+  interruptions or server restarts; reconnections do not produce new
+  events while a session is active. A new event is recorded when a
+  session has been idle for one hour, or when the user connects from a
+  new IP address or client.
+- Connections made through Coder Desktop (Coder Connect) do not
+  currently produce tunnel events.
+- 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:
@@ -36,9 +67,9 @@ You can filter connection logs by the following parameters:
     For more connection types, refer to the
     [CoderSDK documentation](https://pkg.go.dev/github.com/coder/coder/v2/codersdk#ConnectionType).
 - `username`: The name of the user who initiated the connection.
-   Results will not include SSH or IDE sessions.
+   Results will not include agent-reported SSH or IDE sessions.
 - `user_email`: The email of the user who initiated the connection.
-   Results will not include SSH or IDE sessions.
+   Results will 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.