From 5e57d6736f41c3c13959e6b58683e98f0e92655d Mon Sep 17 00:00:00 2001 From: eleanorjboyd <26030610+eleanorjboyd@users.noreply.github.com> Date: Fri, 27 Feb 2026 09:44:40 -0800 Subject: [PATCH 1/2] feat: enhance environment discovery logging and troubleshooting guidance --- src/common/constants.ts | 1 + src/common/telemetry/helpers.ts | 42 ++++++++++++++++++++++++++++++++- src/extension.ts | 9 ++++++- src/internal.api.ts | 30 ++++++++++++++++++++--- 4 files changed, 77 insertions(+), 5 deletions(-) diff --git a/src/common/constants.ts b/src/common/constants.ts index a804df6e..80de2b54 100644 --- a/src/common/constants.ts +++ b/src/common/constants.ts @@ -4,6 +4,7 @@ export const ENVS_EXTENSION_ID = 'ms-python.vscode-python-envs'; export const PYTHON_EXTENSION_ID = 'ms-python.python'; export const JUPYTER_EXTENSION_ID = 'ms-toolsai.jupyter'; export const EXTENSION_ROOT_DIR = path.dirname(__dirname); +export const ISSUES_URL = 'https://github.com/microsoft/vscode-python-environments/issues'; export const DEFAULT_PACKAGE_MANAGER_ID = 'ms-python.python:pip'; export const DEFAULT_ENV_MANAGER_ID = 'ms-python.python:venv'; diff --git a/src/common/telemetry/helpers.ts b/src/common/telemetry/helpers.ts index 8a226d0f..5e3435f7 100644 --- a/src/common/telemetry/helpers.ts +++ b/src/common/telemetry/helpers.ts @@ -1,5 +1,7 @@ import { getDefaultEnvManagerSetting, getDefaultPkgManagerSetting } from '../../features/settings/settingHelpers'; import { EnvironmentManagers, PythonProjectManager } from '../../internal.api'; +import { ISSUES_URL } from '../constants'; +import { traceInfo, traceWarn } from '../logging'; import { getWorkspaceFolders } from '../workspace.apis'; import { EventNames } from './constants'; import { sendTelemetryEvent } from './sender'; @@ -58,7 +60,7 @@ export async function sendProjectStructureTelemetry( for (const wsFolder of workspaceFolders) { const workspacePath = wsFolder.uri.fsPath; const projectPath = project.uri.fsPath; - + // Check if project is a subdirectory of workspace folder: // - Path must start with workspace path // - Path must not be equal to workspace path @@ -80,3 +82,41 @@ export async function sendProjectStructureTelemetry( projectUnderRoot, }); } + +/** + * Logs a summary of environment discovery results after startup. + * If no environments are found, logs guidance to help users troubleshoot. + */ +export async function logDiscoverySummary(envManagers: EnvironmentManagers): Promise { + const managers = envManagers.managers; + let totalEnvCount = 0; + const managerSummaries: string[] = []; + + for (const manager of managers) { + try { + const envs = await manager.getEnvironments('all'); + totalEnvCount += envs.length; + if (envs.length > 0) { + managerSummaries.push(`${manager.displayName}: ${envs.length}`); + } + } catch { + // Discovery errors are already logged by InternalEnvironmentManager.refresh() + } + } + + if (totalEnvCount === 0) { + traceWarn( + `No Python environments were found.\n` + + ` This may cause issues with Python tooling in VS Code.\n` + + ` Troubleshooting:\n` + + ` - Ensure Python is installed and on your PATH\n` + + ` - Check if your virtual environment has an 'activate' script\n` + + ` - Try running "Python Environments: Refresh All Environment Managers"\n` + + ` If environments should be detected, please report this: ${ISSUES_URL}/new`, + ); + } else { + traceInfo( + `Environment discovery complete: ${totalEnvCount} environments found (${managerSummaries.join(', ')})`, + ); + } +} diff --git a/src/extension.ts b/src/extension.ts index b03c5132..df71ac90 100644 --- a/src/extension.ts +++ b/src/extension.ts @@ -17,7 +17,11 @@ import { clearPersistentState, setPersistentState } from './common/persistentSta import { newProjectSelection } from './common/pickers/managers'; import { StopWatch } from './common/stopWatch'; import { EventNames } from './common/telemetry/constants'; -import { sendManagerSelectionTelemetry, sendProjectStructureTelemetry } from './common/telemetry/helpers'; +import { + logDiscoverySummary, + sendManagerSelectionTelemetry, + sendProjectStructureTelemetry, +} from './common/telemetry/helpers'; import { sendTelemetryEvent } from './common/telemetry/sender'; import { createDeferred } from './common/utils/deferred'; @@ -545,6 +549,9 @@ export async function activate(context: ExtensionContext): Promise { const sw = new StopWatch(); + const SLOW_DISCOVERY_THRESHOLD_MS = 15000; try { await this.manager.refresh(options); const envs = await this.manager.getEnvironments('all').catch(() => []); - sendTelemetryEvent(EventNames.ENVIRONMENT_DISCOVERY, sw.elapsedTime, { + const duration = sw.elapsedTime; + sendTelemetryEvent(EventNames.ENVIRONMENT_DISCOVERY, duration, { managerId: this.id, result: 'success', envCount: envs.length, }); + + // Log warning for slow discovery + if (duration > SLOW_DISCOVERY_THRESHOLD_MS) { + traceWarn( + `[${this.displayName}] Environment discovery took ${(duration / 1000).toFixed(1)}s (found ${envs.length} environments). ` + + `If this is causing problems, please report it: ${ISSUES_URL}/new`, + ); + } } catch (ex) { + const duration = sw.elapsedTime; const isTimeout = ex instanceof Error && ex.message.includes('timed out'); + const errorType = ex instanceof Error ? ex.name : 'unknown'; sendTelemetryEvent( EventNames.ENVIRONMENT_DISCOVERY, - sw.elapsedTime, + duration, { managerId: this.id, result: isTimeout ? 'timeout' : 'error', - errorType: ex instanceof Error ? ex.name : 'unknown', + errorType, }, ex instanceof Error ? ex : undefined, ); + + // Log verbose failure message to help users report issues + const errorMessage = ex instanceof Error ? ex.message : String(ex); + traceWarn( + `[${this.displayName}] Environment discovery failed after ${(duration / 1000).toFixed(1)}s.\n` + + ` Error: ${errorType} - ${errorMessage}\n` + + ` If environments are not being detected correctly, please report this issue:\n` + + ` ${ISSUES_URL}/new`, + ); + throw ex; } } From d92b648b9ac195f18df07440a9d2403765284e1d Mon Sep 17 00:00:00 2001 From: eleanorjboyd <26030610+eleanorjboyd@users.noreply.github.com> Date: Fri, 27 Feb 2026 09:51:34 -0800 Subject: [PATCH 2/2] fix debug --- src/common/telemetry/helpers.ts | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/src/common/telemetry/helpers.ts b/src/common/telemetry/helpers.ts index 5e3435f7..da7ce970 100644 --- a/src/common/telemetry/helpers.ts +++ b/src/common/telemetry/helpers.ts @@ -106,13 +106,9 @@ export async function logDiscoverySummary(envManagers: EnvironmentManagers): Pro if (totalEnvCount === 0) { traceWarn( - `No Python environments were found.\n` + - ` This may cause issues with Python tooling in VS Code.\n` + - ` Troubleshooting:\n` + - ` - Ensure Python is installed and on your PATH\n` + - ` - Check if your virtual environment has an 'activate' script\n` + - ` - Try running "Python Environments: Refresh All Environment Managers"\n` + - ` If environments should be detected, please report this: ${ISSUES_URL}/new`, + `No Python environments were found. ` + + `Try running "Python Environments: Run Python Environment Tool (PET) in Terminal..." from the Command Palette to diagnose. ` + + `If environments should be detected, please report this: ${ISSUES_URL}/new`, ); } else { traceInfo(