ads-extension-telemetry

Overview

This module provides a consistent way for first-party extensions to report telemetry over Application Insights.

This is built on top of the vscode-extension-telemetry package, with additional functionality added for usage in Azure Data Studio. (Note that this uses an older version of the module, so make sure to look at the tag for the current version specified in the package.json in this repo - e.g. v0.6.1)

The module respects the user's decision about whether or not to send telemetry data through the telemetry.enableTelemetry setting in Azure Data Studio.

Follow guide to set up Application Insights in Azure and get your key.

Additional Azure Data Studio Functionality

This is a list of the features/changes that have been made:

1. Helper functions for creating & sending view, action, timedAction, metrics and error events
2. Helper functions for adding connection (withConnectionInfo) or server (withServerInfo) properties to events
3. Additional common properties common.adsversion and common.msftinternal

Installation

npm install ads-extension-telemetry

Usage

const vscode = require('vscode');
const TelemetryReporter = require('ads-extension-telemetry');

// all events will be prefixed with this event name
const extensionId = '<your extension unique name>';

// extension version will be reported as a property with each event
const extensionVersion = '<your extension version>';

// the application insights key (also known as instrumentation key)
const key = '<your key>';

// telemetry reporter
let reporter;

function activate(context: vscode.ExtensionContext) {
   ...
   // create telemetry reporter on extension activation
   reporter = new TelemetryReporter(extensionId, extensionVersion, key);
   // ensure it gets property disposed
   context.subscriptions.push(reporter);
   ...
}

function deactivate() {
  // This will ensure all pending events get flushed
   reporter.dispose();
}

...
// send event any time after activation

// Immediately send event
reporter.sendViewEvent('ConnectionDialog');
reporter.sendActionEvent('ConnectionDialog', 'Click', 'OKButton', 'Mouse', 123);
reporter.sendMetricsEvent({ 'dialogLoadTimeMs', 578 }, 'ConnectionDialog');
reporter.sendErrorEvent('ConnectionDialog', 'connectionFailed', '4060', 'SqlException');

// Add on additional properties and then send event
reporter.createViewEvent('ConnectionDialog')
   .withAdditionalProperties( { myProp: 'MyPropValue' })
   .withAdditionalMeasurements( { myMeasure: 123 })
   .withConnectionInfo(connectionProfile)
   .send();

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 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.
• Azure Data Studio Version common.adsversion - The version of Azure Data Studio running this extension
• MSFT Internal common.msftinternal - Whether the user is determined to be an internal MSFT user, this is done by seeing if the USERDNSDOMAIN env var of the user matches one of the well-known MSFT domains

Redacted Properties

All properties are sanitized before sending to try and ensure that no sensitive information is accidently sent. Currently there are 4 types of checks that are done. When a property value is sanitized it will show up as <REDACTED: <name> - e.g. <REDACTED: <user-file-path>

These checks are done using regexes in the vscode-extension-telemetry package, the current usage of which is below for version 0.6.1. Make sure to verify that the current package version matches since otherwise these may be out of date.

User File Path user-file-path - (file:\/\/)?([a-zA-Z]:(\\\\|\\|\/)|(\\\\|\\|\/))?([\w-._]+(\\\\|\\|\/))+[\w-._]* Note this can be a bit overzealous with determining what is or isn't a path - be careful if your values contain / or \ in them otherwise they might get accidently redacted Secret secret - (value is lower-cased) (key|token|sig|signature|password|passwd|pwd|android:value)[^a-zA-Z0-9] E-mail email - @[a-zA-Z0-9-.]+ Token token - xox[pbaors]-[a-zA-Z0-9]+-[a-zA-Z0-9-]+?

Releasing

Release a new version of the extension by:

1. Ensuring all changes are merged in and the package version is updated
2. Create a new Github Release and tag targeting the main branch
3. The CD pipeline will then run and automatically attach the built tgz to the release, go to it and download that file
4. Run npm publish <path to tarball>

License

MIT

Data Collection

The software may collect information about you and your use of the software and send it to Microsoft. Microsoft may use this information to provide services and improve our products and services. You may turn off the telemetry as described in the repository. There are also some features in the software that may enable you and Microsoft to collect data from users of your applications. If you use these features, you must comply with applicable law, including providing appropriate notices to users of your applications together with a copy of Microsoft's privacy statement. Our privacy statement is located at https://go.microsoft.com/fwlink/?LinkID=824704. You can learn more about data collection and use in the help documentation and our privacy statement. Your use of the software operates as your consent to these practices.