Improve extensions telemetry API

In todays API there are some symbols that help extensions with telemetry, e.g machineId, sessionId, and most importantly isTelemetryEnabled. These are used by our telemetry module and by others.

The existing APIs help you to get the job done but offer little quality of life, aren’t always easy to use, and lack hooks that we would like for transparency and cleansing. Our goal is to make it easy for extensions to do the right thing and to be transparent to our user what’s happening.

Below is an alternative API that is around a TelemetryLogger and TelemetryAppender. The appender is what does the actual data collecting but it should be used through a logger. With that “indirection” we can do many nice things:

• we can do extra PII cleansing for extensions, e.g remove everything that looks like path-name, URI, user-name etc
• we can enable/disable telemetry per extension
• we echo everything that is logged to the telemetry output channel
• we check enablements: logger.logUsage() -> setting say NO ⛔ -> we don’t call appender
• we can call logError on provider-errors and unhandled extension errors (superseeding https://github.com/microsoft/vscode/issues/45264)

declare module 'vscode' {

	export interface TelemetryLogger {
		readonly onDidChangeEnableStates: Event<TelemetryLogger>;
		readonly isUsageEnabled: boolean;
		readonly isErrorsEnabled: boolean;

                // calls TelemetryAppender#logUsage iff usage telemetry is enabled, echos data to output channel
                // called by extension
		logUsage(...args: any[]): void;

                // calls TelemetryAppender#logError iff error telemetry is enabled, echos data to output channel
                // called by extension
                // ALSO called by VS Code when the owning extension throws, e.g provider or command errors
		logError(err: Error): void;
	}

	export interface TelemetryAppender {
		logUsage(...args: any[]): void;
		logError(err: Error): void;
	}

	export namespace env {
		// BYOTA
		export function createTelemetryLogger(appender: TelemetryAppender): TelemetryLogger;
	}
}

The vscode-extension-telemetry-module would become an instance of a telemetry appender.

[bwateratmsft]

I really like this idea, especially unifying all of the PII masking into one better-maintained place. One thing I wanted to bring up, though–there will always be examples of PII that the default filters can’t catch. These could be domain-specific things like resource names, or more generic things like an obscure string ID format that isn’t well known–perhaps an ID that’s unique to a particular country or region.

As such, would it be possible to include a means of adding custom PII filtering logic? e.g. a method or list of methods to pass things through that input a string and output an amended string (or the same string if no changes are needed)?

[isidorn]

Once we get this API in a good proposed state let me know and I can reach out to all extension authors that report telemetry so they slowly start transitioning to this API.