Simple telemetry API sample

telemetry-sample/.eslintignore

@@ -0,0 +1,2 @@
+vscode.d.ts
+vscode.proposed.d.ts

telemetry-sample/.eslintrc.js

@@ -0,0 +1,20 @@
+/**@type {import('eslint').Linter.Config} */
+// eslint-disable-next-line no-undef
+module.exports = {
+	root: true,
+	parser: '@typescript-eslint/parser',
+	plugins: [
+		'@typescript-eslint',
+	],
+	extends: [
+		'eslint:recommended',
+		'plugin:@typescript-eslint/recommended',
+	],
+	rules: {
+		'semi': [2, "always"],
+		'@typescript-eslint/no-unused-vars': 0,
+		'@typescript-eslint/no-explicit-any': 0,
+		'@typescript-eslint/explicit-module-boundary-types': 0,
+		'@typescript-eslint/no-non-null-assertion': 0,
+	}
+};

telemetry-sample/.gitignore

@@ -0,0 +1,4 @@
+out
+node_modules
+.vscode-test/
+*.vsix

telemetry-sample/.vscode/launch.json

@@ -0,0 +1,21 @@
+// A launch configuration that compiles the extension and then opens it inside a new window
+// Use IntelliSense to learn about possible attributes.
+// Hover to view descriptions of existing attributes.
+// For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+{
+	"version": "0.2.0",
+	"configurations": [{
+			"name": "Run Extension",
+			"type": "extensionHost",
+			"request": "launch",
+			"runtimeExecutable": "${execPath}",
+			"args": [
+				"--extensionDevelopmentPath=${workspaceFolder}"
+			],
+			"outFiles": [
+				"${workspaceFolder}/out/**/*.js"
+			],
+			"preLaunchTask": "npm: watch"
+		}
+	]
+}

telemetry-sample/.vscode/tasks.json

@@ -0,0 +1,20 @@
+// See https://go.microsoft.com/fwlink/?LinkId=733558
+// for the documentation about the tasks.json format
+{
+	"version": "2.0.0",
+	"tasks": [
+		{
+			"type": "npm",
+			"script": "watch",
+			"problemMatcher": "$tsc-watch",
+			"isBackground": true,
+			"presentation": {
+				"reveal": "never"
+			},
+			"group": {
+				"kind": "build",
+				"isDefault": true
+			}
+		}
+	]
+}

telemetry-sample/package.json

@@ -0,0 +1,51 @@
+{
+	"enabledApiProposals": ["telemetryLogger"],
+	"name": "telemetry-sample",
+	"displayName": "telemetry-sample",
+	"description": "Sample showing how to use Telemetry API",
+	"version": "0.0.1",
+	"publisher": "vscode-samples",
+	"private": true,
+	"license": "MIT",
+	"repository": "https://github.com/Microsoft/vscode-extension-samples",
+	"engines": {
+		"vscode": "^1.73.0"
+	},
+	"categories": [
+		"Other"
+	],
+	"activationEvents": [
+		"onCommand:extension.logEvent",
+		"onCommand:extension.logException"
+	],
+	"main": "./out/extension.js",
+	"contributes": {
+		"commands": [
+			{
+				"command": "extension.logEvent",
+				"title": "Log Telemetry Event"
+			},
+			{
+				"command": "extension.logException",
+				"title": "Log Telemetry Exception"
+			}
+		]
+	},
+	"scripts": {
+		"vscode:prepublish": "npm run compile",
+		"compile": "tsc -p ./",
+		"lint": "eslint . --ext .ts,.tsx",
+		"watch": "tsc -watch -p ./",
+		"download-api": "vscode-dts dev",
+		"postdownload-api": "vscode-dts main",
+		"postinstall": "npm run download-api"
+	},
+	"devDependencies": {
+		"@types/node": "^16.11.7",
+		"@typescript-eslint/eslint-plugin": "^5.40.1",
+		"@typescript-eslint/parser": "^5.40.1",
+		"eslint": "^8.25.0",
+		"typescript": "^4.8.4",
+		"vscode-dts": "^0.3.3"
+	}
+}

telemetry-sample/src/extension.ts

@@ -0,0 +1,38 @@
+import * as vscode from 'vscode';
+
+export function activate(context: vscode.ExtensionContext) {
+	console.log('Congratulations, your extension "telemtry-sample" is now active!');
+
+
+	const appender: vscode.TelemetryAppender = {
+		ignoreBuiltInCommonProperties: false,
+		logEvent: (evenName, data) => {
+			console.log(`Event: ${evenName}`);
+			console.log(`Data: ${JSON.stringify(data)}`);
+		},
+		logException: (exception, data) => {
+			console.log(`Exception: ${exception}`);
+			console.log(`Data: ${JSON.stringify(data)}`);
+		}
+	};
+
+	const logger = vscode.env.createTelemetryLogger(appender);
+
+	/**
+	 * You can use proposed API here. `vscode.` should start auto complete
+	 * Proposed API as defined in vscode.proposed.<proposalName>.d.ts.
+	 */
+
+	const c1 = vscode.commands.registerCommand('extension.logEvent', () => {
+		vscode.window.showInformationMessage('Logged telemetry event!');
+		logger.logUsage('testEvent', { 'testProp': 'testValue' });
+	});
+
+	context.subscriptions.push(c1);
+
+	context.subscriptions.push(vscode.commands.registerCommand('extension.logException', () => {
+		vscode.window.showInformationMessage('Logged telemetry exception!');
+		logger.logError(new Error('Test'), { 'testProp': 'testValue' });
+		logger.logError('testerror', { 'testProp': 'testValue' });
+	}));
+}

telemetry-sample/tsconfig.json

@@ -0,0 +1,12 @@
+{
+	"compilerOptions": {
+		"module": "commonjs",
+		"target": "es2020",
+		"lib": ["es2020"],
+		"outDir": "out",
+		"sourceMap": true,
+		"strict": true,
+		"rootDir": "src"
+	},
+	"exclude": ["node_modules", ".vscode-test"]
+}

telemetry-sample/vscode.proposed.telemetryLogger.d.ts

@@ -0,0 +1,81 @@
+/*---------------------------------------------------------------------------------------------
+ *  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' {
+
+	export interface TelemetryLogger {
+		//TODO feels weird having this on all loggers
+		readonly onDidChangeEnableStates: Event<TelemetryLogger>;
+		readonly isUsageEnabled: boolean;
+		readonly isErrorsEnabled: boolean;
+
+		/**
+		 * After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetryAppender.logEvent` 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, string | number | boolean>): void;
+
+		/**
+		 * After completing cleaning, telemetry setting checks, and data mix-in calls `TelemetryAppender.logEvent` 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, string | number | boolean>): void;
+
+		/**
+		 * Calls `TelemetryAppender.logException`. 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 exception The error object which contains the stack trace cleaned of PII
+		 * @param data Additional data to log alongside the stack trace
+		 */
+		logError(exception: Error, data?: Record<string, string | number | boolean>): void;
+
+		dispose(): void;
+	}
+
+	export interface TelemetryAppender {
+		/**
+		 * Whether or not you want to avoid having the built-in common properties such as os, extension name, etc injected into the data object.
+		 */
+		readonly ignoreBuiltInCommonProperties: boolean;
+
+		/**
+		 * Any additional common properties which should be injected into the data object.
+		 */
+		readonly additionalCommonProperties?: Record<string, string | number | boolean>;
+
+		/**
+		 * User-defined function which logs an event, used within the TelemetryLogger
+		 * @param eventName The name of the event which you are logging
+		 * @param data A serializable key value pair that is being logged
+		 */
+		logEvent(eventName: string, data?: Record<string, string | number | boolean>): void;
+
+		/**
+		 * User-defined function which logs an error, used within the TelemetryLogger
+		 * @param exception The exception being logged
+		 * @param data Any additional data to be collected with the exception
+		 */
+		logException(exception: Error, data?: Record<string, string | number | boolean>): void;
+
+		/**
+		 * Optional flush function which will give your appender one last chance to send any remaining events as the TelemetryLogger is being disposed
+		 */
+		flush?(): void | Thenable<void>;
+	}
+
+	export namespace env {
+		/**
+		 * A wrapper around a TelemetryAppender which provides built-in setting checks, common properties, data cleaning, output channel logging, and internal ext host process exception catching.
+		 * @param appender The core piece which we call when it is time to log telemetry. It is highly recommended that you don't call the methods within the appender directly as the logger provides extra guards and cleaning.
+		 * @returns An instantiated telemetry logger which you can use for recording telemetry
+		 */
+		export function createTelemetryLogger(appender: TelemetryAppender): TelemetryLogger;
+	}
+}