Gate debug logs behind DEBUG environment variable using debug npm package

.vscode/launch.json

@@ -141,9 +141,13 @@
         // Set the telemetry key environment variable to use if you dont want to set it in package.json
         //"TYPESPEC_VSCODE_TELEMETRY_KEY": "{The instrumentation key of your Application Insights}",
 
-        //"ENABLE_SERVER_COMPILE_LOGGING": "true",
-        //"ENABLE_UPDATE_MANAGER_LOGGING": "true",
-        //"ENABLE_LM_LOGGING": "true",
+        // Enable debug logging for specific areas using DEBUG environment variable
+        // Examples:
+        //   "DEBUG": "typespec:server_compile"           - Enable server compilation debug logs
+        //   "DEBUG": "typespec:lm"                       - Enable Language Model debug logs  
+        //   "DEBUG": "typespec:*"                        - Enable all typespec debug logs
+        //   "DEBUG": "typespec:server_compile,typespec:compile_config" - Enable multiple areas
+        //"DEBUG": "typespec:server_compile,typespec:update_manager,typespec:compile_config,typespec:lm",
 
         "TYPESPEC_SERVER_NODE_OPTIONS": "--nolazy --inspect-brk=4242",
         "TYPESPEC_DEVELOPMENT_MODE": "true"

packages/compiler/package.json

@@ -109,6 +109,7 @@
     "@inquirer/prompts": "^8.0.1",
     "ajv": "~8.17.1",
     "change-case": "~5.4.4",
+    "debug": "~4.4.0",
     "env-paths": "^3.0.0",
     "globby": "~16.0.0",
     "is-unicode-supported": "^2.1.0",
@@ -125,6 +126,7 @@
   },
   "devDependencies": {
     "@types/babel__code-frame": "~7.0.6",
+    "@types/debug": "~4.1.12",
     "@types/mustache": "~4.2.5",
     "@types/node": "~25.0.2",
     "@types/semver": "^7.5.8",

packages/compiler/src/server/compile-service.ts

@@ -19,7 +19,7 @@ import { deepClone, distinctArray } from "../utils/misc.js";
 import { getLocationInYamlScript } from "../yaml/diagnostics.js";
 import { parseYaml } from "../yaml/parser.js";
 import { ClientConfigProvider } from "./client-config-provider.js";
-import { serverOptions } from "./constants.js";
+import { debugLoggers, serverOptions } from "./constants.js";
 import { resolveEntrypointFile } from "./entrypoint-resolver.js";
 import { FileService } from "./file-service.js";
 import { FileSystemCache } from "./file-system-cache.js";
@@ -90,6 +90,8 @@ export function createCompileService({
   const eventListeners = new Map<string, (...args: unknown[]) => void | Promise<void>>();
   const compileManager = new ServerCompileManager(updateManager, compilerHost, log);
   let configFilePath: string | undefined;
+  const debug = debugLoggers.compileConfig;
+  const logDebug = debug.enabled ? log : () => {};
 
   return { compile, getScript, on, notifyChange, getMainFileForDocument };
 
@@ -129,15 +131,15 @@ export function createCompileService({
     }
     const mainFile = await getMainFileForDocument(path);
     if (mainFile === undefined) {
-      log({ level: "debug", message: `failed to resolve main file for ${path}` });
+      logDebug({ level: "debug", message: `failed to resolve main file for ${path}` });
       return undefined;
     }
     if (!mainFile.endsWith(".tsp")) {
       return undefined;
     }
     const config = await getConfig(mainFile);
     configFilePath = config.filename;
-    log({ level: "debug", message: `config resolved`, detail: config });
+    logDebug({ level: "debug", message: `config resolved`, detail: config });
     const [optionsFromConfig, _] = resolveOptionsFromConfig(config, {
       cwd: getDirectoryPath(path),
     });
@@ -217,7 +219,7 @@ export function createCompileService({
       ) {
         // If the file that changed wasn't imported by anything from the main
         // file, retry using the file itself as the main file.
-        log({
+        logDebug({
           level: "debug",
           message: `target file was not included in compiling, try to compile ${path} as main file directly`,
         });
@@ -246,7 +248,7 @@ export function createCompileService({
         const [yamlScript] = parseYaml(await serverHost.compilerHost.readFile(configFilePath));
         const target = getLocationInYamlScript(yamlScript, ["emit", emitterName], "key");
         if (target.pos === 0) {
-          log({
+          logDebug({
             level: "debug",
             message: `Unexpected situation, can't find emitter '${emitterName}' in config file '${configFilePath}'`,
           });
@@ -286,7 +288,7 @@ export function createCompileService({
     const lookupDir = entrypointStat.isDirectory() ? mainFile : getDirectoryPath(mainFile);
     const configPath = await findTypeSpecConfigPath(compilerHost, lookupDir, true);
     if (!configPath) {
-      log({
+      logDebug({
         level: "debug",
         message: `can't find path with config file, try to use default config`,
       });
@@ -337,7 +339,7 @@ export function createCompileService({
    */
   async function getMainFileForDocument(path: string) {
     if (path.startsWith("untitled:")) {
-      log({ level: "debug", message: `untitled document treated as its own main file: ${path}` });
+      logDebug({ level: "debug", message: `untitled document treated as its own main file: ${path}` });
       return path;
     }
 

packages/compiler/src/server/constants.ts

@@ -1,4 +1,5 @@
 import { CompilerOptions } from "../core/options.js";
+import createDebug from "debug";
 
 export const serverOptions: CompilerOptions = {
   dryRun: true,
@@ -14,7 +15,16 @@ export const Commands = {
 };
 
 /**
- * Environment variables to enable some logging when needed
+ * Debug loggers for different areas. Can be enabled via DEBUG environment variable.
+ * Usage: DEBUG=typespec:server_compile,typespec:compile_config
+ * 
+ * Examples:
+ *   DEBUG=typespec:server_compile      - Enable server compilation debug logs
+ *   DEBUG=typespec:*                   - Enable all typespec debug logs
+ *   DEBUG=typespec:server_compile,typespec:compile_config - Enable multiple areas
  */
-export const ENABLE_SERVER_COMPILE_LOGGING = "ENABLE_SERVER_COMPILE_LOGGING";
-export const ENABLE_UPDATE_MANAGER_LOGGING = "ENABLE_UPDATE_MANAGER_LOGGING";
+export const debugLoggers = {
+  serverCompile: createDebug("typespec:server_compile"),
+  updateManager: createDebug("typespec:update_manager"),
+  compileConfig: createDebug("typespec:compile_config"),
+} as const;

packages/compiler/src/server/entrypoint-resolver.ts

@@ -3,6 +3,7 @@ import { getDirectoryPath, joinPaths } from "../core/path-utils.js";
 import { SystemHost, Diagnostic as TypeSpecDiagnostic } from "../core/types.js";
 import { doIO, loadFile } from "../utils/io.js";
 import { resolveTspMain } from "../utils/misc.js";
+import { debugLoggers } from "./constants.js";
 import { FileSystemCache } from "./file-system-cache.js";
 import { ServerLog } from "./types.js";
 
@@ -14,6 +15,8 @@ export async function resolveEntrypointFile(
   log: (log: ServerLog) => void,
 ): Promise<string | undefined> {
   const options = { allowFileNotFound: true };
+  const debug = debugLoggers.compileConfig;
+  const logDebug = debug.enabled ? log : () => {};
 
   const pathStat = await doIO(() => host.stat(path), path, logMainFileSearchDiagnostic, options);
   const isFilePath = pathStat?.isFile() ?? false;
@@ -36,22 +39,22 @@ export async function resolveEntrypointFile(
 
     const tspMain = resolveTspMain(pkg);
     if (typeof tspMain === "string") {
-      log({
+      logDebug({
         level: "debug",
         message: `tspMain resolved from package.json (${pkgPath}) as ${tspMain}`,
       });
 
       const packageJsonEntrypoint = await existingFile(dir, tspMain);
       if (packageJsonEntrypoint) {
-        log({ level: "debug", message: `entrypoint file found as ${packageJsonEntrypoint}` });
+        logDebug({ level: "debug", message: `entrypoint file found as ${packageJsonEntrypoint}` });
         return packageJsonEntrypoint;
       }
     }
 
     for (const entrypoint of entrypoints) {
       const candidate = await existingFile(dir, entrypoint);
       if (candidate) {
-        log({
+        logDebug({
           level: "debug",
           message: `main file found using client provided entrypoint: ${candidate}`,
         });
@@ -67,7 +70,7 @@ export async function resolveEntrypointFile(
     dir = parentDir;
   }
 
-  log({ level: "debug", message: `reached directory root, using '${path}' as main file` });
+  logDebug({ level: "debug", message: `reached directory root, using '${path}' as main file` });
   return isFilePath ? path : undefined;
 
   function logMainFileSearchDiagnostic(diagnostic: TypeSpecDiagnostic) {

packages/compiler/src/server/server-compile-manager.ts

@@ -9,7 +9,7 @@ import {
   ServerLog,
 } from "../index.js";
 import { getEnvironmentVariable } from "../utils/misc.js";
-import { ENABLE_SERVER_COMPILE_LOGGING } from "./constants.js";
+import { debugLoggers } from "./constants.js";
 import { trackActionFunc } from "./server-track-action-task.js";
 import { UpdateManager } from "./update-manager.js";
 
@@ -45,10 +45,10 @@ export class ServerCompileManager {
     private compilerHost: CompilerHost,
     private log: (log: ServerLog) => void,
   ) {
-    this.logDebug =
-      getEnvironmentVariable(ENABLE_SERVER_COMPILE_LOGGING)?.toLowerCase() === "true"
-        ? (msg) => this.log({ level: "debug", message: msg })
-        : () => {};
+    const debug = debugLoggers.serverCompile;
+    this.logDebug = debug.enabled
+      ? (msg) => this.log({ level: "debug", message: msg })
+      : () => {};
   }
 
   async compile(

packages/compiler/src/server/serverlib.ts

@@ -104,7 +104,7 @@ import { getSemanticTokens } from "./classify.js";
 import { ClientConfigProvider } from "./client-config-provider.js";
 import { createCompileService } from "./compile-service.js";
 import { resolveCompletion } from "./completion.js";
-import { Commands } from "./constants.js";
+import { Commands, debugLoggers } from "./constants.js";
 import { convertDiagnosticToLsp } from "./diagnostics.js";
 import { createFileService } from "./file-service.js";
 import { createFileSystemCache } from "./file-system-cache.js";
@@ -1138,7 +1138,7 @@ export function createServer(
           compilerHost,
           emitterProvider,
           linterProvider,
-          log,
+          log: logCompileConfig,
         });
         return CompletionList.create(items);
       }
@@ -1412,6 +1412,12 @@ export function createServer(
     host.log(log);
   }
 
+  function logCompileConfig(logMessage: ServerLog) {
+    if (debugLoggers.compileConfig.enabled) {
+      log(logMessage);
+    }
+  }
+
   function sendDiagnostics(document: TextDocument, diagnostics: VSDiagnostic[]) {
     host.sendDiagnostics({
       uri: document.uri,

packages/compiler/src/server/update-manager.ts

@@ -1,7 +1,7 @@
 import { TextDocumentIdentifier } from "vscode-languageserver";
 import { TextDocument } from "vscode-languageserver-textdocument";
 import { getEnvironmentVariable } from "../utils/misc.js";
-import { ENABLE_UPDATE_MANAGER_LOGGING } from "./constants.js";
+import { debugLoggers } from "./constants.js";
 import { ServerLog } from "./types.js";
 
 interface PendingUpdate {
@@ -43,12 +43,12 @@ export class UpdateManager<T = void> {
     log: (sl: ServerLog) => void,
     getDebounceDelay?: () => number,
   ) {
-    this._log =
-      getEnvironmentVariable(ENABLE_UPDATE_MANAGER_LOGGING)?.toLowerCase() === "true"
-        ? (sl: ServerLog) => {
-            log({ ...sl, message: `#FromUpdateManager(${this.name}): ${sl.message}` });
-          }
-        : () => {};
+    const debug = debugLoggers.updateManager;
+    this._log = debug.enabled
+      ? (sl: ServerLog) => {
+          log({ ...sl, message: `#FromUpdateManager(${this.name}): ${sl.message}` });
+        }
+      : () => {};
 
     // Set the debounce delay function once during construction
     this.getDebounceDelay = getDebounceDelay ?? this.getAdaptiveDebounceDelay;

packages/typespec-vscode/package.json

@@ -309,6 +309,10 @@
     "vitest": "^4.0.15",
     "vscode-languageclient": "~9.0.1",
     "which": "^6.0.0",
-    "yaml": "~2.8.2"
+    "yaml": "~2.8.2",
+    "@types/debug": "~4.1.12"
+  },
+  "dependencies": {
+    "debug": "~4.4.0"
   }
 }

packages/typespec-vscode/src/const.ts

@@ -1,5 +1,14 @@
+import createDebug from "debug";
+
 export const StartFileName = "main.tsp";
 export const TspConfigFileName = "tspconfig.yaml";
 export const EmptyGuid = "00000000-0000-0000-0000-000000000000";
 
-export const ENABLE_LM_LOGGING = "ENABLE_LM_LOGGING";
+/**
+ * Debug logger for Language Model operations.
+ * Can be enabled via DEBUG environment variable.
+ * Usage: DEBUG=typespec:lm
+ */
+export const debugLoggers = {
+  lm: createDebug("typespec:lm"),
+} as const;

packages/typespec-vscode/src/lm/language-model.ts

@@ -1,6 +1,6 @@
 import { inspect } from "util";
 import { LanguageModelChat, LanguageModelChatMessage, lm } from "vscode";
-import { ENABLE_LM_LOGGING } from "../const";
+import { debugLoggers } from "../const";
 import logger, { LogItem } from "../log/logger";
 import { RetryResult, runWithRetry, runWithTimingLog } from "../utils";
 
@@ -23,7 +23,8 @@ export async function sendLmChatRequest(
   /** Only for logging purpose */
   id?: string,
 ): Promise<string | undefined> {
-  const logEnabled = process.env[ENABLE_LM_LOGGING] === "true";
+  const debug = debugLoggers.lm;
+  const logEnabled = debug.enabled;
   const lmLog = (item: LogItem) => {
     if (logEnabled || item.level === "error" || item.level === "warning") {
       logger.log(