feat: add workflow telemetry traces

Author: EhabY

src/commands.ts

@@ -24,6 +24,8 @@ const PROVISIONING_STATUSES: ReadonlySet<WorkspaceStatus> = new Set([
 	"deleting",
 ]);
 
+export type WorkspacePromptAction = "start" | "update";
+
 interface ObservedWorkspaceState {
 	readonly status: WorkspaceStatus;
 	readonly buildTransition: WorkspaceBuild["transition"];
@@ -174,6 +176,25 @@ export class WorkspaceOperationTelemetry {
 		});
 	}
 
+	public async traceStartPrompted(
+		outdated: boolean,
+		fn: () => Promise<WorkspacePromptAction | undefined>,
+	): Promise<WorkspacePromptAction | undefined> {
+		return this.telemetry.trace(
+			"workspace.start.prompted",
+			async (span) => {
+				const action = await fn();
+				if (!action) {
+					span.markAborted();
+					return undefined;
+				}
+				span.setProperty("action", action);
+				return action;
+			},
+			{ "update.offered": outdated },
+		);
+	}
+
 	/**
 	 * Records dismissal as `result: "aborted"`. The framework treats any throw
 	 * as `result: "error"`, so we return inside the span and rethrow outside.
@@ -196,7 +217,7 @@ export class WorkspaceOperationTelemetry {
 					throw error;
 				}
 			},
-			{ workspaceName: this.workspaceName },
+			{ prompt: "parameters" },
 		);
 		if (cancel) throw cancel;
 		return parameters;

src/instrumentation/commands.ts

@@ -337,18 +337,20 @@ export class WorkspaceStateMachine implements vscode.Disposable {
 		workspaceName: string,
 		outdated: boolean,
 	): Promise<"start" | "update" | undefined> {
-		const buttons = outdated ? ["Start", "Update and Start"] : ["Start"];
-		const action = await vscodeProposed.window.showInformationMessage(
-			`The workspace ${workspaceName} is not running. How would you like to proceed?`,
-			{
-				useCustom: true,
-				modal: true,
-			},
-			...buttons,
-		);
-		if (action === "Start") return "start";
-		if (action === "Update and Start") return "update";
-		return undefined;
+		return this.operationTelemetry.traceStartPrompted(outdated, async () => {
+			const buttons = outdated ? ["Start", "Update and Start"] : ["Start"];
+			const action = await vscodeProposed.window.showInformationMessage(
+				`The workspace ${workspaceName} is not running. How would you like to proceed?`,
+				{
+					useCustom: true,
+					modal: true,
+				},
+				...buttons,
+			);
+			if (action === "Start") return "start";
+			if (action === "Update and Start") return "update";
+			return undefined;
+		});
 	}
 
 	public getAgentId(): string | undefined {

src/instrumentation/workspace.ts

@@ -19,6 +19,8 @@ import type { Logger } from "../../logging/logger";
 import type { TelemetryContext } from "../event";
 import type { FlushStatus } from "../service";
 
+import type { ExportFormat } from "./writers/types";
+
 const REVEAL_ACTION = "Reveal in File Explorer";
 
 const PROGRESS_OPTIONS = {
@@ -27,15 +29,24 @@ const PROGRESS_OPTIONS = {
 	cancellable: true,
 } as const;
 
+export type ExportTelemetryOutcome =
+	| { readonly status: "cancelled"; readonly stage: "prompt" | "progress" }
+	| { readonly status: "failed"; readonly error: unknown }
+	| {
+			readonly status: "success";
+			readonly eventCount: number;
+			readonly format: ExportFormat;
+	  };
+
 export async function runExportTelemetryCommand(
 	telemetryDir: string,
 	logger: Logger,
 	flushTelemetry: () => Promise<FlushStatus>,
 	context: TelemetryContext,
-): Promise<void> {
+): Promise<ExportTelemetryOutcome> {
 	const choice = await promptForExport();
 	if (!choice) {
-		return;
+		return { status: "cancelled", stage: "prompt" };
 	}
 
 	const request: ExportRequest = {
@@ -53,7 +64,7 @@ export async function runExportTelemetryCommand(
 		PROGRESS_OPTIONS,
 	);
 
-	await reportOutcome(result, choice, logger);
+	return reportOutcome(result, choice, logger);
 }
 
 /** Wires the pipeline's host hooks to the progress UI and the logger. */
@@ -81,26 +92,27 @@ async function reportOutcome(
 	result: ProgressResult<number>,
 	choice: ExportChoice,
 	logger: Logger,
-): Promise<void> {
+): Promise<ExportTelemetryOutcome> {
 	if (!result.ok) {
 		if (result.cancelled) {
-			return;
+			return { status: "cancelled", stage: "progress" };
 		}
 		logger.error("Telemetry export failed", result.error);
 		void vscode.window.showErrorMessage(
 			`Telemetry export failed: ${toError(result.error).message}`,
 		);
-		return;
+		return { status: "failed", error: result.error };
 	}
 
 	const eventCount = result.value;
 	if (eventCount === 0) {
 		void vscode.window.showInformationMessage(
 			`No telemetry events found for ${choice.range.label}.`,
 		);
-		return;
+		return { status: "success", eventCount, format: choice.format };
 	}
 	await notifyExportSucceeded(choice.outputPath, eventCount, logger);
+	return { status: "success", eventCount, format: choice.format };
 }
 
 async function notifyExportSucceeded(

src/remote/workspaceStateMachine.ts

@@ -85,6 +85,7 @@ async function handleOpen(ctx: UriRouteContext): Promise<void> {
 		agentName: agent ?? undefined,
 		folderPath: folder ?? undefined,
 		openRecent,
+		source: "uri",
 		useDefaultDirectory: false,
 	});
 }

src/telemetry/export/command.ts

@@ -0,0 +1,208 @@
+import { describe, expect, it } from "vitest";
+
+import { CommandInstrumentation } from "@/instrumentation/commands";
+
+import { agent, resource, workspace } from "@repo/mocks";
+
+import { createTelemetryHarness } from "../../mocks/telemetry";
+
+function workspaceWithAgents() {
+	const connected = agent({
+		status: "connected",
+		lifecycle_state: "ready",
+	});
+	const disconnected = agent({
+		id: "agent-2",
+		name: "secondary",
+		status: "disconnected",
+		lifecycle_state: "off",
+	});
+	return {
+		connected,
+		disconnected,
+		workspace: workspace({
+			outdated: true,
+			latest_build: {
+				status: "running",
+				resources: [resource({ agents: [connected, disconnected] })],
+			},
+		}),
+	};
+}
+
+describe("command instrumentation helpers", () => {
+	it("records workspace selection without workspace or agent names", async () => {
+		const { sink, service } = createTelemetryHarness();
+		const traces = new CommandInstrumentation(service);
+		const selection = workspaceWithAgents();
+
+		await traces.workspaceOpen(
+			"command",
+			{ workspace: selection.workspace, agent: selection.connected },
+			() => Promise.resolve(true),
+		);
+
+		const event = sink.expectOne("workspace.open");
+		expect(event.properties).toMatchObject({
+			"agent.lifecycle_state": "ready",
+			"agent.status": "connected",
+			"workspace.outdated": "true",
+			"workspace.status": "running",
+			result: "success",
+		});
+		expect(event.measurements).toMatchObject({
+			agentCount: 2,
+			connectedAgentCount: 1,
+		});
+		expect(event.properties.workspaceName).toBeUndefined();
+		expect(event.properties.agentName).toBeUndefined();
+	});
+
+	it("records workspace picker cancellation and failure distinctly", async () => {
+		const { sink, service } = createTelemetryHarness();
+		const traces = new CommandInstrumentation(service);
+
+		await traces.workspacePicker("workspace.open", (telemetry) => {
+			telemetry.cancelled(3);
+			return Promise.resolve({ status: "cancelled" });
+		});
+		await traces.workspacePicker("workspace.open", (telemetry) => {
+			telemetry.failed("fetch_failed", 0);
+			return Promise.resolve({ status: "failed", category: "fetch_failed" });
+		});
+
+		const [cancelled, failed] = sink.eventsNamed("workspace.picker.prompted");
+		expect(cancelled.properties).toMatchObject({ result: "aborted" });
+		expect(cancelled.measurements.workspaceCount).toBe(3);
+		expect(failed.properties).toMatchObject({
+			"failure.category": "fetch_failed",
+			result: "error",
+		});
+		expect(failed.measurements.workspaceCount).toBe(0);
+	});
+
+	it("records workspace open cancellation and handled failure distinctly", async () => {
+		const { sink, service } = createTelemetryHarness();
+		const traces = new CommandInstrumentation(service);
+		const selection = workspaceWithAgents();
+
+		await traces.workspaceOpen("command", undefined, (telemetry) =>
+			Promise.resolve(
+				telemetry.cancel("agent_picker", { workspace: selection.workspace }),
+			),
+		);
+		await traces.workspaceOpen("command", undefined, (telemetry) =>
+			Promise.resolve(telemetry.fail("fetch_failed")),
+		);
+
+		const [cancelled, failed] = sink.eventsNamed("workspace.open");
+		expect(cancelled.properties).toMatchObject({
+			"cancel.stage": "agent_picker",
+			"workspace.status": "running",
+			result: "aborted",
+		});
+		expect(failed.properties).toMatchObject({
+			"failure.category": "fetch_failed",
+			result: "error",
+		});
+	});
+
+	it("records thrown workspace open failures without raw error details", async () => {
+		const { sink, service } = createTelemetryHarness();
+		const traces = new CommandInstrumentation(service);
+
+		await expect(
+			traces.workspaceOpen("command", undefined, () =>
+				Promise.reject(new Error("secret path /tmp/workspace")),
+			),
+		).rejects.toThrow("secret path /tmp/workspace");
+
+		const event = sink.expectOne("workspace.open");
+		expect(event.properties).toMatchObject({
+			"failure.category": "error",
+			result: "error",
+		});
+		expect(event.error).toBeUndefined();
+	});
+
+	it("records diagnostic cancellation and failure categories", async () => {
+		const { sink, service } = createTelemetryHarness();
+		const traces = new CommandInstrumentation(service);
+		const failure = new Error("boom");
+
+		await traces.diagnostic("coder.supportBundle", (telemetry) => {
+			telemetry.cancel("save_dialog");
+			return Promise.resolve();
+		});
+		await traces.diagnostic("coder.supportBundle", (telemetry) => {
+			telemetry.fail(failure, "unsupported_cli");
+			return Promise.resolve();
+		});
+
+		const [cancelled, failed] = sink.eventsNamed(
+			"command.diagnostic.completed",
+		);
+		expect(cancelled.properties).toMatchObject({
+			"cancel.stage": "save_dialog",
+			result: "aborted",
+		});
+		expect(failed.properties).toMatchObject({
+			"failure.category": "unsupported_cli",
+			result: "error",
+		});
+		expect(failed.error).toBeUndefined();
+	});
+
+	it("records bounded speed test measurements", async () => {
+		const { sink, service } = createTelemetryHarness();
+		const traces = new CommandInstrumentation(service);
+
+		await traces.diagnostic("coder.speedTest", (telemetry) => {
+			const parsed = telemetry.speedtestSuccess(
+				JSON.stringify({
+					overall: {
+						start_time_seconds: 0,
+						end_time_seconds: 5,
+						throughput_mbits: 42,
+					},
+					intervals: [
+						{
+							start_time_seconds: 0,
+							end_time_seconds: 5,
+							throughput_mbits: 42,
+						},
+					],
+				}),
+			);
+			expect(parsed.overall.throughput_mbits).toBe(42);
+			return Promise.resolve();
+		});
+
+		expect(sink.expectOne("command.diagnostic.completed")).toMatchObject({
+			measurements: {
+				intervalCount: 1,
+				throughputMbits: 42,
+			},
+			properties: { result: "success" },
+		});
+	});
+
+	it("records thrown devcontainer failures without raw error details", async () => {
+		const { sink, service } = createTelemetryHarness();
+		const traces = new CommandInstrumentation(service);
+
+		await expect(
+			traces.devcontainerOpen("dev_container", () =>
+				Promise.reject(new Error("secret local path /tmp/workspace")),
+			),
+		).rejects.toThrow("secret local path /tmp/workspace");
+
+		const event = sink.expectOne("workspace.devcontainer.open");
+		expect(event.properties).toMatchObject({
+			"failure.category": "error",
+			mode: "dev_container",
+			result: "error",
+		});
+		expect(event.error).toBeUndefined();
+	});
+});