telemetry - document keys (#155563)

2 files changed, 30 insertions, 24 deletions

diff --git a/src/vs/base/common/actions.ts b/src/vs/base/common/actions.ts
index f9729a18770..cfaa9389600 100644
--- a/src/vs/base/common/actions.ts
+++ b/src/vs/base/common/actions.ts
@@ -15,8 +15,8 @@ export interface ITelemetryData {
 
 export type WorkbenchActionExecutedClassification = {
 	owner: 'bpasero';
-	id: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
-	from: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
+	id: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The identifier of the action that was run.' };
+	from: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The name of the component the action was run from.' };
 };
 
 export type WorkbenchActionExecutedEvent = {
diff --git a/src/vs/workbench/contrib/telemetry/browser/telemetry.contribution.ts b/src/vs/workbench/contrib/telemetry/browser/telemetry.contribution.ts
index 674741ed4d0..40346309f5e 100644
--- a/src/vs/workbench/contrib/telemetry/browser/telemetry.contribution.ts
+++ b/src/vs/workbench/contrib/telemetry/browser/telemetry.contribution.ts
@@ -36,11 +36,11 @@ type TelemetryData = {
 };
 
 type FileTelemetryDataFragment = {
-	mimeType: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
-	ext: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
-	path: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
-	reason?: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
-	allowlistedjson?: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
+	mimeType: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The language type of the file (for example XML).' };
+	ext: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The file extension of the file (for example xml).' };
+	path: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The path of the file as a hash.' };
+	reason?: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'The reason why a file is read or written. Allows to e.g. distinguish auto save from normal save.' };
+	allowlistedjson?: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The name of the file but only if it matches some well known file names such as package.json or tsconfig.json.' };
 };
 
 export class TelemetryContribution extends Disposable implements IWorkbenchContribution {
@@ -67,27 +67,29 @@ export class TelemetryContribution extends Disposable implements IWorkbenchContr
 		const activeViewlet = paneCompositeService.getActivePaneComposite(ViewContainerLocation.Sidebar);
 
 		type WindowSizeFragment = {
-			innerHeight: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
-			innerWidth: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
-			outerHeight: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
-			outerWidth: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
+			innerHeight: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'The height of the current window.' };
+			innerWidth: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'The width of the current window.' };
+			outerHeight: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'The height of the current window with all decoration removed.' };
+			outerWidth: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'The width of the current window with all decoration removed.' };
+			comment: 'The size of the window.';
 		};
 
 		type WorkspaceLoadClassification = {
 			owner: 'bpasero';
-			userAgent: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
-			emptyWorkbench: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
+			userAgent: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The user agent as reported by `navigator.userAgent` by Electron or the web browser.' };
+			emptyWorkbench: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'Whether a folder or workspace is opened or not.' };
 			windowSize: WindowSizeFragment;
-			'workbench.filesToOpenOrCreate': { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
-			'workbench.filesToDiff': { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
-			'workbench.filesToMerge': { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
+			'workbench.filesToOpenOrCreate': { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'Number of files that should open or be created.' };
+			'workbench.filesToDiff': { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'Number of files that should be compared.' };
+			'workbench.filesToMerge': { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'Number of files that should be merged.' };
 			customKeybindingsCount: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
-			theme: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
-			language: { classification: 'SystemMetaData'; purpose: 'BusinessInsight' };
-			pinnedViewlets: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
-			restoredViewlet?: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
-			restoredEditors: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
-			startupKind: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true };
+			theme: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The current theme of the window.' };
+			language: { classification: 'SystemMetaData'; purpose: 'BusinessInsight'; comment: 'The display language of the window.' };
+			pinnedViewlets: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The identifiers of views that are pinned.' };
+			restoredViewlet?: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The identifier of the view that is restored.' };
+			restoredEditors: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'The number of editors that restored.' };
+			startupKind: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; isMeasurement: true; comment: 'How the window was opened, e.g via reload or not.' };
+			comment: 'Metadata around the workspace that is being loaded into a window.';
 		};
 
 		type WorkspaceLoadEvent = {
@@ -141,13 +143,15 @@ export class TelemetryContribution extends Disposable implements IWorkbenchContr
 		if (settingsType) {
 			type SettingsReadClassification = {
 				owner: 'bpasero';
-				settingsType: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
+				settingsType: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The type of the settings file that was read.' };
+				comment: 'Track when a settings file was read, for example from an editor.';
 			};
 
 			this.telemetryService.publicLog2<{ settingsType: string }, SettingsReadClassification>('settingsRead', { settingsType }); // Do not log read to user settings.json and .vscode folder as a fileGet event as it ruins our JSON usage data
 		} else {
 			type FileGetClassification = {
 				owner: 'bpasero';
+				comment: 'Track when a file was read, for example from an editor.';
 			} & FileTelemetryDataFragment;
 
 			this.telemetryService.publicLog2<TelemetryData, FileGetClassification>('fileGet', this.getTelemetryData(e.model.resource, e.reason));
@@ -159,12 +163,14 @@ export class TelemetryContribution extends Disposable implements IWorkbenchContr
 		if (settingsType) {
 			type SettingsWrittenClassification = {
 				owner: 'bpasero';
-				settingsType: { classification: 'SystemMetaData'; purpose: 'FeatureInsight' };
+				settingsType: { classification: 'SystemMetaData'; purpose: 'FeatureInsight'; comment: 'The type of the settings file that was written to.' };
+				comment: 'Track when a settings file was written to, for example from an editor.';
 			};
 			this.telemetryService.publicLog2<{ settingsType: string }, SettingsWrittenClassification>('settingsWritten', { settingsType }); // Do not log write to user settings.json and .vscode folder as a filePUT event as it ruins our JSON usage data
 		} else {
 			type FilePutClassfication = {
 				owner: 'bpasero';
+				comment: 'Track when a file was written to, for example from an editor.';
 			} & FileTelemetryDataFragment;
 			this.telemetryService.publicLog2<TelemetryData, FilePutClassfication>('filePUT', this.getTelemetryData(e.model.resource, e.reason));
 		}