feat: add auth telemetry lifecycle traces (#994)

Add login/logout outcome traces with bounded source/method/reason, credential
store/clear traces (keyring mode, category, failure category, duration), and
deployment suspended/recovered/cross-window/auth-config-recovery-failed events.
Command login owns the outer auth.login span so command, auto-login, and
switch-deployment sources are captured once.

Closes #984

Author: EhabY

src/commands.ts

@@ -14,6 +14,11 @@ import * as cliExec from "./core/cliExec";
 import { CertificateError } from "./error/certificateError";
 import { toError } from "./error/errorUtils";
 import { type FeatureSet, featureSetForVersion } from "./featureSet";
+import {
+	AuthTelemetry,
+	type AuthLoginOutcome,
+	type AuthLogoutOutcome,
+} from "./instrumentation/auth";
 import {
 	reportElapsedProgress,
 	withCancellableProgress,
@@ -49,7 +54,7 @@ import type { PathResolver } from "./core/pathResolver";
 import type { SecretsManager } from "./core/secretsManager";
 import type { DeploymentManager } from "./deployment/deploymentManager";
 import type { Logger } from "./logging/logger";
-import type { LoginCoordinator } from "./login/loginCoordinator";
+import type { LoginCoordinator, LoginMethod } from "./login/loginCoordinator";
 import type { TelemetryService } from "./telemetry/service";
 import type { SpeedtestPanelFactory } from "./webviews/speedtest/speedtestPanelFactory";
 import type {
@@ -68,6 +73,11 @@ interface OpenOptions {
 	useDefaultDirectory?: boolean;
 }
 
+interface LoginArgs {
+	readonly url?: string;
+	readonly autoLogin?: boolean;
+}
+
 const openDefaults = {
 	openRecent: false,
 	useDefaultDirectory: true,
@@ -83,6 +93,7 @@ export class Commands {
 	private readonly duplicateWorkspaceIpc: DuplicateWorkspaceIpc;
 	private readonly speedtestPanelFactory: SpeedtestPanelFactory;
 	private readonly telemetryService: TelemetryService;
+	private readonly authTelemetry: AuthTelemetry;
 
 	// These will only be populated when actively connected to a workspace and are
 	// used in commands.  Because commands can be executed by the user, it is not
@@ -109,6 +120,7 @@ export class Commands {
 		this.loginCoordinator = serviceContainer.getLoginCoordinator();
 		this.duplicateWorkspaceIpc = serviceContainer.getDuplicateWorkspaceIpc();
 		this.speedtestPanelFactory = serviceContainer.getSpeedtestPanelFactory();
+		this.authTelemetry = new AuthTelemetry(this.telemetryService);
 	}
 
 	/**
@@ -137,20 +149,20 @@ export class Commands {
 	 * Log into a deployment. If already authenticated, this is a no-op.
 	 * If no URL is provided, shows a menu of recent URLs plus defaults.
 	 */
-	public async login(args?: {
-		url?: string;
-		autoLogin?: boolean;
-	}): Promise<void> {
+	public async login(args?: LoginArgs): Promise<void> {
 		if (this.deploymentManager.isAuthenticated()) {
 			return;
 		}
-		await this.performLogin(args);
+		await this.authTelemetry.traceLogin(
+			args?.autoLogin ? "auto_login" : "command",
+			(trace) => this.performLogin(args, trace.setMethod),
+		);
 	}
 
-	private async performLogin(args?: {
-		url?: string;
-		autoLogin?: boolean;
-	}): Promise<void> {
+	private async performLogin(
+		args: LoginArgs | undefined,
+		setMethod: (method: LoginMethod) => void,
+	): Promise<AuthLoginOutcome> {
 		this.logger.debug("Logging in");
 
 		const currentDeployment = await this.secretsManager.getCurrentDeployment();
@@ -160,7 +172,7 @@ export class Commands {
 			currentDeployment?.url,
 		);
 		if (!url) {
-			return; // The user aborted.
+			return { success: false, reason: "no_url_provided" };
 		}
 
 		const safeHostname = toSafeHost(url);
@@ -173,19 +185,26 @@ export class Commands {
 		});
 
 		if (!result.success) {
-			return;
+			return result;
 		}
 
+		// Record the method eagerly so it is captured even if persistence throws.
+		setMethod(result.method);
 		await this.deploymentManager.setDeployment({
 			url,
 			safeHostname,
 			token: result.token,
 			user: result.user,
 		});
+		this.showWelcomeMessage(result.user.username);
+		this.logger.debug("Login complete to deployment:", url);
+		return { success: true, method: result.method };
+	}
 
+	private showWelcomeMessage(username: string): void {
 		vscode.window
 			.showInformationMessage(
-				`Welcome to Coder, ${result.user.username}!`,
+				`Welcome to Coder, ${username}!`,
 				{
 					detail:
 						"You can now use the Coder extension to manage your Coder instance.",
@@ -197,7 +216,6 @@ export class Commands {
 					vscode.commands.executeCommand("coder.open");
 				}
 			});
-		this.logger.debug("Login complete to deployment:", url);
 	}
 
 	/**
@@ -418,21 +436,30 @@ export class Commands {
 	 * Log out and clear stored credentials, requiring re-authentication on next login.
 	 */
 	public async logout(): Promise<void> {
+		await this.authTelemetry.traceLogout(() => this.performLogout());
+	}
+
+	private async performLogout(): Promise<AuthLogoutOutcome> {
 		if (!this.deploymentManager.isAuthenticated()) {
-			return;
+			return { success: false, reason: "not_authenticated" };
 		}
 
 		this.logger.debug("Logging out");
 
 		const deployment = this.deploymentManager.getCurrentDeployment();
-
-		await this.deploymentManager.clearDeployment();
+		await this.deploymentManager.clearDeployment("logout");
 
 		if (deployment) {
 			await this.cliManager.clearCredentials(deployment.url);
 			await this.secretsManager.clearAllAuthData(deployment.safeHostname);
 		}
 
+		this.showLogoutMessage();
+		this.logger.debug("Logout complete");
+		return { success: true };
+	}
+
+	private showLogoutMessage(): void {
 		vscode.window
 			.showInformationMessage("You've been logged out of Coder!", "Login")
 			.then((action) => {
@@ -442,8 +469,6 @@ export class Commands {
 					});
 				}
 			});
-
-		this.logger.debug("Logout complete");
 	}
 
 	/**
@@ -452,7 +477,9 @@ export class Commands {
 	 */
 	public async switchDeployment(): Promise<void> {
 		this.logger.debug("Switching deployment");
-		await this.performLogin();
+		await this.authTelemetry.traceLogin("switch_deployment", (trace) =>
+			this.performLogin(undefined, trace.setMethod),
+		);
 	}
 
 	/**

src/core/cliCredentialManager.ts

@@ -7,8 +7,14 @@ import * as semver from "semver";
 
 import { isAbortError } from "../error/errorUtils";
 import { featureSetForVersion } from "../featureSet";
+import {
+	CredentialCliError,
+	CredentialFileError,
+	CredentialTelemetry,
+} from "../instrumentation/credentials";
 import { isKeyringEnabled } from "../settings/cli";
 import { getHeaderArgs } from "../settings/headers";
+import { type TelemetryReporter } from "../telemetry/reporter";
 import { toSafeHost } from "../util";
 import { writeAtomically } from "../util/fs";
 
@@ -17,6 +23,7 @@ import { version } from "./cliExec";
 import type { WorkspaceConfiguration } from "vscode";
 
 import type { Logger } from "../logging/logger";
+import type { Span } from "../telemetry/span";
 
 import type { PathResolver } from "./pathResolver";
 
@@ -46,11 +53,16 @@ export function isKeyringSupported(): boolean {
  * persistence: keyring-backed (via CLI) and file-based (plaintext).
  */
 export class CliCredentialManager {
+	private readonly credentialTelemetry: CredentialTelemetry;
+
 	constructor(
 		private readonly logger: Logger,
 		private readonly resolveBinary: BinaryResolver,
 		private readonly pathResolver: PathResolver,
-	) {}
+		telemetry: TelemetryReporter,
+	) {
+		this.credentialTelemetry = new CredentialTelemetry(telemetry);
+	}
 
 	/**
 	 * Store credentials for a deployment URL. Uses the OS keyring when the
@@ -59,22 +71,35 @@ export class CliCredentialManager {
 	 *
 	 * Keyring and files are mutually exclusive, never both.
 	 */
-	public async storeToken(
+	public storeToken(
 		url: string,
 		token: string,
 		configs: Pick<WorkspaceConfiguration, "get">,
 		options?: { signal?: AbortSignal },
 	): Promise<void> {
-		const binPath = await this.resolveKeyringBinary(
-			url,
-			configs,
-			"keyringAuth",
-		);
-		if (!binPath) {
-			await this.writeCredentialFiles(url, token);
-			return;
-		}
+		return this.credentialTelemetry.traceStore(configs, async (span) => {
+			const binPath = await this.resolveKeyringBinary(
+				url,
+				configs,
+				"keyringAuth",
+			);
+			if (!binPath) {
+				span.setProperty("category", "file");
+				await this.writeCredentialFiles(url, token);
+				return;
+			}
+			span.setProperty("category", "keyring");
+			await this.storeKeyringToken(binPath, url, token, configs, options);
+		});
+	}
 
+	private async storeKeyringToken(
+		binPath: string,
+		url: string,
+		token: string,
+		configs: Pick<WorkspaceConfiguration, "get">,
+		options?: { signal?: AbortSignal },
+	): Promise<void> {
 		const args = [
 			...getHeaderArgs(configs),
 			"login",
@@ -89,7 +114,10 @@ export class CliCredentialManager {
 			this.logger.info("Stored token via CLI for", url);
 		} catch (error) {
 			this.logger.warn("Failed to store token via CLI:", error);
-			throw error;
+			if (isAbortError(error)) {
+				throw error;
+			}
+			throw new CredentialCliError(error);
 		}
 	}
 
@@ -139,15 +167,20 @@ export class CliCredentialManager {
 	 * deletion in parallel, both best-effort. Throws AbortError when the
 	 * signal is aborted.
 	 */
-	public async deleteToken(
+	public deleteToken(
 		url: string,
 		configs: Pick<WorkspaceConfiguration, "get">,
 		options?: { signal?: AbortSignal },
 	): Promise<void> {
-		await Promise.all([
-			this.deleteCredentialFiles(url),
-			this.deleteKeyringToken(url, configs, options?.signal),
-		]);
+		return this.credentialTelemetry.traceClear(configs, async (span) => {
+			await Promise.all([
+				this.deleteCredentialFiles(url),
+				this.deleteKeyringToken(url, configs, {
+					signal: options?.signal,
+					span,
+				}),
+			]);
+		});
 	}
 
 	/**
@@ -201,14 +234,18 @@ export class CliCredentialManager {
 		url: string,
 		token: string,
 	): Promise<void> {
-		const safeHostname = toSafeHost(url);
-		await Promise.all([
-			this.atomicWriteFile(this.pathResolver.getUrlPath(safeHostname), url),
-			this.atomicWriteFile(
-				this.pathResolver.getSessionTokenPath(safeHostname),
-				token,
-			),
-		]);
+		try {
+			const safeHostname = toSafeHost(url);
+			await Promise.all([
+				this.atomicWriteFile(this.pathResolver.getUrlPath(safeHostname), url),
+				this.atomicWriteFile(
+					this.pathResolver.getSessionTokenPath(safeHostname),
+					token,
+				),
+			]);
+		} catch (error) {
+			throw new CredentialFileError(error);
+		}
 	}
 
 	/**
@@ -230,18 +267,22 @@ export class CliCredentialManager {
 	}
 
 	/**
-	 * Delete keyring token via `coder logout`. Best-effort: never throws.
+	 * Delete keyring token via `coder logout`. Best-effort: records the failure
+	 * on the span instead of throwing (except on abort), so it is tagged where
+	 * it occurs.
 	 */
 	private async deleteKeyringToken(
 		url: string,
 		configs: Pick<WorkspaceConfiguration, "get">,
-		signal?: AbortSignal,
+		{ signal, span }: { signal?: AbortSignal; span: Span },
 	): Promise<void> {
 		let binPath: string | undefined;
 		try {
 			binPath = await this.resolveKeyringBinary(url, configs, "keyringAuth");
 		} catch (error) {
 			this.logger.warn("Could not resolve keyring binary for delete:", error);
+			span.setProperty("failure_category", "binary");
+			span.markFailure();
 			return;
 		}
 		if (!binPath) {
@@ -257,6 +298,8 @@ export class CliCredentialManager {
 				throw error;
 			}
 			this.logger.warn("Failed to delete token via CLI:", error);
+			span.setProperty("failure_category", "cli");
+			span.markFailure();
 		}
 	}
 

src/core/container.ts

@@ -90,6 +90,7 @@ export class ServiceContainer implements vscode.Disposable {
 				}
 			},
 			this.pathResolver,
+			this.telemetryService,
 		);
 		this.cliManager = new CliManager(
 			this.logger,