@vscode/extension-telemetry

What is @vscode/extension-telemetry?

@vscode/extension-telemetry is an npm package designed to help developers collect telemetry data from their Visual Studio Code extensions. This data can include events, errors, and performance metrics, which can be used to improve the extension's functionality and user experience.

What are @vscode/extension-telemetry's main functionalities?

Initialize Telemetry Reporter

This feature allows you to initialize a telemetry reporter with your extension's ID, version, and an Application Insights key. This setup is necessary to start collecting telemetry data.

const TelemetryReporter = require('@vscode/extension-telemetry');
const reporter = new TelemetryReporter(extensionId, extensionVersion, aiKey);

Send Telemetry Event

This feature allows you to send a telemetry event with optional properties and measurements. It helps track specific actions or occurrences within your extension.

reporter.sendTelemetryEvent('eventName', { property1: 'value1' }, { metric1: 100 });

Send Telemetry Error

This feature allows you to send error events, which can include additional properties and metrics. It is useful for tracking and diagnosing errors that occur in your extension.

reporter.sendTelemetryErrorEvent('errorName', { errorProperty: 'value' }, { errorMetric: 1 });

Dispose Telemetry Reporter

This feature ensures that all pending telemetry data is sent before the reporter is disposed of. It is important to call this method when your extension is deactivated to ensure no data is lost.

reporter.dispose();

Other packages similar to @vscode/extension-telemetry

applicationinsights

The 'applicationinsights' package is a Node.js SDK for Azure Application Insights, which provides a broader set of features for monitoring and diagnosing applications. While @vscode/extension-telemetry is specifically tailored for VS Code extensions, 'applicationinsights' can be used for a wider range of applications, offering more comprehensive telemetry capabilities.

raven-js

Raven.js is a JavaScript client for Sentry, a popular error tracking and monitoring platform. It provides similar error tracking capabilities as @vscode/extension-telemetry but is more focused on capturing and reporting errors across web applications rather than being specific to VS Code extensions.

winston

Winston is a versatile logging library for Node.js that can be used to log events and errors. While it does not provide telemetry in the same way as @vscode/extension-telemetry, it can be used to log and manage logs in a structured way, which can be useful for debugging and monitoring applications.

README

@vscode/extension-telemetry

This module provides a consistent way for extensions to report telemetry over Application Insights. The module respects the user's decision about whether or not to send telemetry data. See telemetry extension guidelines for more information on using telemetry in your extension.

Follow guide to set up Application Insights in Azure and get your connection string. Don't worry about hardcoding it, it is not sensitive.

Install

With npm: npm install @vscode/extension-telemetry

With yarn: yarn add @vscode/extension-telemetry

Usage

Setup

import * as vscode from 'vscode';
import TelemetryReporter from '@vscode/extension-telemetry';

// the connection string
const connectionString = '<your connection string>';

// telemetry reporter
let reporter;

function activate(context: vscode.ExtensionContext) {
   // create telemetry reporter on extension activation
   reporter = new TelemetryReporter(connectionString);
   // ensure it gets properly disposed. Upon disposal the events will be flushed
   context.subscriptions.push(reporter);
}

Sending Events

Use this method for sending general events to App Insights.

// send event any time after activation
reporter.sendTelemetryEvent('sampleEvent', { 'stringProp': 'some string' }, { 'numericMeasure': 123 });

Sending Errors as Events

Use this method for sending error telemetry as traditional events to App Insights. This method will automatically drop error properties in certain environments for first party extensions. The last parameter is an optional list of case-sensitive properties that should be dropped. If no array is passed, we will drop all properties but still send the event.

// send an error event any time after activation
reporter.sendTelemetryErrorEvent('sampleErrorEvent', { 'stringProp': 'some string', 'stackProp': 'some user stack trace' }, { 'numericMeasure': 123 }, [ 'stackProp' ]);

Common Properties

• Extension Name common.extname - The extension name
• Extension Version common.extversion - The extension version
• Machine Identifier common.vscodemachineid - A common machine identifier generated by VS Code
• Session Identifier common.vscodesessionid - A session identifier generated by VS Code
• VS Code Commit common.vscodecommithash - A VS Code commit hash
• VS Code Version common.vscodeversion - The version of VS Code running the extension
• OS common.os - The OS running VS Code
• Platform Version common.platformversion - The version of the OS/Platform
• Product common.product - What Vs code is hosted in, i.e. desktop, github.dev, codespaces.
• UI Kind common.uikind - Web or Desktop indicating where VS Code is running
• Remote Name common.remotename - A name to identify the type of remote connection. other indicates a remote connection not from the 3 main extensions (ssh, docker, wsl).
• Architecture common.nodeArch - What architecture of node is running. i.e. arm or x86. On the web it will just say web.

License

MIT