Improve telemetry instrumentation and error diagnostics for typespec-vscode

[RodgeFu]

Improve telemetry instrumentation and error diagnostics

Summary

Based on analysis of 2 weeks of telemetry data (71K+ events, 2,327 unique users), this PR improves telemetry instrumentation gaps and error diagnostics across the typespec-vscode extension and the compiler LSP server.

Changes

Extension telemetry improvements (packages/typespec-vscode)

install-tsp-compiler.ts — Added lastStep tracking and logOperationDetailTelemetry for failure/timeout cases. Previously, all 3 install failures in the dataset had lastStep=undefined and zero error detail.

openapi3-preview.ts — Refactored getOpenApi3OutputFilePath to return Result<string> instead of string | undefined to properly distinguish compile failures from user cancellations. Added lastStep for the success path ("Preview panel opened"). Added compile error details to telemetry.

extension.ts (start-server) — Added lastStep for the "compiler not found" state before the install prompt, and for the cancelled-install path. These covered 66 events (34 fail + 32 cancelled) that previously had lastStep=undefined.

extension.ts (server-path-changed) — Added lastStep for the config change handler. All 30 events previously had lastStep=undefined.

Better error message for node/tsp not on PATH (packages/typespec-vscode)

tsp-executable-resolver.ts — When the compiler is found locally but neither node nor tsp is available on PATH, the extension now shows an actionable error message explaining the likely cause (nvm/fnm/volta PATH not inherited) and three concrete fixes. Previously, this silently fell through to spawn tsp ENOENT. This was the #1 root cause of blocked users — 107 failure events from users who never recovered.

Server-side error detail preservation (packages/compiler)

serverlib.ts — Added wrapUnhandledError wrapper around all LSP server handlers. When a handler crashes, the wrapper catches the error and re-throws with the full server-side stack trace in the error message (via inspect(e)). Previously, the JSON-RPC layer only forwarded error.message to the client, so the server-side crash location was completely lost in telemetry. This addresses the 297 Cannot read properties of undefined (reading 'kind') errors that were previously opaque.

Telemetry data highlights

• 2,327 total users in the 2-week window
• 101 users (4.3%) completely blocked — never had a successful start-server in 2 weeks
• Add PR Validation #1 root cause: spawn tsp ENOENT (node not on PATH) — 107 events from never-recovered users, disproportionately macOS (60%)
• Fix PR validation #2 root cause: compiler not found — 50 events
• 297 reading 'kind' unhandled errors — now will include server-side stack for future diagnosis

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@typespec/compiler@10847

npm i https://pkg.pr.new/typespec-vscode@10847

commit: 74e380e

[github-actions]

All changed packages have been documented.

• ✅ @typespec/compiler
• ✅ typespec-vscode

Show changes

@typespec/compiler - fix ✏️

Wrapped LSP server handlers with wrapUnhandledError to preserve server-side stack traces in error messages forwarded to the client. Previously, the JSON-RPC layer discarded the original stack trace, making unhandled errors in telemetry opaque.

typespec-vscode - fix ✏️

Improved telemetry instrumentation for install-global-compiler-cli, preview-openapi3, start-server, and server-path-changed events by adding missing lastStep tracking and error detail logging. Added actionable error message when compiler is found but neither node nor tsp is available on PATH, guiding users to fix common nvm/fnm/volta configuration issues.

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website	🛝 VSCode Extension