development/vscode
development/vscode
1
0
Fork 0
mirror of https://github.com/Microsoft/vscode synced 2024-08-28 21:39:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

Finalize telemetry proposal (#171858)

Browse source
This commit is contained in:
Logan Ramos 2023-01-23 03:44:04 -05:00 committed by GitHub
parent 2a5c10daf0
commit 0ba16b8326
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
4 changed files with 147 additions and 158 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
src/vs/workbench/api/common/extHost.api.impl.ts
View file

@ -337,7 +337,6 @@ export function createApiFactoryAndRegisterActors(accessor: ServicesAccessor): I
return isNewAppInstall(initData.telemetryInfo.firstSessionDate);
},
createTelemetryLogger(sender: vscode.TelemetrySender): vscode.TelemetryLogger {
checkProposedApiEnabled(extension, 'telemetryLogger');
ExtHostTelemetryLogger.validateSender(sender);
return extHostTelemetry.instantiateLogger(extension, sender);
},

1
src/vs/workbench/services/extensions/common/extensionsApiProposals.ts
View file

@ -59,7 +59,6 @@ export const allApiProposals = Object.freeze({
tabInputTextMerge: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.tabInputTextMerge.d.ts',
taskPresentationGroup: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.taskPresentationGroup.d.ts',
telemetry: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.telemetry.d.ts',
telemetryLogger: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.telemetryLogger.d.ts',
terminalDataWriteEvent: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.terminalDataWriteEvent.d.ts',
terminalDimensions: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.terminalDimensions.d.ts',
terminalQuickFixProvider: 'https://raw.githubusercontent.com/microsoft/vscode/main/src/vscode-dts/vscode.proposed.terminalQuickFixProvider.d.ts',

147
src/vscode-dts/vscode.d.ts vendored
View file

@ -9363,6 +9363,15 @@ declare module 'vscode' {
*/
export const onDidChangeTelemetryEnabled: Event<boolean>;
/**
* Creates a new {@link TelemetryLogger telemetry logger}.
*
* @param sender The telemetry sender that is used by the telemetry logger.
* @param options Options for the telementry logger.
* @returns A new telemetry logger
*/
export function createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions): TelemetryLogger;
/**
* The name of a remote. Defined by extensions, popular samples are `wsl` for the Windows
* Subsystem for Linux or `ssh-remote` for remotes using a secure shell.
@ -16672,6 +16681,144 @@ declare module 'vscode' {
*/
close(tabGroup: TabGroup | readonly TabGroup[], preserveFocus?: boolean): Thenable<boolean>;
}
/**
* A special value wrapper denoting a value that is safe to not clean.
* This is to be used when you can guarantee no identifiable information is contained in the value and the cleaning is improperly redacting it.
*/
export class TelemetryTrustedValue<T = any> {
readonly value: T;
constructor(value: T);
}
/**
* A telemetry logger which can be used by extensions to log usage and error telementry.
*
* A logger wraps around an {@link TelemetrySender sender} but it guarantees that
* - user settings to disable or tweak telemetry are respected, and that
* - potential sensitive data is removed
*
* It also enables an "echo UI" that prints whatever data is send and it allows the editor
* to forward unhandled errors to the respective extensions.
*
* To get an instance of a `TelemetryLogger`, use
* {@link env.createTelemetryLogger `createTelemetryLogger`}.
*/
export interface TelemetryLogger {
/**
* An {@link Event} which fires when the enablement state of usage or error telemetry changes.
*/
readonly onDidChangeEnableStates: Event<TelemetryLogger>;
/**
* Whether or not usage telemetry is enabled for this logger.
*/
readonly isUsageEnabled: boolean;
/**
* Whether or not error telemetry is enabled for this logger.
*/
readonly isErrorsEnabled: boolean;
/**
* Log a usage event.
*
* After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetrySender.sendEventData` to log the event.
* Automatically supports echoing to extension telemetry output channel.
* @param eventName The event name to log
* @param data The data to log
*/
logUsage(eventName: string, data?: Record<string, any | TelemetryTrustedValue>): void;
/**
* Log an error event.
*
* After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetrySender.sendEventData` to log the event. Differs from `logUsage` in that it will log the event if the telemetry setting is Error+.
* Automatically supports echoing to extension telemetry output channel.
* @param eventName The event name to log
* @param data The data to log
*/
logError(eventName: string, data?: Record<string, any | TelemetryTrustedValue>): void;
/**
* Log an error event.
*
* Calls `TelemetrySender.sendErrorData`. Does cleaning, telemetry checks, and data mix-in.
* Automatically supports echoing to extension telemetry output channel.
* Will also automatically log any exceptions thrown within the extension host process.
* @param error The error object which contains the stack trace cleaned of PII
* @param data Additional data to log alongside the stack trace
*/
logError(error: Error, data?: Record<string, any | TelemetryTrustedValue>): void;
/**
* Dispose this object and free resources.
*/
dispose(): void;
}
/**
* The telemetry sender is the contract between a telemetry logger and some telemetry service. **Note** that extensions must NOT
* call the methods of their sender directly as the logger provides extra guards and cleaning.
*
* ```js
* const sender: vscode.TelemetrySender = {...};
* const logger = vscode.env.createTelemetryLogger(sender);
*
* // GOOD - uses the logger
* logger.logUsage('myEvent', { myData: 'myValue' });
*
* // BAD - uses the sender directly: no data cleansing, ignores user settings, no echoing to the telemetry output channel etc
* sender.logEvent('myEvent', { myData: 'myValue' });
* ```
*/
export interface TelemetrySender {
/**
* Function to send event data without a stacktrace. Used within a {@link TelemetryLogger}
*
* @param eventName The name of the event which you are logging
* @param data A serializable key value pair that is being logged
*/
sendEventData(eventName: string, data?: Record<string, any>): void;
/**
* Function to send an error. Used within a {@link TelemetryLogger}
*
* @param error The error being logged
* @param data Any additional data to be collected with the exception
*/
sendErrorData(error: Error, data?: Record<string, any>): void;
/**
* Optional flush function which will give this sender a chance to send any remaining events
* as its {@link TelemetryLogger} is being disposed
*/
flush?(): void | Thenable<void>;
}
/**
* Options for creating a {@link TelemetryLogger}
*/
export interface TelemetryLoggerOptions {
/**
* Whether or not you want to avoid having the built-in common properties such as os, extension name, etc injected into the data object.
* Defaults to `false` if not defined.
*/
readonly ignoreBuiltInCommonProperties?: boolean;
/**
* Whether or not unhandled errors on the extension host caused by your extension should be logged to your sender.
* Defaults to `false` if not defined.
*/
readonly ignoreUnhandledErrors?: boolean;
/**
* Any additional common properties which should be injected into the data object.
*/
readonly additionalCommonProperties?: Record<string, any>;
}
}
/**

156
src/vscode-dts/vscode.proposed.telemetryLogger.d.ts vendored
View file

@ -1,156 +0,0 @@
/*---------------------------------------------------------------------------------------------
* Copyright (c) Microsoft Corporation. All rights reserved.
* Licensed under the MIT License. See License.txt in the project root for license information.
*--------------------------------------------------------------------------------------------*/
declare module 'vscode' {
/**
* A special value wrapper denoting a value that is safe to not clean.
* This is to be used when you can guarantee no identifiable information is contained in the value and the cleaning is improperly redacting it.
*/
export class TelemetryTrustedValue<T = any> {
readonly value: T;
constructor(value: T);
}
/**
* A telemetry logger which can be used by extensions to log usage and error telementry.
*
* A logger wraps around an {@link TelemetrySender sender} but it guarantees that
* - user settings to disable or tweak telemetry are respected, and that
* - potential sensitive data is removed
*
* It also enables an "echo UI" that prints whatever data is send and it allows the editor
* to forward unhandled errors to the respective extensions.
*
* To get an instance of a `TelemetryLogger`, use
* {@link env.createTelemetryLogger `createTelemetryLogger`}.
*/
export interface TelemetryLogger {
/**
* An {@link Event} which fires when the enablement state of usage or error telemetry changes.
*/
readonly onDidChangeEnableStates: Event<TelemetryLogger>;
/**
* Whether or not usage telemetry is enabled for this logger.
*/
readonly isUsageEnabled: boolean;
/**
* Whether or not error telemetry is enabled for this logger.
*/
readonly isErrorsEnabled: boolean;
/**
* Log a usage event.
*
* After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetrySender.sendEventData` to log the event.
* Automatically supports echoing to extension telemetry output channel.
* @param eventName The event name to log
* @param data The data to log
*/
logUsage(eventName: string, data?: Record<string, any | TelemetryTrustedValue>): void;
/**
* Log an error event.
*
* After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetrySender.sendEventData` to log the event. Differs from `logUsage` in that it will log the event if the telemetry setting is Error+.
* Automatically supports echoing to extension telemetry output channel.
* @param eventName The event name to log
* @param data The data to log
*/
logError(eventName: string, data?: Record<string, any | TelemetryTrustedValue>): void;
/**
* Log an error event.
*
* Calls `TelemetrySender.sendErrorData`. Does cleaning, telemetry checks, and data mix-in.
* Automatically supports echoing to extension telemetry output channel.
* Will also automatically log any exceptions thrown within the extension host process.
* @param error The error object which contains the stack trace cleaned of PII
* @param data Additional data to log alongside the stack trace
*/
logError(error: Error, data?: Record<string, any | TelemetryTrustedValue>): void;
/**
* Dispose this object and free resources.
*/
dispose(): void;
}
/**
* The telemetry sender is the contract between a telemetry logger and some telemetry service. **Note** that extensions must NOT
* call the methods of their sender directly as the logger provides extra guards and cleaning.
*
* ```js
* const sender: vscode.TelemetrySender = {...};
* const logger = vscode.env.createTelemetryLogger(sender);
*
* // GOOD - uses the logger
* logger.logUsage('myEvent', { myData: 'myValue' });
*
* // BAD - uses the sender directly: no data cleansing, ignores user settings, no echoing to the telemetry output channel etc
* sender.logEvent('myEvent', { myData: 'myValue' });
* ```
*/
export interface TelemetrySender {
/**
* Function to send event data without a stacktrace. Used within a {@link TelemetryLogger}
*
* @param eventName The name of the event which you are logging
* @param data A serializable key value pair that is being logged
*/
sendEventData(eventName: string, data?: Record<string, any>): void;
/**
* Function to send an error. Used within a {@link TelemetryLogger}
*
* @param error The error being logged
* @param data Any additional data to be collected with the exception
*/
sendErrorData(error: Error, data?: Record<string, any>): void;
/**
* Optional flush function which will give this sender a chance to send any remaining events
* as its {@link TelemetryLogger} is being disposed
*/
flush?(): void | Thenable<void>;
}
/**
* Options for creating a {@link TelemetryLogger}
*/
export interface TelemetryLoggerOptions {
/**
* Whether or not you want to avoid having the built-in common properties such as os, extension name, etc injected into the data object.
* Defaults to `false` if not defined.
*/
readonly ignoreBuiltInCommonProperties?: boolean;
/**
* Whether or not unhandled errors on the extension host caused by your extension should be logged to your sender.
* Defaults to `false` if not defined.
*/
readonly ignoreUnhandledErrors?: boolean;
/**
* Any additional common properties which should be injected into the data object.
*/
readonly additionalCommonProperties?: Record<string, any>;
}
export namespace env {
/**
* Creates a new {@link TelemetryLogger telemetry logger}.
*
* @param sender The telemetry sender that is used by the telemetry logger.
* @param options Options for the telementry logger.
* @returns A new telemetry logger
*/
export function createTelemetryLogger(sender: TelemetrySender, options?: TelemetryLoggerOptions): TelemetryLogger;
}
}