Expand logging coverage across entire extension

- Add leveled logging to all commands, services, utilities, and providers
- Add diagnostic detail logging with severity, line number, and message
- Fix log flooding from repeated running state checks (only log on change)
- Fix feedback loop from Output Channel document events triggering diagnostics
- Promote key startup logs from debug to info/warn level
- Update CHANGELOG to reflect expanded logging scope and bug fixes

Author: garrytrinder

CHANGELOG.md

@@ -11,11 +11,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added:
 
-- Logging: Added debug logging to Output panel (`Dev Proxy Toolkit`) to help investigate issues
+- Logging: Added leveled logging to Output panel (`Dev Proxy Toolkit`) across the entire extension covering commands, diagnostics, services, and utilities to help investigate issues
 - Quick Fixes: Enable local language model fix now adds or updates `languageModel.enabled: true` for supported plugins only
 
 ### Fixed:
 
+- Logging: Fixed log flooding from repeated running state checks by only logging on state changes
+- Logging: Fixed log feedback loop caused by Output Channel document events triggering diagnostics
+
 - Diagnostics: Language model diagnostic now correctly targets plugins that can use a local language model (OpenAIMockResponsePlugin, OpenApiSpecGeneratorPlugin, TypeSpecGeneratorPlugin) and shows as an informational hint instead of a warning
 
 ## [1.12.0] - 2026-01-29

src/code-actions.ts

@@ -4,6 +4,7 @@ import parse from 'json-to-ast';
 import { getASTNode, getRangeFromASTNode } from './utils';
 import { pluginSnippets } from './data';
 import snippetsJson from './snippets/json-snippets.json';
+import * as logger from './logger';
 
 /**
  * Extract the diagnostic code value from the object format.
@@ -60,6 +61,7 @@ export const registerCodeActions = (context: vscode.ExtensionContext) => {
     context.globalState.get<DevProxyInstall>('devProxyInstall');
 
   if (!devProxyInstall) {
+    logger.debug('Dev Proxy install not found, code actions disabled');
     return;
   }
 
@@ -123,8 +125,8 @@ export function extractSchemaFilename(schemaUrl: string): string {
     if (match) {
       return match[1];
     }
-  } catch {
-    // Fall through to default
+  } catch (error) {
+    logger.warn('Failed to extract schema filename, using default', { schemaUrl, error });
   }
 
   return defaultSchema;

src/code-lens.ts

@@ -2,6 +2,7 @@ import * as vscode from 'vscode';
 import { isConfigFile, getASTNode, getRangeFromASTNode } from './utils';
 import parse from 'json-to-ast';
 import { pluginSnippets } from './data';
+import * as logger from './logger';
 
 export const registerCodeLens = (context: vscode.ExtensionContext) => {
   context.subscriptions.push(
@@ -31,44 +32,48 @@ export const pluginLensProvider: vscode.CodeLensProvider = {
 export const createCodeLensForPluginNodes = (document: vscode.TextDocument) => {
   const codeLens: vscode.CodeLens[] = [];
   if (isConfigFile(document)) {
-    const documentNode = parse(document.getText()) as parse.ObjectNode;
-    const pluginsNode = getASTNode(
-      documentNode.children,
-      'Identifier',
-      'plugins'
-    );
+    try {
+      const documentNode = parse(document.getText()) as parse.ObjectNode;
+      const pluginsNode = getASTNode(
+        documentNode.children,
+        'Identifier',
+        'plugins'
+      );
 
-    if (
-      pluginsNode &&
-      (pluginsNode.value as parse.ArrayNode).children.length !== 0
-    ) {
-      const pluginNodes = (pluginsNode.value as parse.ArrayNode)
-        .children as parse.ObjectNode[];
+      if (
+        pluginsNode &&
+        (pluginsNode.value as parse.ArrayNode).children.length !== 0
+      ) {
+        const pluginNodes = (pluginsNode.value as parse.ArrayNode)
+          .children as parse.ObjectNode[];
 
-      pluginNodes.forEach((pluginNode: parse.ObjectNode) => {
-        const pluginNameNode = getASTNode(
-          pluginNode.children,
-          'Identifier',
-          'name'
-        );
-        if (!pluginNameNode) {
-          return;
-        }
-        const pluginName = (pluginNameNode?.value as parse.LiteralNode)
-          .value as string;
+        pluginNodes.forEach((pluginNode: parse.ObjectNode) => {
+          const pluginNameNode = getASTNode(
+            pluginNode.children,
+            'Identifier',
+            'name'
+          );
+          if (!pluginNameNode) {
+            return;
+          }
+          const pluginName = (pluginNameNode?.value as parse.LiteralNode)
+            .value as string;
 
-        const isValidName = pluginSnippets[pluginName];
+          const isValidName = pluginSnippets[pluginName];
 
-        if (isValidName) {
-          codeLens.push(
-            new vscode.CodeLens(getRangeFromASTNode(pluginNameNode), {
-              title: `📄 ${pluginName}`,
-              command: 'dev-proxy-toolkit.openPluginDoc',
-              arguments: [pluginName],
-            })
-          );
-        }
-      });
+          if (isValidName) {
+            codeLens.push(
+              new vscode.CodeLens(getRangeFromASTNode(pluginNameNode), {
+                title: `📄 ${pluginName}`,
+                command: 'dev-proxy-toolkit.openPluginDoc',
+                arguments: [pluginName],
+              })
+            );
+          }
+        });
+      }
+    } catch (error) {
+      logger.warn('Failed to parse config file for code lens generation', { file: document.fileName, error });
     }
   }
 

src/commands/config.ts

@@ -3,6 +3,7 @@ import { Commands } from '../constants';
 import { executeCommand } from '../utils/shell';
 import { getDevProxyExe } from '../detect';
 import { VersionPreference } from '../enums';
+import * as logger from '../logger';
 
 /**
  * Configuration file commands: open, create new.
@@ -25,6 +26,7 @@ export function registerConfigCommands(
 }
 
 async function openConfig(devProxyExe: string): Promise<void> {
+  logger.debug('Opening Dev Proxy config', { devProxyExe });
   await executeCommand(`${devProxyExe} config open`);
 }
 
@@ -36,15 +38,18 @@ async function createNewConfig(devProxyExe: string): Promise<void> {
 
   const workspaceFolder = vscode.workspace.workspaceFolders?.[0]?.uri.fsPath;
   if (!workspaceFolder) {
+    logger.warn('Cannot create config: no workspace folder open');
     vscode.window.showErrorMessage('No workspace folder open');
     return;
   }
+  logger.info('Creating new config file', { fileName, workspaceFolder });
 
   const devProxyFolder = vscode.Uri.file(`${workspaceFolder}/.devproxy`);
   const configUri = vscode.Uri.file(`${workspaceFolder}/.devproxy/${fileName}`);
 
   // Check if file already exists
   if (await fileExists(configUri)) {
+    logger.warn('Config file already exists', { path: configUri.fsPath });
     vscode.window.showErrorMessage('A file with that name already exists');
     return;
   }
@@ -67,9 +72,11 @@ async function createNewConfig(devProxyExe: string): Promise<void> {
     );
 
     // Open the newly created file
+    logger.info('Config file created', { path: configUri.fsPath });
     const document = await vscode.workspace.openTextDocument(configUri);
     await vscode.window.showTextDocument(document);
   } catch (error) {
+    logger.error('Failed to create new config file', error);
     vscode.window.showErrorMessage('Failed to create new config file');
   }
 }

src/commands/discovery.ts

@@ -3,6 +3,7 @@ import { Commands } from '../constants';
 import { TerminalService } from '../services/terminal';
 import { getDevProxyExe } from '../detect';
 import { VersionPreference } from '../enums';
+import * as logger from '../logger';
 
 /**
  * URL discovery command.
@@ -40,10 +41,12 @@ async function discoverUrlsToWatch(
 
   // User cancelled
   if (processNames === undefined) {
+    logger.debug('URL discovery cancelled by user');
     return;
   }
 
   const command = buildDiscoverCommand(devProxyExe, processNames);
+  logger.info('Starting URL discovery', { processNames: processNames || '(all processes)', command });
   terminalService.sendCommand(terminal, command);
 }
 

src/commands/docs.ts

@@ -3,6 +3,7 @@ import { Commands } from '../constants';
 import { pluginDocs } from '../data';
 import parse from 'json-to-ast';
 import { getASTNode, getRangeFromASTNode } from '../utils/ast';
+import * as logger from '../logger';
 
 /**
  * Documentation and language model configuration commands.
@@ -21,8 +22,11 @@ export function registerDocCommands(context: vscode.ExtensionContext): void {
 function openPluginDocumentation(pluginName: string): void {
   const doc = pluginDocs[pluginName];
   if (doc) {
+    logger.debug('Opening plugin docs', { pluginName, url: doc.url });
     const target = vscode.Uri.parse(doc.url);
     vscode.env.openExternal(target);
+  } else {
+    logger.warn('Plugin docs not found', { pluginName });
   }
 }
 
@@ -42,11 +46,13 @@ async function addLanguageModelConfig(uri: vscode.Uri): Promise<void> {
     }
   } catch (error) {
     // Fallback to simple text-based insertion
+    logger.debug('Failed to parse document with json-to-ast, using text-based fallback', error);
     addLanguageModelFallback(document, edit, uri);
   }
 
   await vscode.workspace.applyEdit(edit);
   await document.save();
+  logger.info('Language model configuration added');
 
   vscode.window.showInformationMessage('Language model configuration added');
 }

src/commands/install.ts

@@ -7,6 +7,7 @@ import {
   openUpgradeDocumentation,
 } from '../utils/shell';
 import { PackageManager, VersionPreference } from '../enums';
+import * as logger from '../logger';
 
 /**
  * Installation and upgrade commands.
@@ -33,6 +34,7 @@ async function installDevProxy(
 ): Promise<void> {
   const message = vscode.window.setStatusBarMessage('Installing Dev Proxy...');
   const versionPreference = configuration.get('version') as VersionPreference;
+  logger.info('Installing Dev Proxy', { platform, versionPreference });
 
   try {
     if (platform === 'win32') {
@@ -41,6 +43,7 @@ async function installDevProxy(
       await installOnMac(versionPreference);
     } else if (platform === 'linux') {
       // Linux requires manual installation
+      logger.info('Linux detected, opening install docs');
       vscode.env.openExternal(vscode.Uri.parse(Urls.linuxInstall));
     }
   } finally {
@@ -55,17 +58,21 @@ async function installOnWindows(versionPreference: VersionPreference): Promise<v
   try {
     await executeCommand('winget --version');
   } catch {
+    logger.warn('Winget not found on PATH');
     vscode.window.showErrorMessage('Winget is not installed. Please install winget and try again.');
     return;
   }
 
   try {
+    logger.info('Installing Dev Proxy via winget', { packageId });
     await executeCommand(`winget install ${packageId} --silent`);
+    logger.info('Dev Proxy installed successfully via winget');
     const result = await vscode.window.showInformationMessage('Dev Proxy installed.', 'Reload');
     if (result === 'Reload') {
       await vscode.commands.executeCommand('workbench.action.reloadWindow');
     }
   } catch (error) {
+    logger.error('Failed to install Dev Proxy via winget', error);
     vscode.window.showErrorMessage(`Failed to install Dev Proxy.\n${error}`);
   }
 }
@@ -77,18 +84,22 @@ async function installOnMac(versionPreference: VersionPreference): Promise<void>
   try {
     await executeCommand('brew --version');
   } catch {
+    logger.warn('Homebrew not found on PATH');
     vscode.window.showErrorMessage('Homebrew is not installed. Please install brew and try again.');
     return;
   }
 
   try {
+    logger.info('Installing Dev Proxy via Homebrew', { packageId });
     await executeCommand('brew tap dotnet/dev-proxy');
     await executeCommand(`brew install ${packageId}`);
+    logger.info('Dev Proxy installed successfully via Homebrew');
     const result = await vscode.window.showInformationMessage('Dev Proxy installed.', 'Reload');
     if (result === 'Reload') {
       await vscode.commands.executeCommand('workbench.action.reloadWindow');
     }
   } catch (error) {
+    logger.error('Failed to install Dev Proxy via Homebrew', error);
     vscode.window.showErrorMessage(`Failed to install Dev Proxy.\n${error}`);
   }
 }
@@ -97,9 +108,11 @@ async function upgradeDevProxy(configuration: vscode.WorkspaceConfiguration): Pr
   const platform = process.platform;
   const versionPreference = configuration.get('version') as VersionPreference;
   const isBeta = versionPreference === VersionPreference.Beta;
+  logger.info('Upgrading Dev Proxy', { platform, versionPreference });
 
   // Linux always redirects to documentation
   if (platform === 'linux') {
+    logger.info('Linux detected, opening upgrade docs');
     openUpgradeDocumentation();
     return;
   }
@@ -119,6 +132,7 @@ async function upgradeDevProxy(configuration: vscode.WorkspaceConfiguration): Pr
       isBeta
     );
     if (!upgraded) {
+      logger.warn('Upgrade via winget failed, opening upgrade docs');
       openUpgradeDocumentation();
     }
     return;
@@ -139,11 +153,13 @@ async function upgradeDevProxy(configuration: vscode.WorkspaceConfiguration): Pr
       isBeta
     );
     if (!upgraded) {
+      logger.warn('Upgrade via Homebrew failed, opening upgrade docs');
       openUpgradeDocumentation();
     }
     return;
   }
 
   // Unknown platform
+  logger.warn('Unknown platform, opening upgrade docs', { platform });
   openUpgradeDocumentation();
 }

src/commands/jwt.ts

@@ -3,6 +3,7 @@ import { Commands } from '../constants';
 import { executeCommand } from '../utils/shell';
 import { getDevProxyExe } from '../detect';
 import { VersionPreference } from '../enums';
+import * as logger from '../logger';
 
 /**
  * JWT (JSON Web Token) generation commands.
@@ -36,8 +37,10 @@ interface JwtParams {
 async function createJwt(devProxyExe: string): Promise<void> {
   const params = await collectJwtParams();
   if (!params) {
+    logger.debug('JWT creation cancelled by user');
     return; // User cancelled
   }
+  logger.info('Generating JWT', { name: params.name, issuer: params.issuer, audiences: params.audiences.length, roles: params.roles.length, scopes: params.scopes.length, validFor: params.validFor });
 
   await vscode.window.withProgress(
     {
@@ -50,8 +53,10 @@ async function createJwt(devProxyExe: string): Promise<void> {
         const command = buildJwtCommand(devProxyExe, params);
         const result = await executeCommand(command);
         const token = extractToken(result);
+        logger.info('JWT token generated successfully');
         await presentToken(token, command);
       } catch (error) {
+        logger.error('Failed to generate JWT token', error);
         vscode.window.showErrorMessage(`Failed to generate JWT token: ${error}`);
       }
     }

src/commands/proxy.ts

@@ -62,10 +62,12 @@ async function stopDevProxy(
 
   const closeTerminal = configuration.get<boolean>('closeTerminal', true);
   if (closeTerminal) {
+    logger.debug('Waiting for Dev Proxy to stop before closing terminal');
     await waitForProxyToStop(apiClient);
 
     const terminalService = TerminalService.fromConfiguration();
     terminalService.disposeDevProxyTerminals();
+    logger.debug('Dev Proxy terminals disposed');
   }
 }
 
@@ -88,7 +90,9 @@ async function restartDevProxy(
       : devProxyExe;
 
     terminalService.sendCommand(terminal, command);
-  } catch {
+    logger.debug('Dev Proxy restart command sent');
+  } catch (error) {
+    logger.error('Failed to restart Dev Proxy', error);
     vscode.window.showErrorMessage('Failed to restart Dev Proxy');
   }
 }