feat(telemetry): Phase A core service infrastructure (#919)

Lays the producer-side foundation for extension telemetry. The service
fans out structured events to a list of sinks; this PR ships the
service, event model, and trace abstraction only. No sinks, no callers,
and no user-facing setting. Phase B will add the first sink and start
instrumenting.

- TelemetryService owns the event pipeline: session context, level
  gating, sink fan-out, and lifecycle (flush and dispose)
- Event model is shaped after OpenTelemetry resource and trace
  attributes so a future exporter is a thin adapter
- Span and phase form a small tracing API where every event in a trace
  shares one traceId and child phases carry parentEventId
- Reactive level: the service watches coder.telemetry.level and flushes
  when telemetry is turned off
- Caller properties and measurements reserve the framework-managed keys
  (result, durationMs) at the type level
- Setting is intentionally unregistered until the first sink ships, so
  nothing user-visible activates from this PR alone

Closes #900

Author: EhabY

src/configWatcher.ts

@@ -8,16 +8,18 @@ export interface WatchedSetting {
 
 /**
  * Watch for configuration changes and invoke a callback when values change.
+ * The callback receives a map of changed settings to their new values, so
+ * consumers can act on the new value without re-reading the configuration.
  * Only fires when actual values change, not just when settings are touched.
  */
 export function watchConfigurationChanges(
 	settings: WatchedSetting[],
-	onChange: (changedSettings: string[]) => void,
+	onChange: (changes: ReadonlyMap<string, unknown>) => void,
 ): vscode.Disposable {
 	const appliedValues = new Map(settings.map((s) => [s.setting, s.getValue()]));
 
 	return vscode.workspace.onDidChangeConfiguration((e) => {
-		const changedSettings: string[] = [];
+		const changes = new Map<string, unknown>();
 
 		for (const { setting, getValue } of settings) {
 			if (!e.affectsConfiguration(setting)) {
@@ -27,13 +29,13 @@ export function watchConfigurationChanges(
 			const newValue = getValue();
 
 			if (!configValuesEqual(newValue, appliedValues.get(setting))) {
-				changedSettings.push(setting);
+				changes.set(setting, newValue);
 				appliedValues.set(setting, newValue);
 			}
 		}
 
-		if (changedSettings.length > 0) {
-			onChange(changedSettings);
+		if (changes.size > 0) {
+			onChange(changes);
 		}
 	});
 }

src/core/container.ts

@@ -3,6 +3,7 @@ import * as vscode from "vscode";
 import { CoderApi } from "../api/coderApi";
 import { LoginCoordinator } from "../login/loginCoordinator";
 import { OAuthCallback } from "../oauth/oauthCallback";
+import { TelemetryService } from "../telemetry/service";
 import { SpeedtestPanelFactory } from "../webviews/speedtest/speedtestPanelFactory";
 import { DuplicateWorkspaceIpc } from "../workspace/duplicateWorkspaceIpc";
 
@@ -31,6 +32,7 @@ export class ServiceContainer implements vscode.Disposable {
 	private readonly duplicateWorkspaceIpc: DuplicateWorkspaceIpc;
 	private readonly oauthCallback: OAuthCallback;
 	private readonly speedtestPanelFactory: SpeedtestPanelFactory;
+	private readonly telemetryService: TelemetryService;
 
 	constructor(context: vscode.ExtensionContext) {
 		this.logger = vscode.window.createOutputChannel("Coder", { log: true });
@@ -88,6 +90,7 @@ export class ServiceContainer implements vscode.Disposable {
 			context.extensionUri,
 			this.logger,
 		);
+		this.telemetryService = new TelemetryService(context, [], this.logger);
 	}
 
 	getPathResolver(): PathResolver {
@@ -134,12 +137,18 @@ export class ServiceContainer implements vscode.Disposable {
 		return this.speedtestPanelFactory;
 	}
 
-	/**
-	 * Dispose of all services and clean up resources.
-	 */
-	dispose(): void {
+	getTelemetryService(): TelemetryService {
+		return this.telemetryService;
+	}
+
+	/** Dispose logger last so telemetry teardown warnings still reach it. */
+	async dispose(): Promise<void> {
 		this.contextManager.dispose();
-		this.logger.dispose();
 		this.loginCoordinator.dispose();
+		try {
+			await this.telemetryService.dispose();
+		} finally {
+			this.logger.dispose();
+		}
 	}
 }

src/deployment/deploymentManager.ts

@@ -5,6 +5,7 @@ import { type MementoManager } from "../core/mementoManager";
 import { type SecretsManager } from "../core/secretsManager";
 import { type Logger } from "../logging/logger";
 import { type OAuthSessionManager } from "../oauth/sessionManager";
+import { type TelemetryService } from "../telemetry/service";
 import { type WorkspaceProvider } from "../workspace/workspacesProvider";
 
 import {
@@ -33,6 +34,7 @@ export class DeploymentManager implements vscode.Disposable {
 	private readonly mementoManager: MementoManager;
 	private readonly contextManager: ContextManager;
 	private readonly logger: Logger;
+	private readonly telemetryService: TelemetryService;
 
 	#deployment: Deployment | null = null;
 	#authListenerDisposable: vscode.Disposable | undefined;
@@ -48,6 +50,7 @@ export class DeploymentManager implements vscode.Disposable {
 		this.mementoManager = serviceContainer.getMementoManager();
 		this.contextManager = serviceContainer.getContextManager();
 		this.logger = serviceContainer.getLogger();
+		this.telemetryService = serviceContainer.getTelemetryService();
 	}
 
 	public static create(
@@ -124,6 +127,7 @@ export class DeploymentManager implements vscode.Disposable {
 			user: deployment.user.username,
 		});
 		this.#deployment = { ...deployment };
+		this.telemetryService.setDeploymentUrl(deployment.url);
 
 		// Updates client credentials
 		if (deployment.token === undefined) {
@@ -155,6 +159,7 @@ export class DeploymentManager implements vscode.Disposable {
 		this.#authListenerDisposable?.dispose();
 		this.#authListenerDisposable = undefined;
 		this.#deployment = null;
+		this.telemetryService.setDeploymentUrl("");
 
 		await this.secretsManager.setCurrentDeployment(undefined);
 	}

src/remote/remote.ts

@@ -861,8 +861,8 @@ export class Remote {
 	): vscode.Disposable {
 		const titleMap = new Map(settings.map((s) => [s.setting, s.title]));
 
-		return watchConfigurationChanges(settings, (changedSettings) => {
-			const changedTitles = changedSettings
+		return watchConfigurationChanges(settings, (changes) => {
+			const changedTitles = [...changes.keys()]
 				.map((s) => titleMap.get(s))
 				.filter((t) => t !== undefined);
 

src/telemetry/event.ts

@@ -0,0 +1,107 @@
+import * as os from "node:os";
+import * as vscode from "vscode";
+
+import { toError } from "../error/errorUtils";
+
+/** Telemetry level, mirrors `coder.telemetry.level`. Ordered: off < local. */
+export type TelemetryLevel = "off" | "local";
+
+/** Caller properties. `result` is framework-managed on traced events. */
+export type CallerProperties = Record<string, string> & { result?: never };
+
+/** Caller measurements. `durationMs` is framework-managed on traced events. */
+export type CallerMeasurements = Record<string, number> & {
+	durationMs?: never;
+};
+
+/** Session-stable resource attributes. Field names are inspired by OTel
+ * resource attributes; they are camelCase TypeScript and not a 1:1 mapping. */
+export interface SessionContext {
+	readonly extensionVersion: string;
+	readonly machineId: string;
+	readonly sessionId: string;
+	readonly osType: string;
+	readonly osVersion: string;
+	readonly hostArch: string;
+	readonly platformName: string;
+	readonly platformVersion: string;
+}
+
+/** Per-event context: session attributes plus the current deployment URL. */
+export interface TelemetryContext extends SessionContext {
+	readonly deploymentUrl: string;
+}
+
+export interface TelemetryEvent {
+	readonly eventId: string;
+	readonly eventName: string;
+	readonly timestamp: string;
+	readonly eventSequence: number;
+
+	readonly context: TelemetryContext;
+
+	readonly properties: Readonly<Record<string, string>>;
+	readonly measurements: Readonly<Record<string, number>>;
+
+	/** Shared by all events in a trace. Maps to OTel `trace_id`. */
+	readonly traceId?: string;
+	/** Set on phase children only. Equals the parent event's `eventId`. Maps to OTel `parent_span_id`. */
+	readonly parentEventId?: string;
+
+	readonly error?: Readonly<{
+		message: string;
+		type?: string;
+		code?: string;
+	}>;
+}
+
+/**
+ * Sink for telemetry events. `write` is sync and must buffer in memory; I/O
+ * happens in `flush`/`dispose`. The service filters by `minLevel`; sinks can
+ * still self-gate on other signals (e.g. deployment URL).
+ */
+export interface TelemetrySink {
+	readonly name: string;
+	readonly minLevel: TelemetryLevel;
+	write(event: TelemetryEvent): void;
+	flush(): Promise<void>;
+	dispose(): Promise<void>;
+}
+
+/** Build session attributes. `extensionVersion` falls back to `"unknown"`. */
+export function buildSession(ctx: vscode.ExtensionContext): SessionContext {
+	// "unknown" only for malformed package.json or test fixtures missing `version`.
+	const packageJson = ctx.extension.packageJSON as { version?: unknown };
+	const extensionVersion =
+		typeof packageJson.version === "string" ? packageJson.version : "unknown";
+
+	return {
+		extensionVersion,
+		machineId: vscode.env.machineId,
+		sessionId: vscode.env.sessionId,
+		osType: detectOsType(),
+		osVersion: os.release(),
+		hostArch: process.arch,
+		platformName: vscode.env.appName,
+		platformVersion: vscode.version,
+	};
+}
+
+/** Normalize a thrown value into the event's `error` block. */
+export function buildErrorBlock(
+	value: unknown,
+): NonNullable<TelemetryEvent["error"]> {
+	const err = toError(value);
+	const rawCode = (value as { code?: unknown } | null | undefined)?.code;
+	const hasCode = typeof rawCode === "string" || typeof rawCode === "number";
+	return {
+		message: err.message,
+		...(err.name && err.name !== "Error" && { type: err.name }),
+		...(hasCode && { code: String(rawCode) }),
+	};
+}
+
+// Node uses "win32" on Windows; OTel's os.type is "windows".
+function detectOsType(): string {
+	return process.platform === "win32" ? "windows" : process.platform;
+}