package
A module for Visual Studio Code extensions to report consistent telemetry.
npm install @vscode/extension-telemetryGitHub-flavored package documentation.
Across all versions.
Download trend unavailable.
Runtime metadata.
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.
With npm:
npm install @vscode/extension-telemetry
With yarn:
yarn add @vscode/extension-telemetry
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);
}Use this method for sending general events to App Insights.
// send event any time after activation
reporter.sendTelemetryEvent('sampleEvent', { 'stringProp': 'some string' }, { 'numericMeasure': 123 });Use this method for sending error telemetry as traditional events to App Insights.
Note: To filter out sensitive properties (e.g., stack traces), use replacementOptions in the constructor rather than passing properties to drop as a parameter.
// Configure property filtering in the constructor
import TelemetryReporter from '@vscode/extension-telemetry';
const reporter = new TelemetryReporter(
connectionString,
[
// Remove or redact sensitive properties
{ lookup: /stackProp/, replacementString: '[REDACTED]' },
{ lookup: /sensitiveData/ } // Remove entirely if no replacementString
]
);
// Send error event (properties are automatically filtered based on replacementOptions)
reporter.sendTelemetryErrorEvent(
'sampleErrorEvent',
{ 'stringProp': 'some string', 'stackProp': 'some user stack trace' },
{ 'numericMeasure': 123 }
Route telemetry to non-Azure endpoints (e.g., GitHub telemetry) and configure common properties and static tags:
import TelemetryReporter from '@vscode/extension-telemetry';
import * as os from 'os';
import * as vscode from 'vscode';
const reporter = new TelemetryReporter(
connectionString,
undefined, // replacementOptions
undefined, // initializationOptions
undefined, // customFetch
{
// Custom endpoint URL - route to GitHub, Azure, or other services
endpointUrl: 'https://<somename>-telemetry.githubusercontent.com/telemetry',
// Common properties - automatically added to all events
commonProperties: {
'common_os': os.platform(),
'common_arch': os.arch
When to use constructor options:
For dynamic tags that change per event (e.g., user tracking IDs from authentication tokens):
// Get dynamic tracking ID that changes per event
const trackingId = getTrackingIdFromToken();
// Send event with per-event tag override using the 4th parameter
reporter.sendTelemetryEvent(
'userAction',
{ 'action': 'click' },
{ 'duration': 123 },
{ 'ai.user.id': trackingId } // Overrides user ID for this event only
);
// Error events also support per-event tag overrides
reporter.sendTelemetryErrorEvent(
'errorEvent',
{ 'error': error.message },
{ 'errorCount': 1 },
{ 'ai.user.id': trackingId } // Per-event tag override (4th parameter)
);Tag Merging Priority (lowest to highest):
tagOverrides (static, set at initialization)setContextTag() (can be set after construction)tagOverrides (highest priority, dynamic per event)For edge cases where tags are not available at construction or need to change at runtime:
const reporter = new TelemetryReporter(connectionString);
// Set context tag after construction (e.g., after async initialization)
authService.getSession().then(session => {
reporter.setContextTag('ai.session.id', session.id);
});
// Update tag at runtime (e.g., user switches accounts)
reporter.setContextTag('ai.user.id', 'user1');
// ... later ...
reporter.setContextTag('ai.user.id', 'user2');
// Read back a context tag value
const sessionId = reporter.getContextTag('ai.session.id');When to use setContextTag():
Note: For most use cases, prefer constructor tagOverrides over setContextTag() for better immutability and clarity.
These methods send telemetry without checking the user's telemetry settings. Only use them in controlled environments such as CI pipelines or during development testing.
// Send event without checking telemetry setting
reporter.sendDangerousTelemetryEvent(
'ciPipelineEvent',
{ 'build': 'success' },
{ 'duration': 1234 },
{ 'ai.user.id': trackingId } // Optional tag overrides
);
// Send error event without checking telemetry setting
reporter.sendDangerousTelemetryErrorEvent(
'ciErrorEvent',
{ 'error': 'build failed' },
{ 'errorCount': 1 },
{ 'ai.user.id': trackingId } // Optional tag overrides
);
// Send exception directly to Application Insights exceptions table
// without checking telemetry setting
try {
⚠️ Warning: These methods bypass the user's telemetry opt-in preference. Only use them when you have explicit consent or in non-user-facing scenarios (e.g., automated testing, CI/CD pipelines).
common.extname - The extension namecommon.extversion - The extension versioncommon.vscodemachineid - A common machine identifier generated by VS Codecommon.vscodesessionid - A session identifier generated by VS Codecommon.vscodecommithash - A VS Code commit hashcommon.vscodeversion - The version of VS Code running the extensioncommon.os - The OS running VS Codecommon.platformversion - The version of the OS/Platformcommon.product - What Vs code is hosted in, i.e. desktop, github.dev, codespaces.common.uikind - Web or Desktop indicating where VS Code is runningcommon.remotename - A name to identify the type of remote connection. other indicates a remote connection not from the 3 main extensions (ssh, docker, wsl).common.nodeArch - What architecture of node is running. i.e. arm or x86. On the web it will just say web.lszomoru
lszomoru@microsoft.com
Estimated unpacked size across 11 packages.
127.6 MB
Includes dependencies.
5 direct dependencies.